入库预报（创建）

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

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

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

可用性： 沙箱 / Gateway MOCK 已上线（hio_test_*）。真实仓库上游转发尚未接通。

Scope：shipment:create。

请求体

{
  "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_ 前缀。

包裹状态（参考）

CODE英文显示含义
PENDINGPending Receipt已预报/已知晓，等待仓库收货
RECEIVEDReceived仓库已完成收货入库
CONSOLIDATEDConsolidated已加入集运单/完成集包
SHIPPEDShipped已从 HioBuy 仓库发出
DELIVEREDDelivered海外最终收件人已签收
TRANSFERRINGTransferring正从一个履约仓转移至另一个仓
DISCARDEDDiscarded已执行弃件处理
UNCLAIMEDUnclaimed已到仓但无法匹配所属客户/预报
ARCHIVEDArchived业务完成后归档

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

Sandbox Fixture

触发值字段HTTPerror.code
sb_inbound_shippedtracking_number409INBOUND_TRACKING_ALREADY_SHIPPED
sb_inbound_existstracking_number409INBOUND_TRACKING_ALREADY_EXISTS
sb_inbound_bad_trackingtracking_number422INVALID_TRACKING_NUMBER
sb_inbound_external_existsexternal_order_id409EXTERNAL_ORDER_ID_ALREADY_EXISTS
sb_vas_missingservices[].service_code422VALUE_ADDED_SERVICE_NOT_FOUND
sb_vas_unavailableservices[].service_code422VALUE_ADDED_SERVICE_UNAVAILABLE
sb_vas_outboundservices[].service_code422VALUE_ADDED_SERVICE_INVALID_STAGE
quantity: 0services[].quantity422VALUE_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 个工作日内回复

发送邮件