Xero薪资单列表获取策略：通过Payrun API分步查询-js教程-PHP中文网

Xero薪资单列表获取策略：通过Payrun API分步查询

碧海醫心

发布： 2025-09-13 17:01:01

原创

1035人浏览过

Xero薪资单列表获取策略：通过Payrun API分步查询

本教程详细阐述了如何通过Xero API获取组织内的所有薪资单列表。由于Xero API不提供直接获取所有薪资单的单一接口，用户需要首先查询薪资运行（Payrun）列表，然后针对每个薪资运行获取其包含的薪资单ID，最终逐一查询以获取完整的薪资单详情。

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: 按薪资周期日期范围过滤。

示例响应结构（部分）：

AI大学堂

科大讯飞打造的AI学习平台

179

查看详情

{
  "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的读/写权限。
数据存储与更新：考虑如何存储和更新获取到的薪资单数据。如果您的系统需要实时数据，可能需要定期执行此同步过程；如果只需要历史数据，则可以一次性获取并存储。