履约 API 响应模型

标准响应（省略 response_format 或 "standard"）会带顶层字段：

字段	值	含义
`monetary_unit`	`"CNY_minor"`	响应中每个 `{ amount, currency }` 的 `amount` 均为人民币分；1 元 = 100 分

出现在带金额的接口：余额、运费估算、创建、取消（含 refund）、列表、详情、服务。支付、物流轨迹、物品属性，以及 response_format: "upstream" 不带此字段。

运费试算 — quotes[] {#freight-estimate-quotes}

完整请求/响应见运费试算。渠道目录见运输渠道。展示语言只用 Language Header，不要写在 Body 或 Query。

字段	说明
`channel.code` / `name` / `description` / `tags`	稳定渠道身份。创建发货单时用 `code`，不要依赖 `name`
`available` / `quote_status`	必须同时判断。`UNAVAILABLE` 是单个渠道结果，不是 HTTP 错误
`unavailable_reason`	`{ code, message }` 或 `null`。程序判断用 `code`
`matched_region`	`{ code, name, match_type }`
`packages` / `weights`	申报包裹；`actual` / `volumetric` / `chargeable`，单位 `KG`
`billing_quantity` / `pricing_selector`	渠道实际计费数量与单位（`KG` / `M3` / `KG_PER_M3`）
`transit_time`	参考时效
`charges`	`base_freight` / `channel_services` / `channel_rules` / `outbound_services` / `inbound_services` / `adjustments`
`display_charges`	可能仅用于前端；`included_in_total=false` 时不要再加进 `total`
`total` / `known_total`	完整预算 vs 当前已知费用。`total=null` 时不能把 `known_total` 当完整报价
`service_adjustment_possible`	仓库处理后服务和费用仍可能调整
`monetary_unit`	固定 `CNY_minor`

创建 — pricing {#preview-create-pricing}

字段	说明
`freight`	国际干线运费
`services`	增值服务合计
`discount`	促销扣减
`total` / `total.payment`	`freight + services − discount`
`id` / `order_sn`	创建响应：Public `id` 取仓库数字主键（字符串）；`order_sn` 为仓库单号
`status`	`PENDING`、`WAIT_PAYMENT`、`WAIT_SHIP`、`SHIPPED`、`SIGNED`、`CANCELLED`

发货单列表 {#shipment-list}

GET /v1/fulfillment/shipments 返回轻量行。示例见发货单 · 列表。

字段	说明
`id` / `order_sn`	Public `id` 为仓库数字主键（字符串）；`order_sn` 为仓库单号
`external_shipment_id`	创建时的 ISV 业务对账编号；不是 `Idempotency-Key` 重试请求头；仓库空串 → `null`
`status`	`PENDING` / `WAIT_PAYMENT` / `WAIT_SHIP` / `SHIPPED` / `SIGNED` / `CANCELLED`
`international_tracking`	`{ tracking_number, carrier }`。没有顶层 `tracking_number`
`receiver` / `shipping_channel` / `services[]`	与详情同形
`total`	详情风格：`charges` / `discount` / `payable` / `paid` / `outstanding`
`payment_status`	`UNPAID` / `PAID` / `PARTIAL`
`times`	`created_at` / `packed_at` / `paid_at` / `shipped_at` / `delivered_at` / `cancelled_at`
`pagination`	`page` / `page_size` / `total` / `total_pages`

列表不含 boxes、timeline、files、charges、shipping_legs、source_packages、interception。

发货单详情 {#shipment-detail}

GET /v1/fulfillment/shipments/{id} 是完整视图。创建 / 支付仍用汇总 total.freight / services / discount / payment。金额为分。示例见发货单 · 详情。

字段	说明
`id` / `order_sn`	Public `id`（路径参数）为仓库数字主键（字符串）；`order_sn` 为仓库单号
`external_shipment_id`	创建时的 ISV 业务对账编号；不是 `Idempotency-Key` 重试请求头；仓库空串 → `null`
`status`	`PENDING` / `WAIT_PAYMENT` / `WAIT_SHIP` / `SHIPPED` / `SIGNED` / `CANCELLED`
`source_packages[]`	合箱前国内包裹（过渡期 `id` 可能为 `null`）
`receiver`	国际收件人；`country_code` 为大写 ISO；`district` / `personal_code` 可为 `null`。`personal_code` 为创单时可选的个人通关码（如韩国 PCCC）
`shipping_channel`	`{ code, name }`
`multi_box`	`boxes.length > 1` 时为 `true`
`boxes[]`	出库箱：`box_no`（仓库 `box_sn`）、`source_package_ids`（仓库 `package_ids`）、重量 / 尺寸、可选 `tracking`
`international_tracking`	`{ tracking_number, carrier }`；仓库空串 → `null`
`timeline[]`	仓库业务事件 `{ code, status, title, occurred_at, details }`；code 稳定且非空；无上下文时 `details` 为 `{}`；最新事件在前
`shipping_legs[]`	有单号时为 `FIRST_MILE` / `LAST_MILE`；否则 `[]`
`files[]`	`PACKING_IMAGE` / `PACKING_VIDEO`
`services[]`	本单增值服务（`service_code`、`name`、`quantity`、`status`）
`charges[]`	费用行。折扣行为负数
`total`	`charges`（正费用）/ `discount`（正数）/ `payable` / `paid` / `outstanding`
`payment_status`	`UNPAID` / `PAID` / `PARTIAL`
`times`	`created_at` / `packed_at` / `paid_at` / `shipped_at` / `delivered_at` / …；未发生为 `null`

charges[].type：FREIGHT、VALUE_ADDED_SERVICE、CHANNEL_SERVICE_FEE、CHANNEL_RULE_FEE、INSURANCE、DUTIES_AND_TAXES、PACKAGE_SERVICE、COUPON_DISCOUNT、POINTS_DISCOUNT。

运单号在 international_tracking / boxes[].tracking / shipping_legs。详情 timeline 是仓库业务事件（打包 / 支付）。承运商扫描节点在国际物流追踪的 timeline[]（同为 { code, status, title, occurred_at, details }）。

余额 {#balance}

字段	说明
`balance.available`	可用于支付
`balance.frozen`	待处理运单占用
`balance.total`	可用 + 冻结

国际轨迹 {#international-trace}

发货单详情的子集 — 仅承运商扫描节点。

字段	说明
`id` / `order_sn`	与详情一致
`shipping_channel`	`{ code, name }`
`international_tracking`	`{ tracking_number, carrier }`；空字符串 → `null`
`status`	`PENDING` / `WAIT_PAYMENT` / `WAIT_SHIP` / `SHIPPED` / `SIGNED` / `CANCELLED`
`status_label`	仓库展示文案
`interception`	独立的拦截请求状态；未申请时为 `null`，且不会替代发货单 `status`
`timeline[]`	`{ code, status, title, occurred_at, details }`；code 稳定且非空；`title` 为本地化展示文案；时间为带时区 ISO 8601；最新事件在前

详情 timeline[] = 仓库业务节点；本接口 timeline[] = 承运商扫描节点。二者不要混用。

获取支持

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

发送邮件