Xero API发票端点无法获取完整联系人详情的技术问询

使用Xero API以JSON格式提取发票数据时，能获取发票本身的大量信息，但Contact对象中的Addresses、Phones、ContactGroups及ContactPersons等嵌套结构始终返回空数组[]。已将发票端点的查询参数summaryOnly设为false以确保获取详细数据，咨询：是否需启用其他参数或设置来获取完整联系人详情？这是否是Xero中数据存储/配置问题或API限制？是否有可行的解决办法或替代端点可获取该信息？

JSON输出片段：

"Contact": {
   "ContactID": "example-id",
   "Name": "Sample Name",
   "Addresses": [],
   "Phones": [],
   "ContactGroups": [],
   "ContactPersons": [],
   ...
}

核心原因：API端点的设计限制 #

发票端点（GET /api.xro/2.0/Invoices）的summaryOnly参数仅控制发票自身字段的返回粒度，不会影响关联联系人的嵌套数据返回。该接口默认只返回联系人的核心标识字段（如ContactID、Name），不会附带地址、电话等详细嵌套结构，这是Xero API的设计逻辑。

可行解决办法 #

1. 单独调用联系人详情端点 #

利用发票返回的ContactID，单独请求联系人详情接口，获取完整的联系人数据：

GET /api.xro/2.0/Contacts/{ContactID}

这个接口会返回该联系人的所有字段，包括Addresses、Phones、ContactGroups、ContactPersons等嵌套结构。

2. 批量获取联系人数据 #

如果需要处理多个发票的联系人信息，可收集所有目标ContactID，通过批量查询接口一次性获取：

GET /api.xro/2.0/Contacts?IDs=contact-id-1,contact-id-2,contact-id-3

这种方式能减少请求次数，提升效率。

排查其他可能原因 #

1. 确认Xero后台的联系人数据 #

先登录Xero后台，查看对应联系人的详情页，确认Addresses、Phones等信息是否已正确录入。如果后台本身没有这些数据，API自然会返回空数组。

2. 检查API应用权限 #

在Xero开发者门户的应用权限设置中，确认你的应用已勾选Contacts的Read权限。权限不足会导致联系人接口无法返回完整数据。

内容的提问来源于stack exchange，提问作者Sentinal