标题： AuthorisationException (403) 即使作用域正确，在更新已合并的联系人时Xero API仍返回403

问题描述：在通过Xero PHP SDK的 updateContact 方法更新联系人时，偶发性地出现 AuthorisationException（403）错误。

背景：

• 工作流： getContacts() -> 修改特定字段 -> updateContact()。
• 权限： 应用使用带有 accounting.contacts 范围的OAuth2，已正确授权。用户具有标准权限，且可以通过网页界面正常修改联系人。
• 根本原因线索： 相关联系人此前曾参与过一次“合并”操作。
• 历史： 我的代码在过去多次成功更新该联系人（在Xero活动历史中的 System Generated 日志已确认）。
• 偶发行为： API会偶尔返回403禁止错误。
• 关键观察： 如果我在Xero的网页界面手动打开该联系人并保存（不做任何修改），API对该联系人的请求会立即恢复工作。这表明网页UI会触发后台元数据/版本同步，而当记录具有“已合并”历史时，API更新请求未能正确处理。

错误响应详情：API在受影响的 ContactID 的 Elements 区块中返回一个 AuthorisationException。

JSON

{
  "ErrorNumber": 23,
  "Type": "AuthorisationException",
  "Message": "An authorisation error has occurred, please check your access permissions.",
  "Elements": [
    {
      "ContactID": "2697bc02-7616-0000-0000-0000000000",
      "AccountNumber": "0210000000",
      "UpdatedDateUTC": "\/Date(1781637616523+0000)\/",
      "AuthorisationError": {
        "Message": "An authorisation error has occurred, please check your access permissions."
      }
    }
  ]
}

我尝试过以下方法：

1. 验证 tenantId 和 AccessToken 的有效性。
2. 验证用户账户权限（已确认具备网页访问权限）。
3. 尝试从有效负载中剥离只读元数据字段（如 UpdatedDateUTC），但偶发错误仍然存在。

环境：

• PHP版本： 8.2
• XeroPHP SDK版本： xeroapi/xero-php-oauth2 v5

问题：

Xero是否对已合并的联系人应用了特定的限制或“版本锁定”机制？为什么在网页前端手动保存会解决API中的 AuthorisationException，并且在没有人工干预的情况下，如何通过SDK处理这种“版本过时”的记录？

解决方案

已发布变更，编辑联系人时应用必须由具备标准权限和银行账户管理员权限的用户进行连接，作为最低要求。这样，当连接应用的用户在Xero前端无法编辑联系人的银行账户字段时，应用就不能对该字段进行编辑。

另外，出于同样的原因，手动分录（manual journals）也有变更，现在只有由具备标准权限和报表权限的用户连接的应用才能发布手动分录。

如果你同时涉及这两个领域，你需要标准权限+ 报表权限+ 银行账户管理员权限，或者由拥有这些权限的其他人来连接应用，而不是你来连接。

https://developer.xero.com/changelog#authorisation-updates-accounting-api