You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

13 KiB

信仓(XinCang)接入汇总

1. 基本信息

项 值
适配器 ID xincang
测试 / 联调环境 http://test.api.oms.13u3.com/oms
生产环境 https://oms.xincang-tech.com/oms(常量已去掉末尾斜杠,避免拼出 //api.xxx)
鉴权 先 GET /api.login?appkey=&secret= 换 token;业务请求把 token 放 query 参数 token,不是 Authorization 头
token 有效期 2 小时,没有 refresh 接口,到期只能重新登录
token 维度 客户级(同一 appkey 下多仓共用一个 token)
限流 保守默认 2 req/s(仓方未公开)
成功判定 顶层 errno=0;业务接口还要 rst.code="0"(登录响应没有 rst.code)
时间口径 北京时间(yyyy-MM-dd HH:mm:ss / 日期 yyyy-MM-dd)
单位 金额美元、尺寸英寸、重量磅(统一模型是 cm/g,适配器内换算)

2. 接口清单(19 个已对接)

# 接口 路径 能力位
1 登录 GET /api.login —
2 新增产品 POST /api.add_product PRODUCT
3 更新产品 POST /api.update_product PRODUCT
4 商品列表(查询 + 建档查重) GET /api.productlist PRODUCT
5 新增订单一单多件 POST /api.add_order_multiple OUTBOUND
6 订单详情 GET /api.get_order OUTBOUND
7 删除订单 POST /api.delete_order OUTBOUND
8 新增转运 POST /fba.do_fba TRANSFER
9 转运审核 POST /fba.do_approve TRANSFER
10 转运详情 GET /fba.fba_detail TRANSFER
11 删除转运 POST /fba.delete_fba TRANSFER
12 新增预报 POST /forecast.do_forecast INBOUND
13 完善资料 POST /forecast.do_improve_forecast INBOUND
14 预报提交 POST /forecast.done_forecast INBOUND
15 预报详情 GET /forecast.forecast_detail INBOUND
16 实时库存 GET /api.stocklist INVENTORY_QUERY
17 库龄列表 GET /api.stockagelist INVENTORY_QUERY
18 最优渠道 POST /api.calculate_order_v3 CHANNEL_RECOMMEND
19 客户仓库 / 承运商 GET /api.get_customer_warehouses、/api.get_customer_logistics DIRECTORY

已声明但未接入

常量 说明
PATH_PRODUCT_PUBLISH(/api.pub_product) 临时产品 → 正式产品,未接;建档结果仍是临时产品
PATH_TRANSFER_LIST(/fba.fbalist) 转运列表,未接
api.orderlist / forecast.forecastlist 列表查询均未接

3. 业务流程

出库

① 查仓库 / 承运商(拿 warehouse_code、logistics_type)
      GET  /api.get_customer_warehouses
      GET  /api.get_customer_logistics
② 可选:最优渠道询价
      POST /api.calculate_order_v3
③ 下单(multipart/form-data)
      POST /api.add_order_multiple
④ 查详情 / 回读状态
      GET  /api.get_order?order_no=  (或 ckh=)
⑤ 删除(按状态分流:待审核→删除、待发货→已取消、拣货/已拣货→已拦截)
      POST /api.delete_order

转运(仓 → 平台仓)

① 建转运(application/json)    POST /fba.do_fba        → order_no
② 查详情                        GET  /fba.fba_detail?order_no=
③ 审核                          POST /fba.do_approve?order_no=
④ 删除(仅待审核可删)          POST /fba.delete_fba?order_no=

头程入库(预报)

① 建空单(只给单头)            POST /forecast.do_forecast        → order_no
② 补明细(整段覆盖)            POST /forecast.do_improve_forecast
③ 提交                          POST /forecast.done_forecast      (query + body 都带 forecast_no)
④ 查详情                        GET  /forecast.forecast_detail

①②③ 是三步,不是一次调用。① 不需要商品明细(referenceSkuCount 必填)。

商品

① 查临时产品(决定 add 还是 update)
      GET  /api.productlist?state=0&key=<sku>&page=1&limit=20
② 新增(临时产品)              POST /api.add_product
   或 更新(仅临时产品可更新)    POST /api.update_product
③ 商品查询(正式产品)
      GET  /api.productlist?state=1&page=1&limit=20[&key=<sku>]

