基于OAuth2的Xero API按名查询时Tracking Categories为null的解决办法

核心接口限制说明 #

Xero 批量联系人列表接口（GetContactsAsync）的原生设计本身，就不会在批量查询场景下返回联系人关联的 TrackingCategories 字段。该现象和你编写的名称过滤逻辑没有关系，属于接口默认的轻量化返回规则。

实现思路 #

完全保留「按名称检索、匹配所有重名联系人」的核心需求，不需要提前手动收集或录入联系人GUID：

• 第一步：沿用现有代码逻辑，通过名称过滤拉取所有匹配的联系人基础列表，接口返回的基础数据会自动携带每个联系人的 ContactID（即唯一标识GUID）
• 第二步：遍历第一步拿到的联系人列表，逐行调用单条联系人查询接口，使用列表返回的 ContactID 拉取对应联系人的全量详情。单条查询的返回结果会完整包含 TrackingCategories 等批量模式下缺失的嵌套字段
• 第三步：将单条查询拿到的缺失字段同步赋值回原列表对象，即可得到所有匹配名称的联系人的完整详情

代码调整参考 #

在现有代码基础上追加补全逻辑即可，无需修改原有名称检索的查询条件：

List<Contact> contactList = new List<Contact>();
                
var AccountingApi = new AccountingApi();
var response = await AccountingApi.GetContactsAsync(accessToken, xeroTenantId, null,
                                string.Format("FirstName != Null && FirstName.ToLower().Contains(\"{0}\")", "aaron"));

contactList = response._Contacts.ToList();

// 追加字段补全逻辑
foreach (var contact in contactList)
{
    // 直接复用批量查询返回的ContactID，无需手动提前准备GUID
    var fullDetail = await AccountingApi.GetContactAsync(accessToken, xeroTenantId, contact.ContactID);
    // 填充批量查询不返回的TrackingCategories字段
    contact.TrackingCategories = fullDetail.TrackingCategories;
    // 若其他嵌套字段在批量模式下也返回null，可在此处同步赋值
}

关键注意点 #

• 该方案的检索入口依然是按名称匹配，所有联系人GUID都是接口自动返回的，完全规避了「必须提前已知联系人GUID才能查询」的前置要求
• 若单次匹配的联系人数量较多，可适当做并发控制，避免触发Xero的API速率限制（常规租户每分钟可调用60次接口，逐次查询完全在限额范围内）
• 联系人维度关联的追踪类别配置，无需单独调用Tracking Categories独立接口，单条联系人查询即可直接返回对应数据

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