# 信仓(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=&page=1&limit=20 ② 新增(临时产品) POST /api.add_product 或 更新(仅临时产品可更新) POST /api.update_product ③ 商品查询(正式产品) GET /api.productlist?state=1&page=1&limit=20[&key=] ``` ### 商品查询(`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. 联调探针 三个探针,默认全部跳过: ```bash # ① 登录 mvn -pl warehouse-sdk-xincang -am -DfailIfNoTests=false \ -Dxincang.probe=true \ -Dxincang.probe.appKey= -Dxincang.probe.appSecret= \ -Dtest=XincangLoginProbeTest test # ② 只读(9 个查询接口) mvn -pl warehouse-sdk-xincang -am -DfailIfNoTests=false \ -Dxincang.probe=true \ -Dxincang.probe.appKey= -Dxincang.probe.appSecret= \ -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= -Dxincang.probe.appSecret= \ -Dxincang.probe.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` 已支持,但结算账单未接 |