信仓(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 已支持,但结算账单未接 |