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.

252 lines
11 KiB

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