用途
本技能用于通过 Xero 官方 REST API 执行会计与财务管理操作。当用户提到「Xero」「会计」「发票」「记账」或询问财务管理时适用。
主要能力
- 组织信息：获取组织信息（名称、法定名称、本位币、国家代码、财年结束日/月、税号、时区、期间锁定日期等，均为只读），以及查询允许的操作（返回 Name 与 Status，Status 为 ALLOWED 或 NOT-ALLOWED）。
- 联系人：分页列出、按 searchTerm 搜索（覆盖 Name、FirstName、LastName、ContactNumber、CompanyNumber、EmailAddress）、按 where 过滤（优化字段：Name、EmailAddress、AccountNumber）、按 ID 获取、创建、更新、归档。联系人不能删除，只能归档；列表请求可用 includeArchived=true 查看已归档联系人。
- 联系人组：列出、创建、向组添加联系人、从组移除联系人、删除组。
- 发票：列出（不带 page 仅返回摘要，无行项目；加 page=1 返回完整详情）、按状态/联系人等过滤、按 ID 或发票号获取、获取在线发票 URL（仅限非草稿的 ACCREC 发票）、创建销售发票（ACCREC）与账单（ACCPAY）、创建带折扣与跟踪类别的发票、更新状态（批准）、作废发票、通过邮件发送发票。
- 信用票据：列出、创建（ACCRECCREDIT 客户信用或 ACCPAYCREDIT 供应商信用）、分配到发票（需先为 AUTHORISED 状态）。
- 报价单：列出（可按状态、联系人、日期范围等过滤）、创建、更新状态。
- 采购订单：列出、创建、更新。
- 付款：列出、针对发票创建付款、针对信用票据创建付款、删除付款（付款不能修改，只能删除；批量创建的付款不能删除）、列出批量付款。
- 银行交易：分页列出、过滤、创建支出（SPEND）等交易。
使用方式
所有 Xero API 调用都需要 xero-tenant-id 请求头。首先通过 Connections 端点获取租户 ID：
curl -s "https://api.xero.com/Connections" \
--header "Authorization: Bearer $XERO_TOKEN" \
--header "Content-Type: application/json"
响应返回已连接组织的数组，使用第一个（或所需）条目的 tenantId，并在后续所有请求中作为 xero-tenant-id 请求头使用。
请求统一使用 Authorization: Bearer $XERO_TOKEN 与 xero-tenant-id 请求头。创建/更新操作使用 PUT 或 POST，请求体为 JSON。
故障排查
如果请求失败，可运行：
zero doctor check-connector --env-name XERO_TOKEN
或
zero doctor check-connector --url https://api.xero.com/Connections --method GET
适用场景
- 查询组织与财务基础信息。
- 管理客户与供应商联系人及分组。
- 创建、查询、批准、作废销售发票与账单。
- 处理信用票据及其分配。
- 管理报价单与采购订单。
- 记录与删除付款、查询批量付款。
- 查询与创建银行交易。
限制
- 联系人不能删除，只能归档。
- 发票状态流转：DRAFT -> SUBMITTED -> AUTHORISED -> PAID（全额付款时由系统分配）；AUTHORISED 可作废为 VOIDED；DRAFT/SUBMITTED 可删除。仅 AUTHORISED 发票可作废。
- 在线发票 URL 仅适用于非 DRAFT 的 ACCREC 发票。
- ACCPAY（账单）不支持 DiscountRate/DiscountAmount。
- 邮件发送发票需要付费 Xero 套餐，成功返回 204；限额：付费 1000/天，试用 20/天，演示 0/天。
- 付款不能修改，只能删除；批量创建的付款不能删除。
- 付款金额不得超过未结余额。
- 更新采购订单时，现有行项目需包含 LineItemID 才能更新，省略则会删除并重建该行项目。
- 更新报价单状态时，即使仅更新状态，Contact 与 Date 也为必填。
- 信用票据分配到发票前必须为 AUTHORISED 状态。
- 创建联系人时 Name 为必填（最多 255 字符），ContactPersons 最多 5 个。
- 采购订单列表 pageSize 最大 1000。
- 具体收费、价格与套餐细节暂未提供。