接 Xero：拉订单、客户、发票与产品，查库存

在 developer.xero.com 为您的应用走完 OAuth2 流程（带三项 read scope），从 connections 列表复制 Tenant ID，把两个值粘进 Integration，测试、配 Mapping、激活。

Xero 连接器把您 Xero 组织里的订单、客户、发票与产品拉进本系统，能把客户、产品与发票推回 Xero，还能通过 Xero 的 Items 查库存数量。它不把库存变化推回 Xero：本连接里库存只读。一个连接对应一个 Xero 组织，用 Tenant ID 识别。

前置条件#

• 一个能登录的 Xero 组织，以及在 developer.xero.com 上为它注册的一个应用。
• 您能在 developer.xero.com 为该应用走完 OAuth2 流程，并授予全部三项 read scope：accounting.transactions.read、accounting.contacts.read、accounting.settings.read。缺任何一项的 token，测试或拉取都会失败。
• 您清楚这个连接对接哪个组织。Tenant ID 是组织的 ID，不是应用的 ID——两个值不同、不能混用。

拿凭证#

1. 打开 developer.xero.com，进入您的应用，走完 OAuth2 流程。Xero 要求选 scope 时，至少包含 accounting.transactions.read、accounting.contacts.read、accounting.settings.read 三项。
2. 复制 OAuth2 流程返回的 access token。这个 token 就是要粘进 Integration 的值——本连接没有另外要建的 API Key。
3. Tenant ID 有两种取法：用 access token 调 GET https://api.xero.com/connections，从返回里复制您组织的 tenantId；或打开 developer.xero.com → 您的应用 → connections，在那里看 tenantId。

填进 Integration#

1. 打开 Integration → 连接器市场 → Xero → 新建连接。
2. tenant_id——必填，Tenant ID（组织）：粘贴您组织的 tenantId，形如 xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx。它是 connections 列表里的组织 ID，不是应用 ID。
3. access_token——必填，Access token：完整粘贴 OAuth2 流程返回的 access token。这是密码类型字段，作为秘密保存。请确认该 token 授予时包含 accounting.transactions.read、accounting.contacts.read、accounting.settings.read。

测试连接#

点测试连接。测试会向 GET https://api.xero.com/api.xro/2.0/Organisation 发一个真实请求，带两个头：Authorization: Bearer 加您的 access token，以及 xero-tenant-id 加您的 tenant_id。返回 200 才算测通，结果里会显示 Xero 返回的组织名，您可以确认是不是要接的那个组织。401 表示 token 无效或已过期；403 表示 token 的 scope 不足。tenant_id 或 access_token 缺失时，测试在发出请求前就会停下，因为这个探针两个值缺一不可。探针 12 秒超时。

配 Mapping / 选模板#

选 Xero 标准 Mapping。订单、客户与发票按 Xero Accounting 的标准记录走，产品与库存查询按 Xero 的 Items 走。测试通过后先拉一次，把一个真实订单对照核对——订单号、客户、明细行与金额——再用同样方式核一张发票和一个产品，并拿一个 item 的数量和 Xero 里显示的对一遍，确认后再激活。

激活#

激活后，连接按您设的频率，从 tenant_id 指定的 Xero 组织拉订单、客户、发票与产品；相关流程运行时把客户、产品与发票推回 Xero；查库存时从 Xero 的 Items 读数量。先在 运行监控 / 日志里盯头几次运行、和 Xero 对照无误，再放手跑。

这个连接不做的事：不把库存变化推回 Xero。Xero Items 里的数量只读来核对，库存调整仍需在 Xero 里做，或在实际发生调整的系统里做。

常见问题#

测试报 401——token 无效或已过期

Xero 拒的是 access token 本身：填错了、粘贴不全，或已经失效。这种情况下组织探针连鉴权都过不了，所以先别查 tenant_id。

回 developer.xero.com → 您的应用，重新走一遍 OAuth2 流程，把新拿到的 access token 完整复制进 access_token 字段，再重新测试。

测试报 403——scope 不足

token 被接受了，但授予时没带上本连接需要的 read scope。必需的三项是 accounting.transactions.read、accounting.contacts.read、accounting.settings.read——缺任何一项都可能报这个错。

在 developer.xero.com 为您的应用重走 OAuth2 流程，这次把三项 scope 全部授予，把新 access token 粘进 Integration 再测试。不要只重粘旧 token——它的 scope 不会变。

token 是对的，但测试还是失败——组织不对

tenant_id 不属于这个 token 被授权的组织。探针把您的 tenant_id 放在 xero-tenant-id 头里发过去，Xero 只按那个组织应答——token 有效但配了别的组织的 ID，就会在这里失败；测通时结果里的组织名就是核对是否选对组织的依据。

重新复制目标组织的 tenantId：用 access token 调 GET https://api.xero.com/connections，从返回里选该组织的 tenantId；或在 developer.xero.com → 您的应用 → connections 里读。替换 tenant_id、保存、重新测试——然后确认显示的组织名对得上。

测试在发出前就停下——有必填值缺失

tenant_id 或 access_token 是空的。组织探针两个都要：token 进 Authorization 头，tenant_id 进 xero-tenant-id 头，所以测试会直接停下，而不是发一个注定失败的请求。

按填进 Integration 一节把两个字段补全——tenant_id 从 connections 列表取、access_token 完整粘贴——保存后重新测试。

连接成功，但 Xero 里的库存数量从来不变

这是本连接的能力边界，不是故障：库存是从 Xero 的 Items 读来核对的，库存变化不推回 Xero。订单、客户、发票与产品按上文所述流动；Xero 里的库存数量仍由 Xero 管。

库存调整请在 Xero 里做，或在实际发生调整的系统里做；做完后用本连接的库存查询核对数量。

测试 12 秒后超时

组织探针没有在规定时间内收到 Xero 的应答。这是去 api.xero.com 的通路或响应问题，不是 token 或 tenant_id 的判定——两个值实际上都还没被验到。

等一会儿，用同样的两个值再点一次测试连接。如果反复超时而其他连接测试正常，先记下时间和 运行监控 / 日志里的确切报错，再考虑改值。