xero api在设计上并未提供一个单一的端点来直接获取所有薪资单的列表。这种设计模式通常是为了优化性能和管理api调用负载，特别是在处理大量数据时。因此，要获取组织内的所有薪资单，开发者需要采用一种分阶段的策略，即先获取薪资运行（payrun）信息，再通过薪资运行获取其下的薪资单id，最后逐个查询薪资单详情。这种方法虽然需要多次api调用，但能确保数据的一致性和准确性。
分步指南：获取Xero薪资单列表
以下是实现Xero组织内所有薪资单列表获取的详细步骤。
步骤一：获取薪资运行（Payrun）列表
首先，您需要调用Xero Payroll API的Payruns端点来获取所有或特定时间范围内的薪资运行记录。薪资运行代表了一个支付周期内所有员工的薪资处理批次。
API 端点示例：
GET https://api.xero.com/payroll.xro/1.0/Payruns
可能的查询参数：
- If-Modified-Since: 用于获取自上次查询后有更新的薪资运行。
- status: 过滤薪资运行的状态（例如，DRAFT, POSTED, PAID）。
- periodStartDate, periodEndDate: 按薪资周期日期范围过滤。
示例响应结构（部分）：
{
"Payruns": [
{
"PayRunID": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
"PayRunPeriodStartDate": "2023-01-01T00:00:00",
"PayRunPeriodEndDate": "2023-01-15T00:00:00",
"PayRunStatus": "POSTED",
"PayRunType": "Scheduled",
"PaymentDate": "2023-01-15T00:00:00",
"Wages": 10000.00,
"Deductions": 1000.00,
"NetPay": 9000.00
},
// ... 更多 Payrun 对象
]
}从这个响应中，您将提取每个PayRunID，这些ID将用于下一步。
步骤二：获取每个薪资运行中的薪资单ID
在获取了相关的PayRunID之后，您需要对每个PayRunID进行单独调用，以获取该薪资运行下包含的所有薪资单（Payslip）的ID。
API 端点示例：
GET https://api.xero.com/payroll.xro/1.0/Payruns/{PayRunID}/Payslips将{PayRunID}替换为您在步骤一中获取到的具体薪资运行ID。
示例响应结构（部分）：
{
"Payslips": [
{
"PayslipID": "5037f8ef-e9b5-40a6-9ec1-0f6f7ebb4787",
"EmployeeID": "employee-uuid-1",
"FirstName": "John",
"LastName": "Doe",
"NetPay": 1500.00,
"Status": "DRAFT"
},
{
"PayslipID": "b1c2d3e4-f5a6-7890-1234-567890fedcba",
"EmployeeID": "employee-uuid-2",
"FirstName": "Jane",
"LastName": "Smith",
"NetPay": 1600.00,
"Status": "POSTED"
}
// ... 更多 Payslip 摘要对象
]
}此响应将为您提供每个薪资运行中包含的PayslipID列表。
步骤三：逐一查询薪资单详情
最后一步是利用在步骤二中获取到的每个PayslipID，逐一调用单个薪资单详情端点，以获取完整的薪资单数据。
API 端点示例：
GET https://api.xero.com/payroll.xro/1.0/Payslip/{PayslipID}将{PayslipID}替换为您在步骤二中获取到的具体薪资单ID。
示例响应结构（部分）：
{
"Payslip": {
"PayslipID": "5037f8ef-e9b5-40a6-9ec1-0f6f7ebb4787",
"EmployeeID": "employee-uuid-1",
"FirstName": "John",
"LastName": "Doe",
"PayslipPeriodStartDate": "2023-01-01T00:00:00",
"PayslipPeriodEndDate": "2023-01-15T00:00:00",
"NetPay": 1500.00,
"Tax": 300.00,
"EarningsLines": [
{
"EarningsLineID": "earnings-uuid-1",
"Description": "Regular Hours",
"Rate": 25.00,
"NumberOfUnits": 80.00,
"Amount": 2000.00
}
],
"DeductionLines": [
{
"DeductionLineID": "deduction-uuid-1",
"Description": "401K Contribution",
"Amount": 200.00
}
],
"SuperannuationLines": [
{
"SuperannuationLineID": "super-uuid-1",
"Description": "Employer Contribution",
"Amount": 100.00
}
]
}
}通过重复此步骤，您可以收集到所有目标薪资单的完整详细信息。
注意事项
在实施上述策略时，请考虑以下几点以确保系统的健壮性和效率：
- API 速率限制（Rate Limiting）：由于需要进行多次API调用，请务必了解Xero API的速率限制。过度频繁的请求可能会导致您的应用被暂时阻止。建议在连续调用之间加入适当的延迟，或采用指数退避（Exponential Backoff）策略处理速率限制错误。
- 数据量与性能：如果您的Xero组织拥有大量薪资运行和员工，此过程可能会涉及大量的API调用和数据处理。考虑对数据进行分页处理，或仅获取所需时间范围内的薪资单，以减少处理负载。
- 错误处理：在每次API调用中都应实现完善的错误处理机制。例如，处理网络错误、无效ID错误或Xero API返回的其他错误状态码。
- 权限管理：确保您的Xero API集成具有访问payroll.payslip和payroll.payruns资源的必要权限。通常，这需要在Xero应用配置中授予payroll.payslip和payroll.payruns的读/写权限。
- 数据存储与更新：考虑如何存储和更新获取到的薪资单数据。如果您的系统需要实时数据，可能需要定期执行此同步过程；如果只需要历史数据，则可以一次性获取并存储。
总结
尽管Xero API不提供直接获取所有薪资单的单一接口，但通过分步查询薪资运行、获取薪资单ID，再逐一获取薪资单详情的策略，开发者仍然可以有效地集成并获取所需的薪资单数据。理解并遵循上述步骤和注意事项，将帮助您构建一个稳定、高效的Xero薪资单集成方案。
