From 85e1fed8d48c94108e060ad4ca39a6bedcfb4ac5 Mon Sep 17 00:00:00 2001 From: lml <1297555865@qq.com> Date: Thu, 12 Nov 2026 13:51:34 +0800 Subject: [PATCH] =?UTF-8?q?docs(warehouse):=20=E6=96=B0=E5=A2=9E=E4=BF=A1?= =?UTF-8?q?=E4=BB=93=E6=8E=A5=E5=85=A5=E6=B1=87=E6=80=BB=E6=96=87=E6=A1=A3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 参照 docs-warehouse/yqn/README.md 的结构,补一份信仓的: - 基本信息:测试端点、query token 鉴权、2h 无 refresh、客户级 token、 成功判定(errno + rst.code)、北京时间、英寸/磅/美元 - 接口清单:19 个已对接接口与能力位,另列 3 个已声明常量但未接入的 - 业务流程:出库 / 转运 / 头程预报 / 商品四条链路的分步说明 - 枚举映射:订单 12 码、转运 8 码、预报 10 码、order_type 两套字典 并标注转运「列表与详情码表不一致」的差异 - 字段口径:ckh 唯一、amount 必填美元、po / rfc_sku_count 兜底规则、 is_pallet 必填、库存单仓限制等 13 条 - 平台限制与协议待核对:生产域名缺失、限流未公开、 calculate_order_v3 的 GET + JSON body 与 OkHttp 冲突 - 联调探针:三个探针的运行命令与全部可选属性,标明哪些会留数据 Co-Authored-By: Claude Code --- docs-warehouse/README.md | 2 + docs-warehouse/xincang/README.md | 251 +++++++++++++++++++++++++++++++++++++++ 2 files changed, 253 insertions(+) create mode 100644 docs-warehouse/xincang/README.md diff --git a/docs-warehouse/README.md b/docs-warehouse/README.md index 45d2d5f..e75ff01 100644 --- a/docs-warehouse/README.md +++ b/docs-warehouse/README.md @@ -7,6 +7,7 @@ | [architecture.md](architecture.md) | 三方仓架构:分层、模块依赖、门面/能力/适配器/SPI | | [callback.md](callback.md) | 回调(Webhook)链路:验签、分派、出参模型、宿主怎么接 | | [yqn/README.md](yqn/README.md) | 运去哪:接口汇总、联调结论、平台限制 | +| [xincang/README.md](xincang/README.md) | 信仓:接口汇总、枚举码表、协议待核对、联调探针 | | [notes.md](notes.md) | 通用注意事项:写操作、幂等、时区、单位、字段口径 | ## 快速定位 @@ -14,4 +15,5 @@ - 想知道**能力有哪些** → `architecture.md` 的「能力矩阵」 - 想知道**回调怎么接** → `callback.md` 的「宿主要做什么」 - 想知道**运去哪对接了什么** → `yqn/README.md` 的「接口清单」 +- 想知道**信仓对接了什么** → `xincang/README.md` 的「接口清单」 - 想知道**踩过什么坑** → `notes.md` diff --git a/docs-warehouse/xincang/README.md b/docs-warehouse/xincang/README.md new file mode 100644 index 0000000..93784af --- /dev/null +++ b/docs-warehouse/xincang/README.md @@ -0,0 +1,251 @@ +# 信仓(XinCang)接入汇总 + +## 1. 基本信息 + +| 项 | 值 | +|---|---| +| 适配器 ID | `xincang` | +| 测试 / 联调环境 | `http://test.api.oms.13u3.com/oms` | +| 生产环境 | `https://oms.xincang-tech.com/oms/` | +| 鉴权 | 先 `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= +② 新增(临时产品) POST /api.add_product + 或 更新(仅临时产品可更新) POST /api.update_product +``` + +## 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. 协议待核对(联调时必看) + +| 项 | 现状 | +|---|---| +| 生产域名 | 文档未给,常量写的是 `"待核对"` | +| 限流 | 未公开,按 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` 已支持,但结算账单未接 |