商品查询(api.productlist)

项 值
方法 / 路径 GET /api.productlist
必填 query token / state / page / limit(四项都必填,文档标 required)
选填 query key(产品 SKU,单值)
state 0 临时产品 / 1 正式产品
limit 默认 20,最大 100

适配器的 queryProducts 固定传 state=1——临时产品是建档中间态, 混进业务列表会让人以为能下单。建档查重那条路径仍用 state=0。

一次只能查一个 SKU:key 是单值。传多个时适配器拒绝, 静默只取第一个会让其余 SKU 缺席,看起来像「仓里没有」。

响应 rst.data[] 字段(Apifox 2026-11 核对):

字段 含义 落点
id 产品 id providerProductId
product_no SKU omsSku / providerSku
bar_code 条码 barcode
en_name / chn_name 英文 / 中文名 nameEn / name
amount 金额(USD) declaredValue
packing_rate 装箱率 packedQuantity
weight_kg / weight_lbs 重量 weightGrams(kg×1000)
size_l_cm / size_w_cm / size_h_cm 厘米尺寸 lengthCm 等(直接用厘米那套)
size_l_ln / size_w_ln / size_h_ln 英寸尺寸 不用(避免二次换算舍入)
volume_cm / volume_ln / volume_m 体积 volumeCm3(立方厘米)
gmt_create / gmt_modify 北京时间 createdAt / updatedAt(转 UTC)
state / state_name 状态码 / 中文名 rawState / stateName
image_url 图片签名 URL(有时效) imageUrl
product_image OSS 元数据 不映射(修改临时产品图片时回传用)
ckm 仓库码 不映射
rst.count 总条数(字符串) 判断是否有下一页

所有数值字段都是字符串——信仓全站风格。空串转 null,不转 0。

4. 枚举映射(信仓是两套码表,core 是第三套)

订单状态 state

信仓码 含义 core OutboundStatus
0 待审核 PENDING_REVIEW
1 待发货 PENDING_SHIPMENT
2 拣货中 PICKING
3 已拣货 PICKED
4 已贴单 LABEL_READY
5 已发货 SHIPPED
6 已拦截 INTERCEPTED
7 缺货 OUT_OF_STOCK
8 已取消 CANCELLED
10 已删除 DELETED
11 审核中 REVIEWING
12 审核失败 REVIEW_FAILED
其他 — UNKNOWN(不猜)

转运状态 state

信仓码 含义 core TransferStatus
0 待审核 PENDING_REVIEW
1 待处理 PENDING_PROCESSING
2 待拣货 PENDING_PICK
3 待贴标 PENDING_LABELING
4 待打托 PENDING_PALLETIZING
5 待发货 PENDING_OUTBOUND
6 已发货 SHIPPED(不是 COMPLETED)
7 已取消 CANCELLED

列表接口与详情接口的码表不一致:列表写的是「0 待审核 1 待处理 2 带拣货 3 待打托 4 待发货 5 已发货 9 取消」(少「待贴标」、后续前移)。适配器以详情码表为准,原始值仍保存在 rawStatus。

预报状态 state

信仓码 含义 core InboundStatus
0 建仓中 DRAFT
1 出运中 IN_TRANSIT
2 预报完成 PENDING_SHIPMENT
3 在海上 IN_TRANSIT
4 送仓中 IN_TRANSIT
5 卸柜中 RECEIVING
6 清点中 RECEIVING
7 上架中 STORING
8 上架完成 COMPLETED
9 已驳回 REJECTED

订单类型 order_type

值 含义 对应 core
common 非自供面单 LabelMode.WAREHOUSE_LABEL
wayfair 自供面单 LabelMode.PLATFORM_LABEL(gzh + face_base64 必填)

转运接口的 order_type 是另一套字典(FBA / LTL 等),与下单接口无关。

5. 字段口径(容易传错的)

