本文将指导开发者如何通过Xero Payroll API获取工资单列表。由于Xero API不支持直接获取所有工资单的列表，需要组合使用Payruns端点和Payslip端点。以下是详细步骤和注意事项，帮助开发者高效地集成Xero工资单数据。
步骤一：获取Payruns列表
首先，需要调用Payruns端点来获取包含工资单信息的Payrun ID。Payruns端点允许您检索特定时间段内的所有工资单运行记录。
GET https://api.xero.com/payroll.xro/1.0/Payruns
您可以使用查询参数来过滤特定时间段内的Payruns。例如，要获取2023年1月1日至2023年12月31日之间的所有Payruns，可以使用fromDate和toDate参数：
GET https://api.xero.com/payroll.xro/1.0/Payruns?fromDate=2023-01-01&toDate=2023-12-31
响应将包含一个Payruns数组，每个Payrun对象都包含一个唯一的ID。
步骤二：获取每个Payrun的工资单ID列表
对于每个Payrun ID，您需要调用Payrun端点来获取与该Payrun关联的工资单ID列表。
GET https://api.xero.com/payroll.xro/1.0/Payruns/{PayrunID}将 {PayrunID} 替换为实际的Payrun ID。例如：
GET https://api.xero.com/payroll.xro/1.0/Payruns/a8f2a4a8-9b2b-4c5a-8d7d-1a2b3c4d5e6f
响应将包含有关该Payrun的详细信息，包括与该Payrun关联的工资单ID列表。
步骤三：获取每个工资单的详细信息
对于每个工资单ID，您需要调用Payslip端点来获取该工资单的详细信息。
GET https://api.xero.com/payroll.xro/1.0/Payslip/{PayslipID}将 {PayslipID} 替换为实际的工资单ID。例如：
GET https://api.xero.com/payroll.xro/1.0/Payslip/5037f8ef-e9b5-40a6-9ec1-0f6f7ebb4787
响应将包含有关该工资单的详细信息，包括员工姓名、工资、税款等。
示例代码 (Python)
以下是一个使用Python的requests库来获取工资单列表的示例代码：
import requests
# Xero API凭证
ACCESS_TOKEN = "YOUR_ACCESS_TOKEN"
XERO_TENANT_ID = "YOUR_XERO_TENANT_ID"
# 设置请求头
headers = {
"Authorization": f"Bearer {ACCESS_TOKEN}",
"Xero-Tenant-Id": XERO_TENANT_ID,
"Content-Type": "application/json"
}
def get_payruns(from_date, to_date):
"""获取指定时间段内的Payruns列表"""
url = f"https://api.xero.com/payroll.xro/1.0/Payruns?fromDate={from_date}&toDate={to_date}"
response = requests.get(url, headers=headers)
response.raise_for_status() # 检查请求是否成功
return response.json()["Payruns"]
def get_payslips_from_payrun(payrun_id):
"""获取指定Payrun ID的工资单ID列表"""
url = f"https://api.xero.com/payroll.xro/1.0/Payruns/{payrun_id}"
response = requests.get(url, headers=headers)
response.raise_for_status()
return response.json()["Payrun"]["Payslips"]
def get_payslip_details(payslip_id):
"""获取指定工资单ID的详细信息"""
url = f"https://api.xero.com/payroll.xro/1.0/Payslip/{payslip_id}"
response = requests.get(url, headers=headers)
response.raise_for_status()
return response.json()["Payslip"]
# 主程序
if __name__ == "__main__":
from_date = "2023-01-01"
to_date = "2023-12-31"
payruns = get_payruns(from_date, to_date)
all_payslips = []
for payrun in payruns:
payrun_id = payrun["PayrunID"]
payslips = get_payslips_from_payrun(payrun_id)
for payslip in payslips:
payslip_id = payslip["PayslipID"]
payslip_details = get_payslip_details(payslip_id)
all_payslips.append(payslip_details)
# 打印所有工资单的详细信息
for payslip in all_payslips:
print(payslip)注意事项:
- 确保替换YOUR_ACCESS_TOKEN和YOUR_XERO_TENANT_ID为您的实际Xero API凭证。
- Xero API有速率限制，请注意控制请求频率，避免触发速率限制。 可以通过查看响应头部的 X-Rate-Limit-Remaining 和 X-Rate-Limit-Reset 来了解当前速率限制情况。
- 异常处理：在实际应用中，需要添加更完善的错误处理机制，例如捕获requests.exceptions.HTTPError异常。
- 分页： 如果payruns 数量很多，需要考虑Payruns API 的分页机制，通过 page 参数来获取所有Payruns。
总结
虽然Xero API目前不支持直接获取所有工资单的列表，但通过组合使用Payruns端点和Payslip端点，我们可以实现此目的。 请注意速率限制和错误处理，并根据实际情况进行优化。 通过本文档，您应该能够成功地集成Xero工资单数据到您的系统中。
