使用Xero API summaryOnly参数获取联系人列表不全问题咨询

数据老陈

2026-7-29

问题解答

核心原因：API分页机制导致数据不完整

Xero的/Contacts接口（无论是否带summaryOnly=true）默认采用分页返回，每页最多返回100条记录。你看到的53KB数据只是第一页的精简结果，并非系统内全部联系人，不存在所谓“未公开特性”过滤数据的情况。

验证方法

检查API响应头中的X-Total-Count字段，该字段会返回联系人总条数。如果你当前获取的条目数小于这个值，就说明还有后续分页数据未获取。

解决办法

1. 处理分页获取全部精简联系人（PHP SDK实现）

循环请求接口，每次递增page参数，直到获取的总条目数等于X-Total-Count：

$allContacts = [];
$currentPage = 1;
$tenantId = "你的租户ID";

do {
    // 调用带summaryOnly和page参数的接口
    $response = $xeroClient->accountingApi->getContacts(
        $tenantId,
        null,       // where条件，留空则获取全部
        true,       // summaryOnly=true
        null,
        null,
        $currentPage // 指定页码
    );
    
    // 合并当前页的联系人数据
    $allContacts = array_merge($allContacts, $response->getContacts());
    
    // 从响应头获取总记录数
    $totalCount = (int)$response->getHeaders()['X-Total-Count'][0];
    $currentPage++;
} while (count($allContacts) < $totalCount);

2. 结合`where`参数优化模糊搜索（推荐）

直接用Xero API的where查询实现模糊匹配，替代本地过滤，能大幅减少返回数据量，配合summaryOnly=true效率更高：

$searchString = "要搜索的关键词";
$whereClause = "ContactName.Contains(\"{$searchString}\")";
$tenantId = "你的租户ID";

// 调用带where和summaryOnly的接口
$response = $xeroClient->accountingApi->getContacts(
    $tenantId,
    $whereClause,
    true
);

$matchedContacts = $response->getContacts();