Browse Source
参照 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 <noreply@anthropic.com>feature/supplier-lingxing^2
2 changed files with 253 additions and 0 deletions
@ -0,0 +1,251 @@
@@ -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=<sku> |
||||
② 新增(临时产品) 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=<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` 已支持,但结算账单未接 | |
||||
Loading…
Reference in new issue