履约财务

履约账户余额、账务流水，以及面向海外开发者的 商业账单发票（overseas commercial invoice）。

可用性： Sandbox / Gateway MOCK 已可用。这不是中国大陆增值税发票接口。

方法	路径	用途
GET	`/v1/fulfillment/balance`	账户余额
GET	`/v1/fulfillment/transactions`	账务流水
GET	`/v1/fulfillment/transactions/{id}`	流水详情
POST	`/v1/fulfillment/invoices`	申请海外发票
GET	`/v1/fulfillment/invoices`	海外发票列表
GET	`/v1/fulfillment/invoices/{id}`	发票详情
GET	`/v1/fulfillment/invoices/{id}/download`	下载发票

金额单位：monetary_unit: CNY_minor。仅可对 AVAILABLE 流水开票。

申请海外发票

面向海外主体的 Bill-to 发票。不区分国内「个人 / 企业」税票类型，也不要求注册地址、开户行等国内专票字段。

字段	必填	说明
`transaction_ids`	是	≥1 个 ID；须为 `AVAILABLE`、同币种
`invoice_title`	是	Bill-to 名称（公司或个人法定名称）
`billing_address`	是	Bill-to 地址（必填 `address1` / `city` / `country_code`；可选 `address2` / `state` / `postal_code`）
`tax_number`	否	海外税号 / VAT ID（如适用）
`email`	否	PDF / 通知投递邮箱
`remark`	否	备注

金额由服务端汇总，不要自报 total。

{
  "transaction_ids": [
    "txn_01K2ABC002",
    "txn_01K2ABC004"
  ],
  "invoice_title": "Acme Trading Co., Ltd.",
  "billing_address": {
    "address1": "88 Gangnam-daero",
    "address2": "Suite 1204",
    "city": "Seoul",
    "state": "Seoul",
    "postal_code": "06236",
    "country_code": "KR"
  },
  "tax_number": "EU123456789",
  "email": "billing@example.com",
  "remark": "August fulfillment charges"
}

流水列表筛选

GET /v1/fulfillment/transactions：参数均为可选。枚举类为单值（不支持逗号多选）；非法枚举 → 422。

参数	匹配	允许值 / 说明
`type`	精确	`CREDIT` · `DEBIT` · `REFUND` · `ADJUSTMENT`
`category`	精确	`TOP_UP` · `PROCUREMENT` · `SHIPPING` · `VALUE_ADDED_SERVICE` · `RETURN` · `STORAGE` · `TRANSFER` · `REFUND` · `MANUAL_ADJUSTMENT` · `OTHER`
`invoice_status`	精确	`NOT_INVOICED` · `AVAILABLE` · `INVOICE_PENDING` · `INVOICED`
`related_resource_type`	精确	`PACKAGE` · `SHIPMENT` · `RETURN` · `SERVICE_REQUEST` · `INBOUND`
`related_resource_id`	精确	关联对象 ID
`created_from` / `created_to`	`created_at` 区间	ISO-8601
`page` / `page_size`	分页	默认 `1` / `20`，`page_size` 最大 `100`

GET /v1/fulfillment/transactions?category=SHIPPING&invoice_status=AVAILABLE&page=1&page_size=20

发票列表筛选

GET /v1/fulfillment/invoices：参数均为可选。status 为单值；非法枚举 → 422。

参数	匹配	允许值 / 说明
`status`	精确	`PENDING`（待开具）· `ISSUED`（已开具，可下载）· `REJECTED`（已拒绝）· `CANCELLED`（已取消）
`created_from`	`created_at >=`	ISO-8601（申请时间）
`created_to`	`created_at <=`	ISO-8601
`issued_from`	`issued_at >=`	ISO-8601；无 `issued_at` 的记录会被排除
`issued_to`	`issued_at <=`	同上
`page` / `page_size`	分页	默认 `1` / `20`，最大 `100`

created_* 与 issued_* 可同时使用（AND）。只看可下载发票用 status=ISSUED。

GET /v1/fulfillment/invoices?status=ISSUED&issued_from=2026-08-01T00:00:00Z&page=1&page_size=20

获取支持

需要集成帮助？请联系开发者支持 support@hiobuy.com · 预计 1–2 个工作日内回复

发送邮件