入库预报（创建）

身份： 创建只返回 package_id（pkg_*）。没有单独 inbound_id。

POST /v1/fulfillment/inbounds/create — 提交 入库预报，让仓库预期国内物流包裹（运单号 + 清单 + 可选增值服务）。

需要仓库履约模式（Portal 授权）。自行履约 → 403 FULFILLMENT_MODE_NOT_SUPPORTED。

可用性： Sandbox 为 MOCK；仓库履约 live key 会转发至仓库入库接口。

Scope：shipment:create。

可选幂等请求头

创建入库预报时建议传 Idempotency-Key，用于保护重试和并发提交。每个逻辑预报使用一个唯一 key，只有重试相同请求时才复用。

POST /v1/fulfillment/inbounds/create
Authorization: Bearer <API_KEY>
Content-Type: application/json
Idempotency-Key: 803627de-c701-4ddf-94b7-b0c2fdad4f02

Gateway 会把该请求头转发给仓库。旧的 X-Idempotency-Key 仅为兼容保留，新接入请使用 Idempotency-Key。

请求体

{
  "tracking_number": "YT1234567890",
  "carrier": "YTO",
  "package_count": 1,
  "total_value": 128.5,
  "currency": "CNY",
  "external_order_id": "MY-ORD-001",
  "supplier_order_id": "1688-xxx",
  "remark": "fragile",
  "sender": {
    "name": "张三",
    "phone": "13800000000",
    "country_code": "CN",
    "province": "Zhejiang",
    "city": "Hangzhou",
    "district": "Yuhang",
    "postcode": "310000",
    "address": "…"
  },
  "items": [
    {
      "name": "Cotton T-Shirt",
      "quantity": "2",
      "unit_price": "64.25",
      "currency": "CNY",
      "hs_code": "610910",
      "image_url": "https://example.com/t.jpg"
    }
  ],
  "services": [
    {
      "service_code": "photo",
      "quantity": 1
    }
  ]
}

字段	必填	说明
`tracking_number`	是	国内物流单号
`package_count`	是	包裹件数
`total_value`	是	申报总货值（面值，非分）
`currency`	否	默认 `CNY`；支持 `CNY` / `USD` / `KRW`
`items[]`	是	清单；`quantity`、`unit_price` 为 string
`services[]`	否	`{ service_code, quantity }` — 仅入库阶段增值服务
`external_order_id`	否	同一 App 内唯一
`carrier` / `sender` / `remark` / `supplier_order_id`	否	补充信息

金额： 提交面值 + currency。与运输接口不同，本响应 不使用 monetary_unit: CNY_minor，Gateway 不做自动转分。

成功响应

HTTP 201：

{
  "success": true,
  "tracking_number": "YT1234567890",
  "status": "pending_receive",
  "package_count": 1,
  "external_order_id": null,
  "created_at": "2026-08-16T07:00:00.000Z",
  "request_id": "req_…"
}

沙箱成功 id 使用 sbi_ 前缀，并返回 package_id（pkg_*）供包裹详情接口使用。

重复与并发请求

运单号、external_order_id 重复或幂等冲突时返回 HTTP 409。已知已有资源时，error.details.existing_resource 会提供安全的包裹摘要，可直接恢复已有 package_id 和运单号，而不是重复创建。

{
  "error": {
    "code": "EXTERNAL_ORDER_ID_ALREADY_EXISTS",
    "message": "外部订单号已存在",
    "request_id": "req_...",
    "category": "VALIDATION_ERROR",
    "details": {
      "field": "external_order_id",
      "existing_resource": {
        "type": "package",
        "package_id": "427",
        "tracking_number": "YT1234567890",
        "external_order_id": "MY-ORD-001",
        "status": "PENDING"
      }
    }
  }
}

相关错误码：EXTERNAL_ORDER_ID_ALREADY_EXISTS、INBOUND_TRACKING_ALREADY_EXISTS、INBOUND_TRACKING_ALREADY_SHIPPED、IDEMPOTENCY_CONFLICT、IDEMPOTENCY_REQUEST_IN_PROGRESS。处理中冲突应等待 error.details.retry_after_ms 后用原 key 重试。

取消入库预报

DELETE /v1/fulfillment/inbounds/{id} 可使用 HioBuy 包裹系统 ID，也可使用仓库支持的开发者外部包裹/订单编号。网关会将 {id} 原样作为仓库 packageNum。纯数字值保留给 HioBuy 内部 ID，建议开发者编号添加前缀，例如 pkg_MY-ORD-001。

包裹状态（参考）

CODE	英文显示	含义
`PENDING`	Pending Receipt	已预报/已知晓，等待仓库收货
`RECEIVED`	Received	仓库已完成收货入库
`CONSOLIDATED`	Consolidated	已加入集运单/完成集包
`SHIPPED`	Shipped	已从 HioBuy 仓库发出
`DELIVERED`	Delivered	海外最终收件人已签收
`TRANSFERRING`	Transferring	正从一个履约仓转移至另一个仓
`DISCARDED`	Discarded	已执行弃件处理
`UNCLAIMED`	Unclaimed	已到仓但无法匹配所属客户/预报
`ARCHIVED`	Archived	业务完成后归档

当前 create MOCK 返回 status: "pending_receive"，语义对齐 PENDING。

Sandbox Fixture

触发值	字段	HTTP	`error.code`
`sb_inbound_shipped`	`tracking_number`	409	`INBOUND_TRACKING_ALREADY_SHIPPED`
`sb_inbound_exists`	`tracking_number`	409	`INBOUND_TRACKING_ALREADY_EXISTS`
`sb_inbound_bad_tracking`	`tracking_number`	422	`INVALID_TRACKING_NUMBER`
`sb_inbound_external_exists`	`external_order_id`	409	`EXTERNAL_ORDER_ID_ALREADY_EXISTS`
`sb_vas_missing`	`services[].service_code`	422	`VALUE_ADDED_SERVICE_NOT_FOUND`
`sb_vas_unavailable`	`services[].service_code`	422	`VALUE_ADDED_SERVICE_UNAVAILABLE`
`sb_vas_outbound`	`services[].service_code`	422	`VALUE_ADDED_SERVICE_INVALID_STAGE`
`quantity: 0`	`services[].quantity`	422	`VALUE_ADDED_SERVICE_QUANTITY_INVALID`

缺必填 → 422 INBOUND_VALIDATION_FAILED，含 details.fields[]。业务冲突一律协议 4xx，不用 soft 200。

错误码

见错误码 — Inbound / VAS 分组。门禁码：FULFILLMENT_MODE_NOT_SUPPORTED（对应草案 FULFILLMENT_NOT_ENABLED）。

获取支持

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

发送邮件