会计导出

会计导出 API 提供可用于对账的订单、支付、结算和退款视图——为与支付服务商(如 Airwallex)银行结算单自动对账的记账流程而设计。

端点

GET  /api/v1/accounting/orders
POST /api/v1/accounting/sync-settlements

认证: 使用 API key(非 JWT)。导出需要 exports:read 作用域 (或 read 通配);结算同步需要 exports:write(或 write/ admin)。作用域机制见 API 密钥。

GET /accounting/orders

查询参数:

参数	说明
`since`	ISO-8601;`updated_at` 的包含下界。增量拉取会重新输出状态变化(pending→settled、新退款)。
`until`	ISO-8601;`updated_at` 的包含上界
`cursor`	来自 `next_cursor` 的不透明分页游标(基于 `(updated_at, id)` 的 keyset)
`test`	`all`(默认)/ `only` / `exclude` —— 测试模式订单
`payment_status`	按支付尝试状态过滤:`pending` / `succeeded` / `failed` / `cancelled` / `refunded`
`limit`	页大小(默认 200,最大 1000)

响应结构 —— data[] 加 next_cursor:

每个订单包含:

order_id —— 稳定的店铺前缀引用(SHOP-1001、SHOP-1002), 取自订单的 invoice_number。它与 Xero 账单号以及支付服务商元数据中的 order_id 一致。
store —— 来自 [accounting] store_name 的店铺名(缺省回退到配置的品牌名)。
test —— 布尔值;测试模式交易(仍可能动真钱,必须可记账)。
items[] —— SKU、名称、数量、单价。
payments[] —— 每次支付尝试一条:服务商 ID(intent_id 即 pi_… intent,attempt_id 即 ftx_… attempt)、状态 (pending|succeeded|failed|cancelled)、总额 amount、逐项列出的 fee.components[]、net,以及结算后的 settlement_id、 settled_at、settlement_currency 和 fx_rate。
refunds[] —— 每条关联其父 attempt_id,含状态和 settled_at。

对账不变量

支付服务商按批次结算。关联键是 settlement_id:

共享同一 settlement_id 的所有成功支付的 net 之和,精确到分等于服务商对账单上的一笔入金。

如果某笔支付 settlement_id: null,说明尚未结算——不要纳入入金匹配,等 settled_at 推进后重新拉取。

POST /accounting/sync-settlements

通过拉取 Airwallex pa/settlement_records,把费用和结算批次 ID 回填到支付记录上(并把 settled_at 回填到退款上)。

{ "limit": 500 }

limit —— 最多查询多少笔未结算的 payment intent(0 或缺省表示全部)。积压量大时请用有界的 limit。
返回 { queried, payments_updated, refunds_updated, not_settled, unmatched }。

需要已配置 Airwallex,否则返回 400 {"error": "Airwallex is not configured"}。

配置

[accounting]
store_code = "SHOP"     # 账单/订单引用和服务商元数据中的短代码
store_name = "My Shop"  # 会计导出中的店铺标签
site_url = "https://shop.example.com"  # 嵌入支付服务商元数据

示例

curl -H "Authorization: Bearer ak_1a2b3c4d.x9y8..." \
  "https://api.shop.example.com/api/v1/accounting/orders?since=2026-10-01T00:00:00Z&test=exclude"

为自动化创建密钥(secret 只显示一次):

rcommerce api-key create --name "accounting-export" --scopes "exports:read,exports:write"