字段 要传什么
下单 ckh 参考号,唯一不可重复;适配器用 outboundRequestNo,重推同一单号会被拒
下单 logistics_type 承运商字典值(api.get_customer_logistics 返回的原值)
下单 is_sign 是 / 否;模型 OutboundCommand.signatureRequired,未给时兜底「否」
下单 is_split 1 拆单 / 0 打包;未给时仓方默认 1
商品 amount 必填且美元;取 declaredValue,缺失直接拒绝(不再兜底 0.00)
商品 bar_code 必填且查重;WarehouseProduct.barcode 未给时退回 SKU
商品 ckm 仓库码,取 customItemNo
转运 po 必填;未给时退回 transferRequestNo
转运 delivery_mode / delivery_way 必填,只认仓方字典原值;先调字典接口
转运 is_pallet 必填 是 / 否;模型映射 palletRequired
预报 rfc_sku_count 必填;取 referenceSkuCount,没有退回明细行数
预报 ref_no 完善资料必填,长度上限 32
库存 warehouse_code 必填且只能单个;传多个显式拒绝
库存 is_show_zero 默认不传时只返回库存 > 0 的 SKU;模型 includeZeroStock
库龄 bill_date 单值字符串 起 - 止

6. 单位与时区

字段 单位
商品 weight_lbs / size_*_ln 磅 / 英寸(适配器从 cm、g 换算,保留 4 位)
商品 amount 美元,2 位小数
库存 volume_cm 立方厘米
库龄 total_volume_cbm 立方米

时间字段全部是北京时间,适配器解析成 UTC 后存入模型(Instant)。空串一律转 null,不猜。

7. 平台限制(已知且无法解决)

接口 字段 情况
订单详情 get_order order_no 只回系统单号;业务侧单号在 ckh
订单详情 get_order 面单 只给 face_url(OSS 签名链接,有时效)
转运详情 dest_warehouse 可能是占位 "0"
产品建档 state 新建的是临时产品(state=0),没有上架接口就下不了单
预报 明细 建单时没有明细,必须先建头再补
列表查询 订单 / 转运 / 预报 均无列表接口;query(cursor) 用单号取详情代替
错误信息 err 只有一句话(如「产品参数有误」),无法细分原因

8. 协议待核对(联调时必看)

项 现状
生产域名 https://oms.xincang-tech.com/oms(已确认并写入常量)
限流 未公开,按 2 req/s
最优渠道 calculate_order_v3 文档标 GET + JSON body,OkHttp 不支持 GET 带 body;适配器按 POST + JSON body 下发

9. 联调探针

三个探针,默认全部跳过:

# ① 登录
mvn -pl warehouse-sdk-xincang -am -DfailIfNoTests=false \
    -Dxincang.probe=true \
    -Dxincang.probe.appKey=<appkey> -Dxincang.probe.appSecret=<secret> \
    -Dtest=XincangLoginProbeTest test

# ② 只读(9 个查询接口)
mvn -pl warehouse-sdk-xincang -am -DfailIfNoTests=false \
    -Dxincang.probe=true \
    -Dxincang.probe.appKey=<appkey> -Dxincang.probe.appSecret=<secret> \
    -Dxincang.probe.sku=<有库存的SKU> -Dxincang.probe.postcode=<美国邮编> \
    -Dtest=XincangReadProbeTest test

# ③ 写(会留下真实数据,需二次确认)
mvn -pl warehouse-sdk-xincang -am -DfailIfNoTests=false \
    -Dxincang.probe=true -Dxincang.probe.write=true \
    -Dxincang.probe.appKey=<appkey> -Dxincang.probe.appSecret=<secret> \
    -Dxincang.probe.sku=<SKU> -Dxincang.probe.postcode=<邮编> \
    -Dxincang.probe.destWarehouse=<目的仓> \
    -Dtest=XincangWriteProbeTest test

可选属性:warehouseCode / carrier / orderNo / transferNo / forecastNo / qty / destWarehouse / deliveryMode / deliveryWay / orderType / shipmentType / cabinetType / deliveryRequirements / otherNeed / transferApprove。

会留下数据的探针:商品建档(无删除接口)、预报(delete_forecast 未接)、 转运审核(审核后不可删,需 -Dxincang.probe.transferApprove=true)。 出库与转运创建可以自清理。

10. 未接入

项 原因
上架正式产品 统一模型没有「上架」语义
订单 / 转运 / 预报列表 仓方虽提供,但统一模型暂未接列表能力
文件上传 upload.files 需要 multipart 文件流;商品图片与转运附件因此传不了
修改订单 api.update_order 文档建议停止使用
费用测算 api.calculate_order / _v2 只接了最优渠道 _v3
库龄费率以外的费用明细 is_need_fee_rate 已支持,但结算账单未接