|
|
|
|
# 恒健(HengJian / Efulfill)接入
|
|
|
|
|
|
|
|
|
|
语雀接口文档:<https://ehengjian.yuque.com/org-wiki-ehengjian-ocq8pc/tvzvkk>(book `tvzvkk`)
|
|
|
|
|
核对时间:2026-11-12(文档 `toc_updated_at` = 2026-11-10)
|
|
|
|
|
|
|
|
|
|
## 1. 基本信息
|
|
|
|
|
|
|
|
|
|
| 项 | 值 |
|
|
|
|
|
|---|---|
|
|
|
|
|
| 适配器 ID / provider | `hengjian` / `WarehouseProvider.HENGJIAN`(code 50) |
|
|
|
|
|
| 测试环境 | `https://pr-open-api.ehengjian.com` |
|
|
|
|
|
| 生产环境 | `https://open-api.ehengjian.com` |
|
|
|
|
|
| 鉴权 | 组织级固定 token,放请求头**两个**:`Authorization` + `x-api-key`,取值相同 |
|
|
|
|
|
| token 获取 | 文档未写自助方式:测试参数需联系 `bianyuqi@henglin.com` |
|
|
|
|
|
| token 续期 | 文档未提 refresh;先按固定 token 处理(不经过 `TokenManager`) |
|
|
|
|
|
| 限流 | 未公开,保守默认 2 req/s/仓 |
|
|
|
|
|
| 成功判定 | body 里 `code = 200`;HTTP 通常恒为 200 |
|
|
|
|
|
| 时间口径 | 文档多处注明 **UTC**(`paidAt`、`expectedShipDate`、订单列表的时间参数) |
|
|
|
|
|
| 单位 | 商品尺寸 cm、重量 g;费用单位为 USD(试算接口另有单位入参) |
|
|
|
|
|
| 文档结构 | 67 个目录项,其中 64 个可见接口页(3 个 `visible=0`,1 个抓取 403);另有 `CloudShip接口文档` / `加拿大邮政` 两个不相关目录,其下文档均不可见 |
|
|
|
|
|
|
|
|
|
|
### 鉴权真机结论(2026-11-12,未拿到有效 token)
|
|
|
|
|
|
|
|
|
|
| 请求 | 结果 |
|
|
|
|
|
|---|---|
|
|
|
|
|
| 不带任何授权头 | **HTTP 200** + `{"statusCode":500,"status":1,"code":999999,"message":"查询失败Unauthorized"}` |
|
|
|
|
|
| 只带 `Authorization`(无效值) | HTTP 500 + `{"status":500,"error":"Internal Server Error","message":"未知的账户!"}` |
|
|
|
|
|
| 只带 `x-api-key`(无效值) | 同上 |
|
|
|
|
|
| 两个都带(无效值) | 同上 |
|
|
|
|
|
|
|
|
|
|
**结论**:
|
|
|
|
|
|
|
|
|
|
- 未授权有两种表现(HTTP 200 + `code=999999`;HTTP 500 + 「未知的账户」),
|
|
|
|
|
适配器把两者都映射成 `AuthException`,**不能**当普通业务失败或瞬时故障——
|
|
|
|
|
否则宿主不会去刷新凭据,还会无意义重试。
|
|
|
|
|
- 用无效 token 区分不出「两个头是否都必须」,所以按文档两个都带。拿到有效 token 后
|
|
|
|
|
应补一次对照实验(各只带一个),再决定能否精简。
|
|
|
|
|
|
|
|
|
|
### 文档与实际不一致(待真机逐条确认)
|
|
|
|
|
|
|
|
|
|
| # | 文档写的 | 问题 |
|
|
|
|
|
|---|---|---|
|
|
|
|
|
| 1 | 《基础API调用》:`Authorization` 与 `x-api-key` 都必填、都叫「授权Token」 | 没说两者是否同值;两个头是否都必须未验证(见上) |
|
|
|
|
|
| 2 | 《库存变动明细查询》(2026-10-20 新增):「沿用现有 OpenAPI 凭证,请求头使用 `Authorization: Bearer <token>`」 | 与《基础API调用》的双头要求**冲突**;该页是后来单独写的,可能代表新约定 |
|
|
|
|
|
| 3 | 《获取仓库支持的物流渠道》:`warehouseCodes` 类型写 `STRING` | 请求示例是数组 `["..."]`;按数组下发 |
|
|
|
|
|
| 4 | 《批量查询库存》:GET,参数是 `warehouseCodes` LIST | HTTP GET 不能可靠表达数组;先按重复 query 参数下发 |
|
|
|
|
|
| 5 | 《查询库存》《查询 sku》等页:`code` 类型写 `STRING` | 其它页写 INTEGER;信封按文本读再转数字,两种都认 |
|
|
|
|
|
| 6 | 多个接口页**不写路径 / 请求方式**(调拨取消、销毁计划、退货 v2、计费类) | 只能从标题和相邻页推断;这几类未接入前不需要 |
|
|
|
|
|
| 7 | 《创建/编辑 产品》`length` vs 《查询 sku》`itemLength` | 同一概念两个字段名;接入商品前要真机确认哪个是「产品长」 |
|
|
|
|
|
| 8 | 试算 / 地址属性文档的路径写的是 `open-api.ehenglin.com`、`thebizark.com` | 与 `ehengjian.com` 不同域,疑似旧域名或从别家文档复制;接入前必须真机核对 |
|
|
|
|
|
| 9 | 几乎所有接口页**没有验签 / 请求头说明** | 真机返回早于业务码的 Spring 错误页,说明鉴权在网关层,文档没覆盖 |
|
|
|
|
|
| 10 | 《创建销售发货单》与 "Create Sale Order With Label" 是同一路径的两页 | 中文页把 `createdAt` 标必填、也没有 `isPrime`;英文页有 `isPrime`、没有 `customerRemark` / `warehouseRemark`。字段表按两页并集实现 |
|
|
|
|
|
| 11 | 建单页 `isPrime` 类型写 STRING | 请求示例给的是数字 `0`;按示例发 Integer |
|
|
|
|
|
| 12 | 建单页行级 `isSignature` 是 0~3 | 统一模型只有布尔,2 / 3(成人 / 间接签收)暂不可表达 |
|
|
|
|
|
|
|
|
|
|
> 运去哪的教训:只按文档写代码,有 4 处接口一个都跑不通。恒健的文档完整度更差
|
|
|
|
|
> (路径缺失、类型不一致、域名不一致),**接入任何写接口前必须先跑只读探针**。
|
|
|
|
|
|
|
|
|
|
## 2. 已接入(本期)
|
|
|
|
|
|
|
|
|
|
| # | 接口 | 路径 | 能力位 | 状态 |
|
|
|
|
|
|---|---|---|---|---|
|
|
|
|
|
| 1 | 获取当前组织仓库 | `POST /v2/warehouse/getWarehouse` | `DIRECTORY` | ✅ |
|
|
|
|
|
| 2 | 获取物流渠道(全量) | `POST /v2/carrierGroup/getCarrierGroup` | `DIRECTORY` / `LOGISTICS_PRODUCT` | ✅ |
|
|
|
|
|
| 3 | 获取仓库支持的物流渠道 | `POST /v2/carrierGroup/getWarehouseCarrierGroupServices` | 同上(适配器方法,非 capability) | ✅ |
|
|
|
|
|
| 4 | 创建 / 编辑产品 | `POST /v1/product/save` | `PRODUCT` | ✅ |
|
|
|
|
|
| 5 | 创建销售发货单 | `POST /v1/saleOrder/create` | `OUTBOUND` / `PLATFORM_LABEL_DELIVERY` | ✅ |
|
|
|
|
|
| 6 | 订单详情 | `POST /v1/saleOrder/findOne` | `OUTBOUND` | ✅ |
|
|
|
|
|
| 7 | 订单列表 | `GET /v1/saleOrder/findByPage` | `OUTBOUND` | ✅ |
|
|
|
|
|
| 8 | 订单取消 | `POST /v1/saleOrder/cancel` | `OUTBOUND` | ✅ |
|
|
|
|
|
| 9 | 物流异动单创建 | `POST /v1/trackingChange/create` | `TRACKING_CHANGE` | ✅ |
|
|
|
|
|
| 10 | 物流异动单查询 | `POST /v1/trackingChange/findOrder` | `TRACKING_CHANGE` | ✅ |
|
|
|
|
|
| 11 | 仓储费明细 | `POST /v1/chargingSettlement/getChargingStorageSettlement` | `FEE_SETTLEMENT` | ✅ |
|
|
|
|
|
| 12 | 尾程配送费明细 | `POST /v1/chargingSettlement/getChargingTailDeliverySettlement` | `FEE_SETTLEMENT` | ✅ |
|
|
|
|
|
| 13 | 作业费明细 | `POST /v1/chargingSettlement/getChargingOperationSettlement` | `FEE_SETTLEMENT` | ✅ |
|
|
|
|
|
| 14 | 运费测算 | `POST /v2/api/shipping/calculate` | `FEE_ESTIMATE` | ✅ |
|
|
|
|
|
| 15 | 地址属性识别 | `POST /v2/api/shipping/addressClassification` | `ADDRESS_CLASSIFICATION` | ✅ |
|
|
|
|
|
| 16 | 按 SKU 查库存 | `POST /v1/inventory/getInventory` | `INVENTORY_QUERY` | ✅ |
|
|
|
|
|
| 17 | 批量查库存(分页) | `GET /v2/inventory/get_inventory_by_page` | `INVENTORY_QUERY` | ✅ |
|
|
|
|
|
| 18 | 库存变动流水 | `POST /v1/inventory/task/query` | `INVENTORY_QUERY` | ✅ |
|
|
|
|
|
| 19 | 入库计划创建 | `POST /v1/inbound/createInboundPlan` | `INBOUND` | ✅ |
|
|
|
|
|
| 20 | 入库计划详情 | `POST /v1/inbound/getInboundPlanInfo` | `INBOUND` | ✅ |
|
|
|
|
|
| 21 | 入库计划列表 | `POST /v1/inbound/getInboundPlanPage` | `INBOUND` | ✅ |
|
|
|
|
|
| 22 | 调拨计划创建 | `POST /v1/transferPlan/create` | `TRANSFER` | ✅ |
|
|
|
|
|
| 23 | 调拨计划查询 | `GET /v1/transferPlan/findByPage` | `TRANSFER` | ✅ |
|
|
|
|
|
| 24 | 调拨计划取消 | `GET /v1/transferPlan/cancel` | `TRANSFER` | ✅ |
|
|
|
|
|
| 25 | 退货计划创建 | `POST /v1/saleReturn/thirdParty/saveReturnPlan` | `RETURN` | ✅ |
|
|
|
|
|
| 26 | 退货计划详情 | `POST /v1/saleReturn/thirdParty/getReturnPlanOrderInfo` | `RETURN` | ✅ |
|
|
|
|
|
| 27 | 退货计划列表 | `POST /v1/saleReturn/thirdParty/getReturnPlanOrderPage` | `RETURN` | ✅ |
|
|
|
|
|
| 28 | 退货处理单列表 | `POST /v1/saleReturn/getReturnPlanHandlePage` | `RETURN` | ✅ |
|
|
|
|
|
| 29 | 填写退货处理方式 | `POST /v1/saleReturn/handlingMethod` | `RETURN` | ✅ |
|
|
|
|
|
| 30 | 订单上传附件 | `POST /v1/saleOrder/createAttachment` | `OUTBOUND` | ✅ |
|
|
|
|
|
| 31 | 销毁计划创建 | `POST /v2/destroyPlanOrder/create`(⚠ **真机 404**) | `DESTRUCTION` | ⚠ 路径待确认 |
|
|
|
|
|
| 32 | 销毁计划查询 | `POST /v2/destroyPlanOrder/find`(⚠ **真机 404**) | `DESTRUCTION` | ⚠ 路径待确认 |
|
|
|
|
|
| 33 | 入库箱标生成 | `POST /v2/inbound/boxLabelGenerate` | `BOX_LABEL` | ✅ |
|
|
|
|
|
| 34 | 回调 | — | — | ❌ 文档无回调页 |
|
|
|
|
|
|
|
|
|
|
前三个接口是无副作用查询、不依赖单号,用来先验证鉴权与信封;商品保存是写接口,
|
|
|
|
|
但只写主数据、不产生履约单据,所以放在第二阶段。出库下单是真正的履约写操作,
|
|
|
|
|
门面强制经幂等守卫(`warehouseCode + outboundRequestNo + create`)。
|
|
|
|
|
|
|
|
|
|
### 返回形状差异
|
|
|
|
|
|
|
|
|
|
| 接口 | `data` |
|
|
|
|
|
|---|---|
|
|
|
|
|
| `getWarehouse` | 数组 |
|
|
|
|
|
| `getCarrierGroup` | 数组 |
|
|
|
|
|
| `getWarehouseCarrierGroupServices` | **对象**:`{"EFCA":[{...}], "EFGA":[...]}` |
|
|
|
|
|
|
|
|
|
|
第三个接口只取请求的那个仓的键——别的仓的渠道混进来,会把「仓不支持该渠道」
|
|
|
|
|
推到仓方去报错。
|
|
|
|
|
|
|
|
|
|
### 字段口径
|
|
|
|
|
|
|
|
|
|
| 统一模型字段 | 恒健字段 | 说明 |
|
|
|
|
|
|---|---|---|
|
|
|
|
|
| `WarehouseFacility.warehouseCode` | `warehouseCode` | 唯一标识,下单也用它 |
|
|
|
|
|
| `WarehouseFacility.providerWarehouseId` | — | 恒健没有独立内部 id,恒为 null |
|
|
|
|
|
| `WarehouseFacility.contactName/mobilePhone/email` | — | 文档仓对象没有这三个字段,**恒为 null**(平台限制) |
|
|
|
|
|
| `WarehouseFacility.postcode` | `postal` | 字段名不同 |
|
|
|
|
|
| `LogisticsProduct.logisticsProductCode` | `code` | 下单的 `carrierCode` 用它 |
|
|
|
|
|
| `LogisticsProduct.logisticsProductName` | `carrier` + `carrierServiceName` | 统一模型只有一个名称字段,拼成「UPS - Ground」 |
|
|
|
|
|
| `LogisticsProduct.crossCountry` | — | 恒健无此维度,恒 false(**不是**「不支持跨国」) |
|
|
|
|
|
|
|
|
|
|
### 商品保存(`/v1/product/save`)
|
|
|
|
|
|
|
|
|
|
**保存语义**:同一 SKU 再调即更新,没有单独的 create / update 接口,也不像信仓那样
|
|
|
|
|
要先查一次再决定调哪个。响应只有 `code / message`,**没有 data**,所以:
|
|
|
|
|
|
|
|
|
|
- `ProductResult.status` 固定为 `SAVED`;
|
|
|
|
|
- `ProductResult.rawStatus` 取仓方的 `message`(如「产品创建成功」);
|
|
|
|
|
- 仓方不告诉这次是新建还是更新,**不替它编** `ADDED` / `UPDATED`。
|
|
|
|
|
|
|
|
|
|
**三组尺寸不能互相顶替**:
|
|
|
|
|
|
|
|
|
|
| 恒健字段 | 含义 | 必填 | 统一模型 |
|
|
|
|
|
|---|---|---|---|
|
|
|
|
|
| `length / width / height / weight` | 产品(发货单元)尺寸与重量 | 是 | `lengthCm / widthCm / heightCm / weightGrams` |
|
|
|
|
|
| `itemLength / itemWidth / itemHeight` | 单品尺寸 | 否 | `itemLengthCm / …`(未给不发) |
|
|
|
|
|
| `packedLength / packedWidth / packedHeight / packedWeight / packedQty` | 外箱尺寸、外箱重量、装箱数量 | 是 | `packedLengthCm / … / packedQuantity` |
|
|
|
|
|
|
|
|
|
|
把单品尺寸填进 `length` 会让仓方的计费重与货架位算错,所以适配器不做任何回退填充。
|
|
|
|
|
|
|
|
|
|
**本地拒绝的必填项**(恒健要求、统一模型不强制):
|
|
|
|
|
|
|
|
|
|
`nameEn`、`description`、`packingType`(0 原包装 / 1 重新打包)、外箱四项尺寸重量、
|
|
|
|
|
`packedQty`。缺任何一项直接抛 `IllegalArgumentException`,**一个请求都不发**。
|
|
|
|
|
|
|
|
|
|
**不在报文里编造字段**:
|
|
|
|
|
|
|
|
|
|
| 统一模型字段 | 为什么不发 |
|
|
|
|
|
|---|---|
|
|
|
|
|
| `imageUrl` | 恒健的 `imageUrls` 是「产品测量图片」(复核长宽高用),不是商品主图;语义不同,改为由 `WarehouseProduct.imageUrls()` 表达 |
|
|
|
|
|
| `packageStyle` | 恒健的 `isSpecialOuterPackaging` 是「是否特殊外包装」,不是同一套码;改为由 `WarehouseProduct.specialOuterPackaging()` 表达 |
|
|
|
|
|
| `requireSn` / `snManagementMode` / `lotControl*` | 文档无对应字段 |
|
|
|
|
|
| `hsCode` / `countryOfOrigin` / `declaredValue` | 恒健只收报关名称(`customName` / `customNameEn`),没有 HS 与原产国 |
|
|
|
|
|
| `link` / `returnDealMethod` / `productCategory` | 文档无对应字段 |
|
|
|
|
|
|
|
|
|
|
**其它口径**:
|
|
|
|
|
|
|
|
|
|
- `isInsuranceFlag` 是 `Y` / `N`(不是 0 / 1);未指定则整组不发。
|
|
|
|
|
- `expirationDate` 只在 `expirationControl = 1` 时发送,避免仓方存「有天数但未启用」的脏数据。
|
|
|
|
|
- `cost` 与 `currency` 成对发送;`cost` 缺失则两个都不发。
|
|
|
|
|
- 单位与统一模型一致(cm / g),**不做换算**。
|
|
|
|
|
|
|
|
|
|
### 创建销售发货单(`/v1/saleOrder/create`)
|
|
|
|
|
|
|
|
|
|
中英文两页文档是**同一个接口**(中文页「创建销售发货单(带附件的)」、英文页
|
|
|
|
|
「Create Sale Order With Label」),按两页并集实现。
|
|
|
|
|
|
|
|
|
|
**必填字段**:`orderNo`、`shipToCountry`、`shipToState`、`shipToCity`、`shipToPostal`、
|
|
|
|
|
`shipToAddress1`、`shipToContact`、`shipToTelephone`、`createdAt`、`productItems`、
|
|
|
|
|
`attachInfoItems`。适配器在本地逐项校验,缺任何一项直接抛 `IllegalArgumentException`,
|
|
|
|
|
**一个请求都不发**。
|
|
|
|
|
|
|
|
|
|
**统一模型字段映射(原先「不发」的现已全部打通)**:
|
|
|
|
|
|
|
|
|
|
| 文档字段 | 统一模型 | 说明 |
|
|
|
|
|
|---|---|---|
|
|
|
|
|
| `paidAt` | `OutboundCommand.paidAt` | UTC;未给由仓方取当前时间 |
|
|
|
|
|
| `pickupTime` | `OutboundCommand.pickupTime` | `yyyy-MM-dd`,FBALTL 自提场景必填 |
|
|
|
|
|
| `isDFOrder` | `OutboundCommand.directFulfillment` | 布尔→0/1;**由调用方显式指定**,不按平台推断 |
|
|
|
|
|
| `thirdPartyAccount` | `OutboundCommand.thirdPartyAccount` | — |
|
|
|
|
|
| `customerRemark` | `OutboundCommand.remark` | 客户 / 买家备注 |
|
|
|
|
|
| `warehouseRemark` | `OutboundCommand.warehouseRemark` | **给仓作业看的备注**,与上一个是两个字段 |
|
|
|
|
|
| `attachInfoItems` | `OutboundCommand.attachments()` | 通用附件列表:支持 URL 与 base64、7 种类型 |
|
|
|
|
|
| `attachInfoItems`(面单快捷入口) | `OutboundCommand.labelContentBase64` | 平台面单专用,可与附件列表同时给 |
|
|
|
|
|
|
|
|
|
|
**几个关键口径**:
|
|
|
|
|
|
|
|
|
|
| 项 | 处理 |
|
|
|
|
|
|---|---|
|
|
|
|
|
| `createdAt` | 统一模型没有该字段,用调用方注入的 `Clock` 生成下单时刻(请求侧时间戳,不是编造数据)。恒健不拿它去重 |
|
|
|
|
|
| 时间格式 | 恒健是 **UTC** 的 `yyyy-MM-dd HH:mm:ss`,固定按 UTC 格式化,**不用** `WarehouseContext.zone()`——那个时区是给「仓方回传的无时区本地时间」用的,方向相反 |
|
|
|
|
|
| `skuAmount` | 是「当前 SKU **总**金额」,不是单价:有 `totalAmount` 直接用,没有就用申报单价 × 数量 |
|
|
|
|
|
| `isSign` / `isSignature` | 恒健挂在**行**上且必填;统一模型挂在**命令**上(布尔)。取命令值套到每一行 |
|
|
|
|
|
| 签收类型 | 统一模型只有布尔,表达不了成人签收(2) / 间接签收(3),统一映射成**直接签收(1)**——比静默降成「不签收(0)」安全 |
|
|
|
|
|
| `isInsure` / `insureAmount` | 由「行是否有保价金额」推导;有金额即视为保价并带上金额 |
|
|
|
|
|
| `attachInfoItems` | **必填**。没有附件时发**空数组**而不是省略字段;平台面单(base64)会剥掉 `data:` 前缀后放进 `file`,`type=0`,名称优先用跟踪号 |
|
|
|
|
|
| `salesPlatform` | 恒健没有平台维度(店铺路由走 `channelAccount`),**不发**,也**不**拿它推 `isDFOrder`——VC 订单里只有一部分是 DF |
|
|
|
|
|
| `splitOrder` / `packages` | 恒健没有拆单与包裹入参,忽略 |
|
|
|
|
|
| `estimatedDeliveryTime` | 恒健只有 `expectedShipDate`(要求发货时间),没有送达时间 |
|
|
|
|
|
|
|
|
|
|
**响应**:只回 `data.orderId`(仓内部**数字** id,不是字符串单号)。取消接口要
|
|
|
|
|
`orderId` + `orderNo` 两个都传,所以这个 id 必须随 `OutboundReceipt.providerOrderId()`
|
|
|
|
|
落库;拿不到就报错,**不当创建成功**。
|
|
|
|
|
|
|
|
|
|
**未接入**:物流异动单取消。调用会显式抛异常,不返回 null——
|
|
|
|
|
静默返回空会让调用方以为「仓说没有这单」。
|
|
|
|
|
|
|
|
|
|
## 3. 未接入(文档已有,按需排期)
|
|
|
|
|
|
|
|
|
|
按能力位分组,路径取自文档(**标注 ⚠ 的表示文档没写路径或路径可疑,需真机核对**):
|
|
|
|
|
|
|
|
|
|
### 出库(`OUTBOUND`)
|
|
|
|
|
|
|
|
|
|
| 接口 | 路径 | 状态 |
|
|
|
|
|
|---|---|---|
|
|
|
|
|
| 创建销售发货单(中文页「带附件」/ 英文页 "With Label",同路径) | `POST /v1/saleOrder/create` → `data.orderId` | ✅ 已接入 |
|
|
|
|
|
| 订单详情 | `POST /v1/saleOrder/findOne` | ✅ 已接入 |
|
|
|
|
|
| 订单列表 | `GET /v1/saleOrder/findByPage` | ✅ 已接入 |
|
|
|
|
|
| 订单取消 | `POST /v1/saleOrder/cancel`(`orderId` + `orderNo` 都必填) | ✅ 已接入 |
|
|
|
|
|
| 订单上传附件 | `POST /v1/saleOrder/createAttachment` | ⬜ |
|
|
|
|
|
| 物流异动单 创建 | `POST /v1/trackingChange/create` | ✅ 已接入(`TRACKING_CHANGE`) |
|
|
|
|
|
| 物流异动单 查询 | `POST /v1/trackingChange/findOrder`(⚠ 文档写的是 `/v1/saleOrder/findOrder`,真机 404) | ✅ 已接入 |
|
|
|
|
|
| 物流异动单 取消 | `POST /v1/trackingChange/cancel` | ⬜ |
|
|
|
|
|
|
|
|
|
|
#### 物流异动单(召回 / 换址 / 在途异常)
|
|
|
|
|
|
|
|
|
|
与「轨迹查询」是两件事:轨迹只读,异动会向承运商提工单、可能产生费用,
|
|
|
|
|
所以单独一个能力位 `TRACKING_CHANGE`。
|
|
|
|
|
|
|
|
|
|
**真机已验证的必填项**(文档标错 / 漏标):
|
|
|
|
|
|
|
|
|
|
| 字段 | 文档 | 真机 |
|
|
|
|
|
|---|---|---|
|
|
|
|
|
| `trackingNo` | 是 | 是 |
|
|
|
|
|
| `orderNo` | **否** | **是**(缺了回「来源单号不能为空」) |
|
|
|
|
|
| `remark` | 是 | 是 |
|
|
|
|
|
| `handleType` | 是 | 是 |
|
|
|
|
|
| `newRecipientName/Phone/Address` | 换址时必填 | 换址时必填(校验顺序 姓名 → 电话 → 地址) |
|
|
|
|
|
|
|
|
|
|
另外仓方会校验**「来源单号和 trackingNo 不匹配」**——两者必须属于同一张单。
|
|
|
|
|
这条本地挡不住,只能在联调时给一对真实存在的单号 + 运单号。
|
|
|
|
|
|
|
|
|
|
**路径纠正(真机 2026-11-13)**:查询页写的 `/v1/saleOrder/findOrder` 返回
|
|
|
|
|
`404 No handler found`;实际路径是 **`/v1/trackingChange/findOrder`**
|
|
|
|
|
(疑似从销售订单页复制)。适配器用后者。
|
|
|
|
|
|
|
|
|
|
**两个状态别混**:
|
|
|
|
|
|
|
|
|
|
| 字段 | 含义 | 落到 |
|
|
|
|
|
|---|---|---|
|
|
|
|
|
| `orderStatus` 0~6 | 异动单**受理**状态(草稿 / 待受理 / 受理中 / 已受理 / 受理成功 / 受理失败 / 取消) | `rawStatus()` |
|
|
|
|
|
| `logisticsStatus` 0~9 | **运单**物流状态(PRE TRANSIT / IN TRANSIT / … / RETURN TO SENDER) | `rawLogisticsStatus()` |
|
|
|
|
|
|
|
|
|
|
两者各存各的:一张异动单可能「已受理」而运单还在途,不能互相覆盖。
|
|
|
|
|
`accepted()` / `failed()` / `cancelled()` 是按 `orderStatus` 的便捷判断。
|
|
|
|
|
|
|
|
|
|
**查询响应的字段全部保留**(原先是只映射了一部分):
|
|
|
|
|
|
|
|
|
|
| 分组 | 字段 | 落点 |
|
|
|
|
|
|---|---|---|
|
|
|
|
|
| 来源三维 | `sourceId` / `sourceNo` / `sourceOrderType` | 各自独立,`sourceNo` 同时作为 `orderNo` |
|
|
|
|
|
| 收件人对照 | `originalRecipient*` / `newRecipient*` | 换址场景要能看到「原 → 新」 |
|
|
|
|
|
| 承运商受理 | `carrierIsAcceptance`(**1 否 / 2 是**,不是 0/1) | `carrierAccepted()` 取布尔,缺失或非法值返回 null |
|
|
|
|
|
| 召回标记 | `trackingLabel`(0 无 / 1 召回中) | `recalling()` |
|
|
|
|
|
| 异常 | `errorStatus` / `errorMessage` | 码与文本分开保留 |
|
|
|
|
|
| 备注 | `customerRemark` / `acceptanceRemark` | 两个字段不合并 |
|
|
|
|
|
|
|
|
|
|
**`changeRequestNo` 在查询结果里为 null**:仓方响应没有这个号,
|
|
|
|
|
不拿仓单号顶替——填同一个值会让调用方误以为 OMS 单号等于仓单号。
|
|
|
|
|
|
|
|
|
|
**未能确认**:`handleType` 文档标 STRING、示例给数字。真机字符串和数字都试过,
|
|
|
|
|
两种都能过(都走到后续业务校验),**区分不出**类型要求,按示例发 Integer。
|
|
|
|
|
|
|
|
|
|
**未接入**:物流异动单取消。调用会显式抛异常,不返回 null——
|
|
|
|
|
静默返回空会让调用方以为「仓说没有这单」。
|
|
|
|
|
|
|
|
|
|
#### 订单详情(`/v1/saleOrder/findOne`)
|
|
|
|
|
|
|
|
|
|
- 请求只有 `orderNo`(来源单号)。
|
|
|
|
|
- **响应不回 `orderId`**:详情查回来的单拿不到仓内部 id。要取消的话,
|
|
|
|
|
得走列表接口按 `orderNos` 查一次补 `orderId`。
|
|
|
|
|
- 统一模型映射:`outboundRequestNo = orderNo`、`providerOrderId = null`、`orderRef = null`。
|
|
|
|
|
- `skuAmount` 是**行总额**,落 `OutboundLine.totalAmount`;恒健不回申报单价,
|
|
|
|
|
`declareValue` 保持 null,**不把总额当单价再乘一次**。
|
|
|
|
|
- 时间按 **UTC** 解析(`yyyy-MM-dd HH:mm:ss`),不用 `WarehouseContext.zone()`。
|
|
|
|
|
- `errorCode = "unexception"` 归一成 `exceptionCode = null`。
|
|
|
|
|
- 发货信息里 `packageFlag=1` 是面单信息行,取运单号 / 发货时间时只认 `0`(实际包裹)。
|
|
|
|
|
- `data` 为空 → 返回 `null`(「查不到」),不造空单。
|
|
|
|
|
|
|
|
|
|
#### 订单列表(`/v1/saleOrder/findByPage`)
|
|
|
|
|
|
|
|
|
|
- `GET`;分页四件套 `page / rows / sidx / sort` 都必填,适配器固定
|
|
|
|
|
`sidx=id&sort=desc`,`rows` 超过 100 截断到 100。
|
|
|
|
|
- **时间、订单号、订单 id 三者必填其一**:给 `outboundRequestNo` 就按 `orderNos` 查;
|
|
|
|
|
给时间窗就按 `beginDateTime / endDateTime`(UTC 日期)查;都没有 →
|
|
|
|
|
**本地拒绝**,不发必然被仓方拒的请求。
|
|
|
|
|
- 时间跨度上限 **30 天**,超过也本地拒绝。
|
|
|
|
|
- 不支持状态过滤:`OutboundQuery.statuses()` 非空时**拒绝**而不是静默忽略
|
|
|
|
|
(静默忽略会让调用方以为过滤生效了)。
|
|
|
|
|
- **新增可传维度**(原先是「模型里没有,调用方传不进来」):
|
|
|
|
|
`channel`(平台)、`channelAccount`(店铺)、`poNo`、`providerOrderIds`
|
|
|
|
|
(逗号拼接下发 `orderIds`)、`updatedAfter/Before`(更新时间窗,独立于创建时间窗)。
|
|
|
|
|
- `OutboundQuery.orderRef`(平台单号)恒健**没有**对应参数:传了就**拒绝**,
|
|
|
|
|
不静默忽略(静默忽略会让调用方以为过滤生效了)。
|
|
|
|
|
- **排序可配**:`sortField` / `sortDirection` 由调用方指定,未指定才用文档默认
|
|
|
|
|
(`sidx=id`、`sort=desc`)。文档说 `sidx`「可写死 id」,不是「只能 id」;
|
|
|
|
|
`sort` 本来就是 `asc` / `desc` 两个可选值。
|
|
|
|
|
- **`rows` 上限 100 是文档明写的**,超过时**拒绝**而不是静默截断——
|
|
|
|
|
截断后调用方按自己的 `pageSize` 判末页会误判「还有下一页」。
|
|
|
|
|
- **列表是唯一回 `orderId` 的接口**,映射进 `providerOrderId` 与 `providerId`。
|
|
|
|
|
- 翻页游标是字符串页码(恒健入参 1 基,响应 `number` 是 0 基);
|
|
|
|
|
是否末页以仓方 `last` 为准。
|
|
|
|
|
- 列表独有 `amount`(整单销售金额)落 `totalAmount`;`taxPrice` 统一模型无对应字段,不落。
|
|
|
|
|
|
|
|
|
|
#### 包裹(`packages`)
|
|
|
|
|
|
|
|
|
|
恒健没有独立包裹接口,从详情 `shipmentPackages` 提取。按 `trackingNo` 去重
|
|
|
|
|
(同一包裹可能同时以「实际包裹」和「面单信息」两行出现),实际包裹优先。
|
|
|
|
|
|
|
|
|
|
#### 状态枚举
|
|
|
|
|
|
|
|
|
|
`HengjianOrderStatus` 全量 8 个值:
|
|
|
|
|
|
|
|
|
|
| 恒健 | 含义 | core `OutboundStatus` |
|
|
|
|
|
|---|---|---|
|
|
|
|
|
| `pending` | 未支付 | `CREATED` |
|
|
|
|
|
| `unshipped` | 未发货 | `SUBMITTED` |
|
|
|
|
|
| `approved` | 已审核 | `ACCEPTED` |
|
|
|
|
|
| `assigned` | 已分配 | `ACCEPTED` |
|
|
|
|
|
| `picked` | 已配货 | `PICKING` |
|
|
|
|
|
| `shipped` | 已发货 | `SHIPPED` |
|
|
|
|
|
| `canceled` | 已取消 | `CANCELLED` |
|
|
|
|
|
| `refunded` | 已退款 | `REFUNDED`(core 新增,码 180) |
|
|
|
|
|
|
|
|
|
|
> `refunded` 为此新增了 core 枚举值:退款是履约后的资金退回,与取消语义不同,
|
|
|
|
|
> 合并就分不出「这单有没有发出去」。core 枚举**只追加**,不动已有码值。
|
|
|
|
|
|
|
|
|
|
**精确匹配**,不用 `contains`;`unshipped` 与 `shipped` 是前缀关系,
|
|
|
|
|
用子串判断会把未发货判成交运。
|
|
|
|
|
|
|
|
|
|
#### 订单取消(`/v1/saleOrder/cancel`)
|
|
|
|
|
|
|
|
|
|
恒健要求 **`orderId` + `orderNo` 两个都传**,而统一模型的 `CancelCommand` 允许只给一个。
|
|
|
|
|
适配器的处理:
|
|
|
|
|
|
|
|
|
|
| 给了什么 | 行为 |
|
|
|
|
|
|---|---|
|
|
|
|
|
| `outboundRequestNo` + `providerOrderId` | 直接用,只发一次取消请求 |
|
|
|
|
|
| 只有 `outboundRequestNo` | 先按 `orderNos` 查列表补 `orderId`,再取消 |
|
|
|
|
|
| 只有 `providerOrderId` | 先按 `orderIds` 查列表补 `orderNo`,再取消 |
|
|
|
|
|
| 两个都没有 | 构造期就拒绝 |
|
|
|
|
|
| 列表补不到(仓里没有这单) | **本地拒绝**,不发必然被拒的取消请求 |
|
|
|
|
|
|
|
|
|
|
- 列表查回来的结果要**逐条精确比对**单号 / id 之后才用——`orderNos` 是否精确匹配文档没写,
|
|
|
|
|
拿近似结果去取消会取消错单。
|
|
|
|
|
- `orderId` 用 `Long`(文档标 INTEGER):九位数的 id 用 int 迟早出事,溢出是静默错单。
|
|
|
|
|
- 恒健没有取消费概念,`CancelCommand.acceptCharge()` 不生效。
|
|
|
|
|
- 仓方拒绝取消 → `OutboundCancelBlockedException`;**认证失败不会被包装**成不可取消,
|
|
|
|
|
否则宿主不会去刷新凭据。
|
|
|
|
|
|
|
|
|
|
#### 取消预判(`checkCancel`)
|
|
|
|
|
|
|
|
|
|
恒健没有独立的预判接口,按详情状态推断:`shipped` / `canceled` / `refunded` / `deleted`
|
|
|
|
|
以及 **`UNKNOWN`** 判 `BLOCKED`,其余 `FREE`。查不到单时也判 `BLOCKED`——
|
|
|
|
|
猜成 FREE 会发出注定被拒的取消。`UNKNOWN` 一并挡住,是因为恒健的词表将来可能加值,
|
|
|
|
|
认不出时不该凭猜下写请求。
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
### 库存(`INVENTORY_QUERY`)
|
|
|
|
|
|
|
|
|
|
| 接口 | 路径 |
|
|
|
|
|
|---|---|
|
|
|
|
|
| 查询库存(按 SKU) | `POST /v1/inventory/getInventory`(`skus` 必填) |
|
|
|
|
|
| 批量查询库存(分页) | `GET /v2/inventory/get_inventory_by_page` |
|
|
|
|
|
| 批次库存查询 | `POST v1/inventory/batch/getInventoryBatchByWarehouseCode`(⚠ 文档少了前导 `/`) |
|
|
|
|
|
| 库存批次快照 | `POST /v1/inventory/batch/getInventoryBatchSnapshotByPage` |
|
|
|
|
|
| 库存变动明细(流水) | `POST /v1/inventory/task/query`(该页要求 `Authorization: Bearer`,见冲突 #2) |
|
|
|
|
|
|
|
|
|
|
库存字段:`inventoryType`(0 可售 / 1 不可售)、`inventoryAvailable`、`inventoryReserved`、
|
|
|
|
|
`inventoryTransport`、`inventoryCurrent`、`updatedAt`。注意 `inventoryTransport` 与
|
|
|
|
|
`inventoryCurrent` 文档标成 STRING,数量类最终要转 int。
|
|
|
|
|
|
|
|
|
|
### 商品(`PRODUCT`)
|
|
|
|
|
|
|
|
|
|
| 接口 | 路径 | 状态 |
|
|
|
|
|
|---|---|---|
|
|
|
|
|
| 创建 / 编辑产品 | `POST /v1/product/save` | ✅ 已接入 |
|
|
|
|
|
| 查询 sku | `POST /v1/product/getBySku` | ⬜ |
|
|
|
|
|
| 分页查询 SKU / 产品打托信息 | `POST /v2/product/queryPage` | ⬜ |
|
|
|
|
|
| 渠道产品关系查询 | `GET /v1/productChannel/findByPage` | ⬜ |
|
|
|
|
|
| 创建产品识别码 | `POST /v1/product/createProductAlias` | ⬜ |
|
|
|
|
|
|
|
|
|
|
尺寸 cm / 重量 g,与统一模型一致(不需要换算)。
|
|
|
|
|
|
|
|
|
|
保存接口的字段口径见上一节。注意《查询 sku》页把「产品长」写作 `itemLength`,
|
|
|
|
|
而《创建/编辑产品》页写作 `length`——**两页对同一概念用了不同字段名**,
|
|
|
|
|
接查询接口时必须真机确认哪个才是产品长(见风险表 #7)。
|
|
|
|
|
|
|
|
|
|
### 入库(`INBOUND`)
|
|
|
|
|
|
|
|
|
|
入库计划创建 / 列表 / 查询 / 取消 / 加附件 / 上传附件 / 发运 / 更新到仓日期 / 生成箱标,
|
|
|
|
|
预约单创建 / 修改 / 取消 / 信息查询 / 日期查询。路径以 `/v1/inbound/...`、`/v3/booking_order/...` 为主。
|
|
|
|
|
|
|
|
|
|
### 入库计划创建(`/v1/inbound/createInboundPlan`)—— 已接入
|
|
|
|
|
|
|
|
|
|
**真机确认的必填项**(空 body 触发的校验信息):
|
|
|
|
|
|
|
|
|
|
```
|
|
|
|
|
orderNo(订单号必须填写)
|
|
|
|
|
warehouseCode(仓库必须填写)
|
|
|
|
|
inventoryType(库存类型必须填写)
|
|
|
|
|
productItems(入库产品明细必须填写)
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
**文档标必填、真机不校验的**:`currency`(文档说「默认 USD」,真机不传也能过校验,
|
|
|
|
|
只会在鉴权处停下)。按选填实现,不传由仓方按 USD 处理。
|
|
|
|
|
|
|
|
|
|
**响应不回仓单号**:只有 `code / message`。所以 `InboundReceipt.providerInboundId` 为 null,
|
|
|
|
|
**不拿来源单号顶替**——后续查详情 / 取消只能用 `orderNo`(来源单号)。
|
|
|
|
|
|
|
|
|
|
**草稿语义**:`status=0` 是草稿,草稿状态下再调本接口是**更新**而非新建。
|
|
|
|
|
由调用方经 `InboundCommand.documentStatus()` 决定,适配器不猜。
|
|
|
|
|
|
|
|
|
|
**柜型映射**:恒健把 20GP / 40GP / 40HQ / 45HQ 拆成独立字段
|
|
|
|
|
(`gpQuantity20` / `gpQuantity40` / `hqQuantity40` / `hqQuantity45` + 各自箱号)。
|
|
|
|
|
统一模型用 `InboundCommand.Container(柜型, 数量, 箱号)` 表达;**认不出的柜型直接拒绝**
|
|
|
|
|
——静默丢弃等于少报柜数。
|
|
|
|
|
|
|
|
|
|
**其它字段映射**:
|
|
|
|
|
|
|
|
|
|
| 恒健 | 统一模型 |
|
|
|
|
|
|---|---|
|
|
|
|
|
| `lineCode` | `lineName`(项目名称) |
|
|
|
|
|
| `batchNumber` | `factoryBatchNo` |
|
|
|
|
|
| `poNos` | `purchaseOrderNos`(逗号分隔) |
|
|
|
|
|
| `shippingCompany` | `shippingCompanyName`(**名称**,与信仓的 `shippingCompanyId` 不同) |
|
|
|
|
|
| `goodsType`(2 集装箱 / 4 卡车) | `goodsType`(**不是** `containerSize` 也不是 `deliveryType`) |
|
|
|
|
|
| `actualShipDate` / `estimateArriveTime` / `expectArriveDate` / `predictionShipDate` | 同名日期,`yyyy-MM-dd` |
|
|
|
|
|
| `cartonItems` | `InboundCarton` 列表(外箱尺寸 cm / 重量 g) |
|
|
|
|
|
| `tmsNo` | `transportOrderNos` 逗号拼接 |
|
|
|
|
|
|
|
|
|
|
**只为这个接口给 core 加的字段**:`documentStatus` / `purchaseOrderNos` / `actualShipDate` /
|
|
|
|
|
`goodsType` / `shippingCompanyName` / `containers`。其它仓不读这些字段,行为不变。
|
|
|
|
|
|
|
|
|
|
**未接入**:取消 / 加附件 / 发运 / 预约单,调用显式抛异常。
|
|
|
|
|
|
|
|
|
|
#### 入库箱标生成(`/v2/inbound/boxLabelGenerate`)
|
|
|
|
|
|
|
|
|
|
**真机确认的必填项**(空 body 一次性列出全部缺失项):
|
|
|
|
|
|
|
|
|
|
```
|
|
|
|
|
inboundPlanOrderNo(单号不能为空)
|
|
|
|
|
type(类型不能为空)
|
|
|
|
|
pageSize(每页个数不能为空)
|
|
|
|
|
isIndexNo(是否生成数字标不能为空)
|
|
|
|
|
isOriginCountry(是否展示原产地不能为空)
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
`paperType`(1 A4 / 2 10×10)与 `fileNamingType`(0 按入库计划名 / 1 按来源单号)选填。
|
|
|
|
|
|
|
|
|
|
**响应无 data**:只有 `code / message`("生成箱标成功"),
|
|
|
|
|
**不回任务号、不回文件**。文件要去入库计划详情的 `packingLabelUrl` 里取。
|
|
|
|
|
所以 `LabelPrintTask.taskNo()` 恒为 null——**不代表调用失败**,看有没有抛异常。
|
|
|
|
|
|
|
|
|
|
**与运去哪口径不同**:
|
|
|
|
|
|
|
|
|
|
| 统一模型 | 恒健 | 说明 |
|
|
|
|
|
|---|---|---|
|
|
|
|
|
| `twoCopies` | `type` 1/2 | 恒健是**份数**码,不是布尔 |
|
|
|
|
|
| `labelsPerPage` | `pageSize` | 1 或 6,与运去哪同值 |
|
|
|
|
|
| `sizeType` / `downloadMode` | — | 恒健没有这两个口径,改用 `paperType` |
|
|
|
|
|
|
|
|
|
|
**两个开关不允许留空**:`isIndexNo` / `isOriginCountry` 仓方标必填,统一模型是 null-able;
|
|
|
|
|
适配器在 null 时**拒绝而不是猜**——猜「是」每箱多印一行,猜「否」漏印。
|
|
|
|
|
|
|
|
|
|
**为这个接口给 core 改的东西**:
|
|
|
|
|
- `BoxLabelCommand` 补 `showIndexNo` / `showOriginCountry` / `paperTypeCode` / `fileNamingType`
|
|
|
|
|
- `LabelPrintTask.taskNo` 改为**可空**(恒健不回任务号),Javadoc 说明了 null 的含义
|
|
|
|
|
|
|
|
|
|
### 退货查询入口说明
|
|
|
|
|
|
|
|
|
|
退货列表 / 处理单列表**全部走门面**(`returns().query(...)` / `returns().queryHandles(...)`),
|
|
|
|
|
不再有「适配器私有多条件方法」——那种方法绕过 `CallSupport.observe`,操作日志会漏记。
|
|
|
|
|
|
|
|
|
|
适配器上剩下的 public 方法只有协议扩展点(如 `HengjianProductQueryMapper` 之类的静态工具),
|
|
|
|
|
不直接对外暴露。
|
|
|
|
|
|
|
|
|
|
### 商品查询(`/v2/product/queryPage`)—— 已接入
|
|
|
|
|
|
|
|
|
|
真机确认(2026-11-17):无 token 时 `403 Unauthorized`,**鉴权先于参数校验**,必填项按文档实现。
|
|
|
|
|
|
|
|
|
|
#### 分页字段说明写反了
|
|
|
|
|
|
|
|
|
|
| 字段 | 文档说法 | 实际含义(按响应) |
|
|
|
|
|
|---|---|---|
|
|
|
|
|
| `pageSize` | 「页码」 | **每页条数** |
|
|
|
|
|
| `pageNum` | 「页数」 | **页码** |
|
|
|
|
|
|
|
|
|
|
响应里的 `pageSize` / `pageNum` 含义是明确的,所以按响应实现。请求侧两个字段都是 **STRING**。
|
|
|
|
|
|
|
|
|
|
#### 响应结构
|
|
|
|
|
|
|
|
|
|
`data` 是**分页对象**(不是数组):`{total, pageSize, pageNum, data[]}`。
|
|
|
|
|
是否还有下一页按 `total` 判断,不看本页是否满。
|
|
|
|
|
|
|
|
|
|
#### 文档漏了 `length`
|
|
|
|
|
|
|
|
|
|
商品主体长宽高里文档只列了 `width` / `height` 与 `itemLength`,**没有 `length`**,
|
|
|
|
|
但建档接口有。映射时优先 `length`,缺失退回 `itemLength`——两者语义不同
|
|
|
|
|
(主体 vs 单品),兜底只为不让「查回来没有长」变成 null。
|
|
|
|
|
|
|
|
|
|
#### 字段映射
|
|
|
|
|
|
|
|
|
|
| 恒健 | 落点 |
|
|
|
|
|
|---|---|
|
|
|
|
|
| `sku` / `upc` | `omsSku` / `barcode` |
|
|
|
|
|
| `name` / `nameEn` / `description` / `remark` | 同名 |
|
|
|
|
|
| `length` / `width` / `height` / `weight` | cm / cm / cm / g |
|
|
|
|
|
| `itemLength` / `itemWidth` / `itemHeight` | 单品尺寸 |
|
|
|
|
|
| `measurementLength` / `Width` / `Height` / `Weight` | **仓方实测**,与申报尺寸分开存 |
|
|
|
|
|
| `packedQty` / `packedLength` / `Width` / `Height` / `Weight` | 外箱 |
|
|
|
|
|
| `expirationControl`(0/1)/ `expirationDate` | `expirationControl` / `expirationDays` |
|
|
|
|
|
| `cost` + `currency` | `cost`(Money) |
|
|
|
|
|
| `isInsuranceFlag`(Y/N)/ `isInsuranceRate` | `insured` / `insuranceFee` |
|
|
|
|
|
| `productType`(1 成品 / 2 配件 / 3 耗材) | `productType` |
|
|
|
|
|
|
|
|
|
|
### 销毁(`DESTRUCTION`)—— 已接入,**路径未真机确认**
|
|
|
|
|
|
|
|
|
|
> **⚠ 重要**:2026-11-17 在测试环境对文档路径及 **26 个变体**请求,
|
|
|
|
|
> **全部返回 `404 No handler found`**;同环境其它接口(`/v1/saleOrder/create`、
|
|
|
|
|
> `/v1/trackingChange/findOrder`)正常响应,说明不是网络问题。
|
|
|
|
|
>
|
|
|
|
|
> 可能是接口未上线 / 只在生产部署 / 命名体系完全不同。代码按文档实现,
|
|
|
|
|
> **联调时必须先核对路径**,若不同只改 `HengjianConstants` 一处常量。
|
|
|
|
|
|
|
|
|
|
#### 创建(`/v2/destroyPlanOrder/create`)
|
|
|
|
|
|
|
|
|
|
- **字段笔误照抄**:`hopeDestroyData`(**Data 不是 Date**),创建与查询两侧都是这个拼写。
|
|
|
|
|
写成 `hopeDestroyDate` 仓方会当成没传。
|
|
|
|
|
- **`orderNo` 不传**:文档标必填,但请求示例里没有;我们下发的 OMS 销毁单号走 `sourceNo`,
|
|
|
|
|
仓方自己生成计划单号。
|
|
|
|
|
- **响应无 data**:只有 `code / message`,**不回仓单号也不回状态**。所以
|
|
|
|
|
`providerDestructionId` 与 `status` 都留 null——不拿来源单号冒充仓单号,
|
|
|
|
|
也不把「已提交」当「已执行」。
|
|
|
|
|
|
|
|
|
|
#### 查询(`/v2/destroyPlanOrder/find`)
|
|
|
|
|
|
|
|
|
|
- **请求体是裸数组** `["单号1","单号2"]`,不是对象包装。
|
|
|
|
|
- 响应 `data` 也是数组;**查不到的单号不返回**(不是返回空对象)。
|
|
|
|
|
- 文档说传「销毁计划单单号集合」,但示例里数组的值正是响应里的 `sourceNo`——
|
|
|
|
|
所以按**来源单号**(我们下发的 `destructionNo`)查。适配器还允许传仓方计划单号,
|
|
|
|
|
因为两边都逐条比对。
|
|
|
|
|
- 适配器只查一个单号,返回匹配的那条,没有则 null。
|
|
|
|
|
|
|
|
|
|
#### 状态码表(`HengjianDestructionStatus`)
|
|
|
|
|
|
|
|
|
|
0 草稿 / 1 提交待审核 / 2 已审核待销毁 / 3 审核不通过 / 4 销毁中 / 5 完成 / 10 取消。
|
|
|
|
|
|
|
|
|
|
**core 没有销毁状态的底层枚举**,所以这里保留仓方码 + 中文名,不硬造一套跨仓枚举
|
|
|
|
|
(运去哪的销毁接口根本不回状态)。`DestructionOrder.status()` 填中文名、
|
|
|
|
|
`rawStatus()` 填原值数字。
|
|
|
|
|
|
|
|
|
|
#### 为这两个接口给 core 加的字段
|
|
|
|
|
|
|
|
|
|
`DestructionCommand`:`lineName`(项目名称,原先没有入口)
|
|
|
|
|
`DestructionOrder`:`lineName` / `hopeDestroyDate` / `createdAt`
|
|
|
|
|
|
|
|
|
|
### 退货查询与处理方式 —— 已接入
|
|
|
|
|
|
|
|
|
|
#### 请求形态有两套,不能混
|
|
|
|
|
|
|
|
|
|
| 接口 | 形态 |
|
|
|
|
|
|---|---|
|
|
|
|
|
| `getReturnPlanOrderInfo` | **双层包裹** `{"params":{"orderNo"}}` |
|
|
|
|
|
| `getReturnPlanOrderPage` | **双层包裹**,`page` / `size` 文档标 **string** |
|
|
|
|
|
| `getReturnPlanHandlePage` | **平铺**(无 `params`) |
|
|
|
|
|
| `handlingMethod` | **平铺** |
|
|
|
|
|
|
|
|
|
|
发错形态仓方会当成空请求。
|
|
|
|
|
|
|
|
|
|
无 token 的表现也不同:thirdParty 那两个直接用 `403`,
|
|
|
|
|
`getReturnPlanHandlePage` / `handlingMethod` 回 `500 + 999999 + "查询失败/处理失败:Unauthorized"`。
|
|
|
|
|
**这四个接口都不做参数校验**,必填项只能按文档实现。
|
|
|
|
|
|
|
|
|
|
#### 三套码表,别混
|
|
|
|
|
|
|
|
|
|
| 码表 | 取值 |
|
|
|
|
|
|---|---|
|
|
|
|
|
| 计划状态 `returnPlanStatus` | 0 草稿 / 5 待审核 / 10 审核拒回 / 15 待收货 / 20 待处理 / 25 已完成 / 30 已取消 / 35 处理中 |
|
|
|
|
|
| 处理状态 `handlingStatus` | 5 待处理 / 10 处理中 / 15 已完成 / 20 已取消 |
|
|
|
|
|
| 主要处理方式 `primaryHandlingMethod` | 101 拍外观 / 102 拆箱拍照 / 103 拆箱拍照并封箱 / 201 销毁 / 202 上架良品 / 203 换标上架 / 204 卖家自提 / 205 重新包装 / 206 仓库拆箱判断 |
|
|
|
|
|
|
|
|
|
|
同一个 `20`:计划状态是「待处理」,处理状态是「已取消」。三套互不通用。
|
|
|
|
|
|
|
|
|
|
#### 详情(`getReturnPlanOrderInfo`)
|
|
|
|
|
|
|
|
|
|
- 单号既可是计划单号,也可是来源单号——响应同时回 `returnPlanNo` 与 `sourceOrderNo`。
|
|
|
|
|
- 双号映射:`returnRequestNo = sourceOrderNo`(缺失时退回计划单号)、
|
|
|
|
|
`providerReturnId = returnPlanNo`。
|
|
|
|
|
- SKU 明细 `returnPlanSkuList` → `WarehouseReturn.lines()`;
|
|
|
|
|
换标上架明细 `relabelShelfSkuItems[].changeSku` → `newSku`。
|
|
|
|
|
- `returnPlanHandleList` / `returnPlanExecuteDetails`(待处理 / 已处理)
|
|
|
|
|
**不塞进 `lines`**(那是 SKU 维度),需要处理单时用处理单列表接口查。
|
|
|
|
|
- `sourceType` **两页文档顺序相反**:创建页写「1 无来源 2 销售」,详情页写「1 销售 2 无来源」。
|
|
|
|
|
适配器不解释,原值保留在 `type()`。
|
|
|
|
|
- `data` 为空 → 返回 `null`。
|
|
|
|
|
|
|
|
|
|
#### 列表(`getReturnPlanOrderPage`)
|
|
|
|
|
|
|
|
|
|
- `page` / `size` 文档标 **string**,下发转字符串。
|
|
|
|
|
- **状态过滤是单值**(`returnPlanStatus` 不是数组);给多个时**拒绝**,
|
|
|
|
|
静默只取一个会让调用方以为筛全了。
|
|
|
|
|
- **原值状态**:统一枚举有损——`RETURNING` 对应仓方的 20(待处理)和 35(处理中),
|
|
|
|
|
归一层表达不了。要精确筛「处理中」时给 `ReturnQuery.rawStatus(raw)`,
|
|
|
|
|
与 `status(...)` **互斥**。
|
|
|
|
|
- **单号与 tracking 不能同时给**:恒健只有一组 `queryType/queryValue`。
|
|
|
|
|
- **时间窗**由 `queryDataType` 指定作用于哪个字段(1 创建 / 2 修改 / 4 完成),
|
|
|
|
|
起止必须成对。
|
|
|
|
|
- `queryDataType`(1 创建 / 2 修改 / 4 完成)+ 时间区间,与
|
|
|
|
|
`queryType`(1 计划单号 / 2 来源单号 / 3 关联订单号 / 4 tracking)+ `queryValue`
|
|
|
|
|
是两组独立的过滤口径。
|
|
|
|
|
- 仓库 code 收**逗号拼接的字符串**,不是数组。
|
|
|
|
|
- `RETURNING` 无法唯一映射回恒健状态(对应 20 或 35),映射函数返回 null,
|
|
|
|
|
调用方要明确选一个。
|
|
|
|
|
|
|
|
|
|
#### 处理单列表(`getReturnPlanHandlePage`)
|
|
|
|
|
|
|
|
|
|
- 过滤条件**全是数组**;`handlingStatusList` 用 5/10/15/20 那套码。
|
|
|
|
|
- 恒健没有对应的统一模型,适配器直接返回仓方的处理单行
|
|
|
|
|
(`HengjianReturnHandleDtos.HandleRow`),供宿主填写处理方式与回收照片。
|
|
|
|
|
- 时间戳是 ISO 带时区(`2025-08-14T01:32:32.000+0000`),解析时转换成 `Z` 再解析。
|
|
|
|
|
|
|
|
|
|
#### 填写处理方式(`handlingMethod`)
|
|
|
|
|
|
|
|
|
|
- 用 **`returnPlanNo + returnNo + erpSku + tracking` 四项定位**,不用行 id——
|
|
|
|
|
与运去哪的条目处理接口不同(那个只认 `items[].id`)。
|
|
|
|
|
- **两级处理方式**:`handlingMethod`(1 继续拍照 / 2 处理方式)是开关,
|
|
|
|
|
`primaryHandlingMethod`(101~206)是具体动作。
|
|
|
|
|
- `handlingMethod=1`(继续拍照)必须给正的 `photosQuantity`,本地先挡。
|
|
|
|
|
- core 的 `ReturnProcessDisposition` 只能映射 4 个:销毁 201 / 上架良品 202 /
|
|
|
|
|
换标上架 203 / 卖家自提 204。**拍照类(101~103)、重新包装(205)、
|
|
|
|
|
仓库拆箱判断(206)必须显式给仓方原值**——core 没有对应语义,强行归一会丢信息。
|
|
|
|
|
|
|
|
|
|
#### 为这四个接口给 core 改的东西
|
|
|
|
|
|
|
|
|
|
`ReturnProcessCommand`:
|
|
|
|
|
- `lineId` 从 `long` 改为 `Long` 且可空(恒健按四项定位,不用行 id);
|
|
|
|
|
需要行 id 的仓(运去哪)在适配器里显式校验,已加守卫。
|
|
|
|
|
- `disposition` 改为可空,与 `primaryHandlingMethod` **至少给一个**。
|
|
|
|
|
- 新增 `returnNo` / `erpSku` / `tracking` / `handlingMethod` /
|
|
|
|
|
`primaryHandlingMethod` / `photosQuantity`。
|
|
|
|
|
|
|
|
|
|
### 退货计划创建(`/v1/saleReturn/thirdParty/saveReturnPlan`)—— 已接入
|
|
|
|
|
|
|
|
|
|
**请求是双层包裹**:所有业务字段都在 `params` 下,不是顶层。发错层级仓方会当成空请求。
|
|
|
|
|
|
|
|
|
|
**真机情况**:这个接口无 token 时**直接回 403、不做参数校验**——与
|
|
|
|
|
`createInboundPlan` / `transferPlan/create` 不同(那两个会先做参数校验)。
|
|
|
|
|
所以必填项只能按文档字段表实现,**待带 token 真机验证**。
|
|
|
|
|
|
|
|
|
|
**按文档实现的必填项**:`orgWarehouseCode`、`returnSkuArr`(非空),每行还要
|
|
|
|
|
`erpSku` / `returnQuantity` / `returnShippingMethod` / `tracking`。缺哪项本地拒绝并点名。
|
|
|
|
|
|
|
|
|
|
| 项 | 处理 |
|
|
|
|
|
|---|---|
|
|
|
|
|
| `returnShippingMethod` | 必填,取值需先经「获取运输方式」接口取得(如 `AMAT`);缺值本地拒绝 |
|
|
|
|
|
| `tracking` | 挂在**行**上(必填),而统一模型的 `returnTrackingNo` 是命令级:行级优先、否则退回命令级 |
|
|
|
|
|
| `treatmentMethodForAppearanceDamage` | 文档标 integer、示例给字符串 `"2"`;按字符串下发 |
|
|
|
|
|
| `threeRdAccount` | 文档里就是**三个 d**,照抄 |
|
|
|
|
|
| `sourceType` | 1 无来源退货 / 2 销售退货;统一模型是 `Integer`,下发时转字符串 |
|
|
|
|
|
| 响应 | 只回头级信息,**不回明细行**——需要明细要再查详情,不凭空造 |
|
|
|
|
|
|
|
|
|
|
#### 状态枚举(`HengjianReturnPlanStatus`)
|
|
|
|
|
|
|
|
|
|
8 个值:0 草稿 / 5 待审核 / 10 审核拒回 / 15 待收货 / 20 待处理 / 25 已完成 /
|
|
|
|
|
30 已取消 / 35 处理中。
|
|
|
|
|
|
|
|
|
|
**20 待处理与 35 处理中是两个状态**:前者还在排队,后者仓已在作业。合并就分不出来。
|
|
|
|
|
|
|
|
|
|
> 注意另一套码表:退货计划列表的 `handlingStatus`(处理状态)是
|
|
|
|
|
> 5 待处理 / 10 处理中 / 15 已完成 / 20 已取消,与计划状态**不是一套**。
|
|
|
|
|
|
|
|
|
|
#### 只为这个接口给 core 加的字段
|
|
|
|
|
|
|
|
|
|
`ReturnCommand`:`sourceType` / `associatedNo` / `consignor` / `channelAccount` /
|
|
|
|
|
`returnAddress` / `thirdPartyAccount` / `returnDate`;
|
|
|
|
|
`ReturnCommandLine`:`returnShippingMethod` / `trackingNumber` / `appearanceDamageTreatment`
|
|
|
|
|
|
|
|
|
|
**未接入**:退货查询(详情 / 列表)、处理方式设置、取消。调用显式抛异常。
|
|
|
|
|
|
|
|
|
|
### 调拨(`TRANSFER`)—— 已接入
|
|
|
|
|
|
|
|
|
|
#### 创建(`POST /v1/transferPlan/create`)
|
|
|
|
|
|
|
|
|
|
**真机确认的必填项**(按校验顺序):`outOrgWarehouseCode` → `inOrgWarehouseCode` →
|
|
|
|
|
`estimateOutboundTime` → `estimateInboundTime`。
|
|
|
|
|
|
|
|
|
|
文档另标了 `projectUnicode` / `transportationType` / `inventoryType` / `isLabel` /
|
|
|
|
|
`receiveStore` / 六个 `shipTo*` 为必填,但**真机校验里没有它们**——不传也能过(只停在鉴权)。
|
|
|
|
|
按选填实现,与入库创建的 `currency` 是同一类情况。
|
|
|
|
|
|
|
|
|
|
| 项 | 处理 |
|
|
|
|
|
|---|---|
|
|
|
|
|
| `details[].qty` | 文档标 **STRING**(不是 INTEGER),按字符串下发;查询响应里是数字,两个 DTO 各声明 |
|
|
|
|
|
| 日期 | 统一模型是 `LocalDate`,恒健要 `yyyy-MM-dd HH:mm:ss`:补当天 `00:00:00`,**不编造具体时刻** |
|
|
|
|
|
| `refferenceId` | 文档里就是**三个 f**,照抄 |
|
|
|
|
|
| `inOrgWarehouseCode=Other` | 外部仓库的固定代号;此时统一模型的 `type` 映射为 `OUTBOUND` |
|
|
|
|
|
| `transportationType` | 1 客户安排 / 2 仓库安排;未指定(0)按「仓库安排」兜底并在文档注明;其它值拒绝 |
|
|
|
|
|
| 响应 | `data` 是**字符串单号**(不是对象);拿不到单号即报错,不当创建成功 |
|
|
|
|
|
|
|
|
|
|
创建接口**不回状态**:`TransferOrder.status` 保持 `UNKNOWN`,不拿请求侧的值冒充。
|
|
|
|
|
|
|
|
|
|
#### 查询(`GET /v1/transferPlan/findByPage`)
|
|
|
|
|
|
|
|
|
|
- `page` / `rows` / `sidx` / `sort` 必填(`sidx=id`、`sort=desc`);`rows` 默认最高 **100**,超限拒绝。
|
|
|
|
|
- 过滤参数都是**单值**(`sourceNo` / `transferOutboundPlanNo` / `projectUnicode` /
|
|
|
|
|
`outOrgWarehouseCode` / `inOrgWarehouseCode`)——与其它接口不同,这里给多个单号时
|
|
|
|
|
只下发第一个(语义是「按这个单号查」,多给没有意义),文档已注明。
|
|
|
|
|
- 响应 `data` 是标准分页信封;游标换算同订单 / 库存列表(`number + 2`)。
|
|
|
|
|
|
|
|
|
|
#### 取消(`GET /v1/transferPlan/cancel`)
|
|
|
|
|
|
|
|
|
|
- **参数在 query,不是 body**;真机确认 `sourceNo` 必填
|
|
|
|
|
(缺了回 `Required String parameter 'sourceNo' is not present`)。
|
|
|
|
|
- 统一模型里落在 `TransferCapable.deleteTransfer`——恒健叫「取消」,语义等价于撤销。
|
|
|
|
|
- 恒健**没有取消费概念**;仓方拒绝时原样抛业务异常(如「未查询到对应调拨计划数据」),
|
|
|
|
|
不伪装成成功。
|
|
|
|
|
|
|
|
|
|
#### 状态枚举(`HengjianTransferStatus`)
|
|
|
|
|
|
|
|
|
|
13 个值:0 草稿 / 3 已驳回 / 5 待审核 / 7 审核通过 / 8 待确认 / 10 待出库 /
|
|
|
|
|
15 出库中 / 20 待入库 / 25 入库中 / 70 已完成 / 90 已关闭 / 100 取消中 / 110 已取消。
|
|
|
|
|
|
|
|
|
|
**精确匹配**,未知归 `UNKNOWN` 不猜。`100`(取消中)与 `110`(已取消)**不合并**——
|
|
|
|
|
合并就分不出「取消请求已发出」和「仓方已确认取消」。
|
|
|
|
|
|
|
|
|
|
#### 只为这些接口给 core 加的字段
|
|
|
|
|
|
|
|
|
|
`TransferCommand`:`projectCode` / `relabelProducts` / `referenceId` / `deliveryDate` /
|
|
|
|
|
`externalDestination`
|
|
|
|
|
`TransferOrder`:`projectCode` / `attachments`
|
|
|
|
|
`TransferQuery`(新增模型)+ `TransferCapable.queryTransfers()` + 门面 `queryTransfers()`
|
|
|
|
|
|
|
|
|
|
#### 未接入
|
|
|
|
|
|
|
|
|
|
`approve`(审核)与 `getTransfer`(按单号查详情)恒健没有对应接口,保持默认拒绝。
|
|
|
|
|
|
|
|
|
|
### 入库计划详情 / 列表(`INBOUND`)—— 已接入
|
|
|
|
|
|
|
|
|
|
两个接口回的对象**字段完全一致**,只有外层形状不同(`data` 对象 vs `data.content[]` 分页信封),
|
|
|
|
|
所以共用一份行模型与映射。
|
|
|
|
|
|
|
|
|
|
#### 详情(`/v1/inbound/getInboundPlanInfo`)
|
|
|
|
|
|
|
|
|
|
- 真机确认 `orderNo` 必填(空 body 回「单号不能为空」)。
|
|
|
|
|
- 单号可以是**仓方计划单号**,也可以是**来源单号**——响应同时回 `inboundPlanOrderNo` 与 `sourceNo`。
|
|
|
|
|
- 双号映射:`inboundRequestNo = sourceNo`(缺失时退回仓单号)、`providerInboundId = inboundPlanOrderNo`。
|
|
|
|
|
- `data` 为空 → 返回 `null`(查不到),不造空单。
|
|
|
|
|
|
|
|
|
|
#### 列表(`/v1/inbound/getInboundPlanPage`)
|
|
|
|
|
|
|
|
|
|
- `page` / `size` 文档标必填,真机不传也能过校验(只停在鉴权);仍按文档下发。
|
|
|
|
|
- 支持的过滤维度:仓 / 计划单号 / 来源单号 / 状态码 / 库存类型 / 七种时间区间 / Amazon shipmentId。
|
|
|
|
|
- **状态过滤要转数字码**(`inboundPlanOrderStatusList` 是 int 数组);
|
|
|
|
|
认不出的状态**拒绝**,不猜——猜错会拉回一大堆无关单。
|
|
|
|
|
- 时间区间是**单值字符串** `yyyy-MM-dd ~ yyyy-MM-dd`,不是一个 start/end 对。
|
|
|
|
|
- 统一模型 `InboundQuery` 只表达三种时间窗(创建 / 更新 / 完成);恒健另有四种
|
|
|
|
|
(期望到货 / 预计发货 / 预计入库 / 首次接收),模型里没有——需要时再扩字段。
|
|
|
|
|
- 页大小上限 200(文档没写,保守值);超限拒绝不截断。
|
|
|
|
|
|
|
|
|
|
#### 状态枚举(`HengjianInboundStatus`)
|
|
|
|
|
|
|
|
|
|
**两套码表不能混**:
|
|
|
|
|
|
|
|
|
|
| 来源 | 码表 |
|
|
|
|
|
|---|---|
|
|
|
|
|
| 计划单 `inboundPlanOrderStatus` / 列表过滤参数 | 0 草稿 / 5 待审核 / 6 审核拒回 / 8 待装箱 / 10 待发货 / 15 待接收 / 20 待入库 / 25 入库中 / 70 已完成 / 100 已取消 |
|
|
|
|
|
| 收货单 `inboundOrderList[].inboundOrderStatus` | 0 草稿 / 70 已完成 / 90 已关闭 |
|
|
|
|
|
|
|
|
|
|
同一个值 `70` 在两张表里都表示「已完成」纯属巧合;`0` 一个是草稿、另一个也是草稿但语义不同套。
|
|
|
|
|
适配器只把**计划单**的状态归一成 `InboundStatus`,收货单的状态原样保留。
|
|
|
|
|
|
|
|
|
|
枚举的 `of()` 同时认数字串(`"70"`)与中文名(`"已完成"`)——因为详情字段表标 STRING、
|
|
|
|
|
示例给 `"70"`,而列表请求参数是数字数组,三种形态都出现过。
|
|
|
|
|
|
|
|
|
|
#### 数量三层的口径
|
|
|
|
|
|
|
|
|
|
`planQty` / `packedQty` / `receivedQty` → `plannedQuantity` / `packedQuantity` / `receivedQuantity`,
|
|
|
|
|
**不重算**——仓方给的就是准的,重算会掩盖仓方的数据问题。
|
|
|
|
|
|
|
|
|
|
产品行的 `qtyReceivedSaleable` / `qtyReceivedUnsaleable` 分开映射;两者都为 0 而
|
|
|
|
|
`qtyReceived > 0` 时按可售兜底(总数一致,不编造拆分)。
|
|
|
|
|
|
|
|
|
|
#### 收货单 → 批次
|
|
|
|
|
|
|
|
|
|
`inboundOrderList` 是**实际收货单**,落成 `InboundOrderBatch` 的 `INBOUNDED` 阶段。
|
|
|
|
|
收货单号作为 `cartonNo`(该粒度没有独立箱号);库存类型保持 null(收货单层面没有细分)。
|
|
|
|
|
|
|
|
|
|
### 库存(`INVENTORY_QUERY`)—— 已接入
|
|
|
|
|
|
|
|
|
|
恒健有**两个**库存接口,能力不同,统一模型只有一个 `query()`,按「给了什么」分流:
|
|
|
|
|
|
|
|
|
|
| 条件 | 接口 | 分页 | 过滤维度 |
|
|
|
|
|
|---|---|---|---|
|
|
|
|
|
| 给 `providerSkus` | `POST /v1/inventory/getInventory` | **不分页** | 只按 SKU |
|
|
|
|
|
| 只给 `warehouseCodes` | `GET /v2/inventory/get_inventory_by_page` | 分页,rows ≤ 500 | 只按仓 |
|
|
|
|
|
| 两个都给 | — | — | **拒绝**:恒健没有这种接口 |
|
|
|
|
|
| 都不给 | — | — | **拒绝**:不能因为缺省就退化成整仓全量 |
|
|
|
|
|
| 给 `updatedAfter` | — | — | **拒绝**:恒健不支持增量,策略是 `FULL_PULL_DIFF` |
|
|
|
|
|
|
|
|
|
|
其它被拒绝的过滤项:`inventoryType` / `includeZeroStock`(恒健库存接口没有这两个参数)。
|
|
|
|
|
|
|
|
|
|
**字段名两套写法**:分页接口的文档字段表写 `snake_case`(`warehouse_code`),
|
|
|
|
|
同一页的返回示例却写 `camelCase`(`warehouseCode`)。DTO 用 `@JsonAlias` 同时接住两种,
|
|
|
|
|
不多花钱但能防一次真机翻车。
|
|
|
|
|
|
|
|
|
|
**`data` 形状两套**:分页接口的字段表说 `data` 是对象,返回示例却是数组。
|
|
|
|
|
适配器用 `JsonNode` 判形状后分流,两种都接住。
|
|
|
|
|
|
|
|
|
|
**数量字段类型不一致**:`inventoryTransport` / `inventoryCurrent` 文档标 STRING,
|
|
|
|
|
`inventoryAvailable` 标 INTEGER。统一按文本转 int。
|
|
|
|
|
|
|
|
|
|
**`updatedAt` 必须有值**:快照时间是对账对齐的依据,仓方没给时**报错**而不是填
|
|
|
|
|
`EPOCH`——填 EPOCH 会让「物理库存 vs 逻辑库存」比对得出错误结论。
|
|
|
|
|
|
|
|
|
|
**同步策略**:`FULL_PULL_DIFF`。两个库存接口都没有 `updatedAfter` 入参,
|
|
|
|
|
只能全量拉后自己做差异比对。流水接口虽然能按日期查,但那是**变动明细**、不是余额,
|
|
|
|
|
不能拿来重建当前库存。
|
|
|
|
|
|
|
|
|
|
#### 库存变动流水(`/v1/inventory/task/query`)
|
|
|
|
|
|
|
|
|
|
- **必填**(真机确认):`skus`(非空数组)、`beginDateTime`、`endDateTime`(`yyyy-MM-dd`)。
|
|
|
|
|
缺任一项回 `MethodArgumentNotValidException` 并列出所有缺的字段。
|
|
|
|
|
- **日期跨度 ≤ 30 个自然日(含首尾)**:`10-01~10-30` 合法,`10-01~10-31` 非法
|
|
|
|
|
(真机回「查询日期最多包含30个自然日」)。适配器按含首尾口径算,正好 30 天放行。
|
|
|
|
|
- **rows ≤ 100**(文档明写 1~100),超过拒绝不截断。
|
|
|
|
|
- 这是**流水**不是余额:`changeQty` 按原值返回、**不转正负号**,方向看 `inventoryChangeType`。
|
|
|
|
|
- 单行缺 `sku` 或 `createTime` 时**跳过该行**而不是整页失败——流水是明细,跳过一行比
|
|
|
|
|
拿不到整页有用;缺多少行由调用方对账发现。
|
|
|
|
|
- core 新增 `InventoryMovement` / `InventoryMovementQuery` / `queryMovements()`。
|
|
|
|
|
|
|
|
|
|
### 运费测算与地址属性 —— 已接入
|
|
|
|
|
|
|
|
|
|
#### 运费测算(`/v2/api/shipping/calculate`)
|
|
|
|
|
|
|
|
|
|
**真机确认的必填项**(文档把 `shipper*` 系列也标必填,但真机校验信息里没有它们):
|
|
|
|
|
|
|
|
|
|
`parcelLength / parcelWidth / parcelHeight / parcelWeight /
|
|
|
|
|
parcelLengthUnit / parcelWeightUnit /
|
|
|
|
|
receiverCountryCode / receiverState / receiverCity / receiverZipcode / receiverAddressLine1`
|
|
|
|
|
|
|
|
|
|
即**发货方信息可不传**。缺任一项时仓方回「参数校验异常」并列出所有缺的字段。
|
|
|
|
|
|
|
|
|
|
| 项 | 处理 |
|
|
|
|
|
|---|---|
|
|
|
|
|
| 单位 | 统一模型 cm / g,恒健也接受 `cm` / `g`,**不换算** |
|
|
|
|
|
| 包裹尺寸 | 恒健字段是 **INTEGER**,厘米值**四舍五入**取整(截断会让报价偏低) |
|
|
|
|
|
| 价格口径 | `conversionTotalRate` 是**折算价**(客户实付)→ `totalRate`;`originalTotalRate` 是承运商牌价,统一模型无对应字段 |
|
|
|
|
|
| 物流服务码 | **选填**:不给由仓报全部渠道。`FeeEstimateQuery.logisticsServiceCode` 已从必填改为选填,运去哪那种要求必填的仓在适配器里拒绝 |
|
|
|
|
|
| 返回维度 | 恒健**不按仓返回**,统一结果只有一个实例,`shipOrgWarehouseCode` 用账户仓填充 |
|
|
|
|
|
|
|
|
|
|
#### 地址属性识别(`/v2/api/shipping/addressClassification`)
|
|
|
|
|
|
|
|
|
|
**文档域名写错了**:页面链接是 `open-api.thebizark.com`(别家域名)。真机确认本仓域名下可正常调用。
|
|
|
|
|
|
|
|
|
|
- 五项必填(真机):`street1 / zip / city / state / country`;`street2` 选填。
|
|
|
|
|
- 响应 `data` 是**字符串**:`BUSINESS / RESIDENTIAL / MIXED / UNKNOWN`。
|
|
|
|
|
- 映射到 core 的 `AddressType`;**认不出归 UNKNOWN,不猜**——猜错会多收或少收住宅附加费。
|
|
|
|
|
- `AddressType.residential()` 把 `MIXED` 也算住宅(附加费按住宅计)。
|
|
|
|
|
- 该能力单独一个能力位 `ADDRESS_CLASSIFICATION`,与试算分开:只判地址、不拉价格时用它。
|
|
|
|
|
|
|
|
|
|
### 计费明细(`FEE_SETTLEMENT`)—— 已接入
|
|
|
|
|
|
|
|
|
|
恒健把三类费用拆成<b>三个独立接口</b>,行字段完全不同:
|
|
|
|
|
|
|
|
|
|
| `FeeQuery.costType` | 接口 | 行特征 |
|
|
|
|
|
|---|---|---|
|
|
|
|
|
| `STORAGE` | `getChargingStorageSettlement` | 批次 / 库存类型 / 存储天数 / 计费量(CBM) |
|
|
|
|
|
| `LAST_MILE` | `getChargingTailDeliverySettlement` | 承运商 / 物流产品 / 计费重 / 分区 / 跟踪号 |
|
|
|
|
|
| `OPERATION` | `getChargingOperationSettlement` | 五级费用分类 / 计费阈值 / 箱数 |
|
|
|
|
|
|
|
|
|
|
**必须用 `costType` 指定查哪一类**:统一模型只有一个 `settlements()`,而三类接口的
|
|
|
|
|
返回结构不同。不指定就**拒绝**,而不是「三个都查再合并」——合并会让调用方以为
|
|
|
|
|
拿到完整账单,实际只覆盖了一部分。`VALUE_ADDED`(增值服务费)恒健没有独立接口,显式拒绝。
|
|
|
|
|
|
|
|
|
|
**请求**(三个接口一致):`orgWarehouseCodes` / `relOrderNos` / `sourceNos` /
|
|
|
|
|
`btChargeAt` 可选,`page` / `size` 必填。
|
|
|
|
|
|
|
|
|
|
| 统一模型 | 恒健 |
|
|
|
|
|
|---|---|
|
|
|
|
|
| `billingTransNo` | `relOrderNos`(计费单号) |
|
|
|
|
|
| `saleOrderNo` / `externalOrderNo` | `sourceNos`(来源单号,两者都当来源单号,重复只发一个) |
|
|
|
|
|
| `settledAfter/Before` 或 `snapshotDateRange` | `btChargeAt`,格式 `yyyy-MM-dd ~ yyyy-MM-dd` |
|
|
|
|
|
| 账户仓代码 | 自动带上 `orgWarehouseCodes`,避免跨仓混账 |
|
|
|
|
|
|
|
|
|
|
- **一条过滤条件都没有时本地拒绝**:等于拉全量账单。
|
|
|
|
|
- **仓过滤可配**:`FeeQuery.warehouseCodes()` 非空时用它(接口本就是复数仓),
|
|
|
|
|
空才退回账户仓。写死账户仓会让调用方无法表达「查全部仓」或「查其中几个仓」。
|
|
|
|
|
- **`providerSku` / `noType` 不支持**:恒健三个计费接口没有 SKU 维度、也没有
|
|
|
|
|
单号类型参数,传了就**拒绝**,不静默忽略。
|
|
|
|
|
- **`pageSize` 超上限(200)拒绝**:这个上限文档没写,是保守值。不静默截断——
|
|
|
|
|
截断会让调用方按自己的 pageSize 误判末页,漏账。
|
|
|
|
|
- **分页**:统一方法返回 `List`、不带游标,翻页靠
|
|
|
|
|
`query.toBuilder().pageCursor("2").build()`。判末页的约定是
|
|
|
|
|
**返回条数 < 本次请求的 `pageSize`**。`size` 未给时默认 100;超过 200 会拒绝
|
|
|
|
|
(上限文档没写,是保守值,待真机确认)。
|
|
|
|
|
- **状态口径**:三项都是账单明细(带 `billNo`),是<b>已发生账目</b>,
|
|
|
|
|
不是预估 → `estimated(false)`。
|
|
|
|
|
- **金额**:`cost` 是<b>该行总费用</b>,不是单价。`cost` 缺失的行**跳过**,
|
|
|
|
|
不用 0 兜底——0 会让对账金额偏小且查不出是哪行缺的。
|
|
|
|
|
- **费用类型由接口决定**,不靠猜 `settlementName`(作业费的名字形如
|
|
|
|
|
「退货入库->入库费->…」,靠字符串归类型迟早错)。
|
|
|
|
|
- **单号口径**:仓储费取 `sourceNo`;尾程费按 发货单号 → 来源单号 → 订单号 → 平台单号
|
|
|
|
|
依次兜底;作业费取 `relOrderNo` → `sourceNo`。`transactionNo` → `serialNumber`,
|
|
|
|
|
`billNo` → `documentNo`。
|
|
|
|
|
|
|
|
|
|
**文档问题**:作业费页的标题和链接都写成了「测算费用(接口)」和
|
|
|
|
|
`open-api.ehenglin.com/v2/api/shipping/calculate`(从测算页复制),只有路径与示例是对的。
|
|
|
|
|
另有两处类型不一致:仓储页 `btChargeAt` 是字符串、作业页字段表标 List;尾程页的
|
|
|
|
|
`sourceOrderNo` 中文名也写成「售后单号」。均按示例实现,待真机确认。
|
|
|
|
|
|
|
|
|
|
### 调拨 / 退货 / 销毁 / 测算
|
|
|
|
|
|
|
|
|
|
| 领域 | 规模 |
|
|
|
|
|
|---|---|
|
|
|
|
|
| 调拨 | 创建 / 查询 / 取消 / 上传附件(`/v1/transferPlan/...`) |
|
|
|
|
|
| 退货 | 旧版 3 个(标「废弃」)+ v2 10 个(`/v1/saleReturn/...`、`/v3/hj_wms/receiptReturn`) |
|
|
|
|
|
| 销毁 | 创建 / 取消 / 批量查询(`/v2/destroyPlanOrder/...`) |
|
|
|
|
|
| 测算 | 测算费用 `/v2/api/shipping/calculate`、地址属性 `/v2/api/shipping/addressClassification`(⚠ 域名可疑) |
|
|
|
|
|
|
|
|
|
|
## 4. 代码结构
|
|
|
|
|
|
|
|
|
|
```
|
|
|
|
|
warehouse-sdk-hengjian/
|
|
|
|
|
├── pom.xml
|
|
|
|
|
└── src/
|
|
|
|
|
├── main/java/common/ecommerce/hengjian/
|
|
|
|
|
│ ├── HengjianConstants.java 端点 / 路径 / 两个授权头 / 成功码 / 未授权码 / 限流
|
|
|
|
|
│ ├── adapter/
|
|
|
|
|
│ │ ├── HengjianAdapter.java 目录 + 渠道 + 商品 + 出库全链路 + 物流异动单
|
|
|
|
|
│ │ ├── HengjianAdapterFactory.java
|
|
|
|
|
│ │ ├── HengjianDirectoryMapper.java 仓库 / 渠道字段搬运
|
|
|
|
|
│ │ ├── HengjianProductMapper.java 商品报文 + 恒健必填项本地校验
|
|
|
|
|
│ │ ├── HengjianOutboundMapper.java 出库下单报文(UTC 时间 / 行总额 / 面单附件)
|
|
|
|
|
│ │ ├── HengjianOrderMapper.java 订单详情 / 列表 → 统一模型
|
|
|
|
|
│ │ ├── HengjianTrackingChangeMapper.java 异动单 → 统一模型
|
|
|
|
|
│ │ ├── HengjianFeeMapper.java 三个计费接口的请求构造 + 行映射
|
|
|
|
|
│ │ ├── HengjianEstimateMapper.java 运费测算 + 地址属性映射
|
|
|
|
|
│ │ ├── HengjianInventoryMapper.java 库存两个接口 + 变动流水
|
|
|
|
|
│ │ ├── HengjianInboundMapper.java 入库计划创建
|
|
|
|
|
│ │ ├── HengjianInboundQueryMapper.java 入库详情 / 列表
|
|
|
|
|
│ │ ├── HengjianTransferMapper.java 调拨创建 / 查询 / 取消
|
|
|
|
|
│ │ ├── HengjianReturnMapper.java 退货计划创建
|
|
|
|
|
│ │ └── HengjianReturnQueryMapper.java 退货详情 / 列表 / 处理单 / 处理方式
|
|
|
|
|
│ ├── dto/
|
|
|
|
|
│ │ ├── HengjianWarehouseDtos.java
|
|
|
|
|
│ │ ├── HengjianCarrierGroupDtos.java 两个渠道接口共用行模型
|
|
|
|
|
│ │ ├── HengjianProductSaveDtos.java /v1/product/save
|
|
|
|
|
│ │ ├── HengjianCreateOrderDtos.java /v1/saleOrder/create
|
|
|
|
|
│ │ ├── HengjianOrderDetailDtos.java /v1/saleOrder/findOne
|
|
|
|
|
│ │ ├── HengjianOrderListDtos.java /v1/saleOrder/findByPage
|
|
|
|
|
│ │ ├── HengjianCancelOrderDtos.java /v1/saleOrder/cancel
|
|
|
|
|
│ │ ├── HengjianTrackingChangeDtos.java /v1/trackingChange/create
|
|
|
|
|
│ │ ├── HengjianTrackingChangeQueryDtos.java /v1/trackingChange/findOrder
|
|
|
|
|
│ │ ├── HengjianStorageFeeDtos.java 仓储费明细
|
|
|
|
|
│ │ ├── HengjianTailDeliveryFeeDtos.java 尾程配送费明细
|
|
|
|
|
│ │ └── HengjianOperationFeeDtos.java 作业费明细
|
|
|
|
|
│ ├── enums
|
|
|
|
|
│ │ ├── HengjianOrderStatus.java orderStatusEnum → OutboundStatus
|
|
|
|
|
│ │ └── package-info.java 其余状态枚举约定(待建)
|
|
|
|
|
│ ├── http/
|
|
|
|
|
│ │ ├── HengjianRequestFactory.java 双授权头 + 链路 ID
|
|
|
|
|
│ │ ├── HengjianEnvelope.java 三种形态信封校验
|
|
|
|
|
│ │ └── HengjianRateLimiter.java
|
|
|
|
|
│ └── webhook/package-info.java 文档无回调,未实现
|
|
|
|
|
└── test/java/common/ecommerce/hengjian/
|
|
|
|
|
├── adapter/HengjianDirectoryTest.java 13 个:请求形状 / 鉴权头 / 映射 / 能力位
|
|
|
|
|
├── adapter/HengjianProductSaveTest.java 20 个:必填拒绝 / 三组尺寸 / 不编造字段
|
|
|
|
|
├── adapter/HengjianCreateOrderTest.java 23 个:必填拒绝 / UTC 时间 / 行总额 / 面单 / 未接入拒绝
|
|
|
|
|
├── adapter/HengjianOrderQueryTest.java 29 个:详情映射 / 分页 / 排序可配 / 时间窗 / 包裹去重
|
|
|
|
|
├── adapter/HengjianCancelOrderTest.java 10 个:双键补齐 / 精确匹配 / 拒绝路径 / 预判
|
|
|
|
|
├── adapter/HengjianTrackingChangeTest.java 27 个:必填 / 路径 / 双状态 / 收件人对照 / 承运商受理
|
|
|
|
|
├── adapter/HengjianFeeTest.java 22 个:三接口路由 / 分页 / 仓过滤 / 行映射 / 缺金额跳过
|
|
|
|
|
├── adapter/HengjianEstimateTest.java 14 个:必填项 / 取整 / 折算价 / 地址四值映射
|
|
|
|
|
├── adapter/HengjianInventoryTest.java 23 个:两接口分流 / snake_case / 30 天 / 流水映射
|
|
|
|
|
├── adapter/HengjianInboundCreateTest.java 17 个:必填 / 柜型 / 装箱 / 无仓单号
|
|
|
|
|
├── adapter/HengjianInboundQueryTest.java 18 个:详情映射 / 状态码表 / 列表过滤 / 分页
|
|
|
|
|
├── adapter/HengjianTransferTest.java 21 个:必填 / 字符串数量 / 外部仓 / 13 状态 / 取消
|
|
|
|
|
├── adapter/HengjianReturnCreateTest.java 16 个:params 包裹 / 行级四项 / 跟踪号回退 / 8 状态
|
|
|
|
|
├── adapter/HengjianReturnQueryTest.java 18 个:两套形态 / 三套码表 / 四项定位 / 处理方式映射
|
|
|
|
|
├── adapter/HengjianOrderAttachmentTest.java 12 个:平铺 / 类型整数 / base64 优先 / 本地校验
|
|
|
|
|
├── adapter/HengjianDestructionTest.java 16 个:Data 拼写 / 裸数组 / 7 状态 / 无仓单号
|
|
|
|
|
├── adapter/HengjianBoxLabelTest.java 11 个:五个必填 / 份数码 / 开关不猜 / 无任务号
|
|
|
|
|
├── adapter/HengjianAdapterTest.java 5 个:注册 / 能力拒绝 / 枚举
|
|
|
|
|
├── http/HengjianEnvelopeTest.java 12 个:三种信封形态 + 通用失败码 + 错误路径
|
|
|
|
|
├── probe/HengjianReadOnlyProbeTest.java 默认跳过,凭据走系统属性
|
|
|
|
|
└── probe/HengjianWriteProbeTest.java 默认跳过,另需 -Dhengjian.probe.write=true
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
已验证:`mvn -pl warehouse-sdk-hengjian -am test` 全部通过(340 个 + 4 个跳过)。
|
|
|
|
|
|
|
|
|
|
## 5. 探针用法
|
|
|
|
|
|
|
|
|
|
只读探针:
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
mvn -pl warehouse-sdk-hengjian -DfailIfNoTests=false \
|
|
|
|
|
-Dhengjian.probe=true \
|
|
|
|
|
-Dhengjian.probe.token=<组织token> \
|
|
|
|
|
-Dhengjian.probe.providerWarehouseId=EFCA \
|
|
|
|
|
-Dtest=HengjianReadOnlyProbeTest test
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
- 默认跳过;token 不入库、只走系统属性。
|
|
|
|
|
- 6 个用例:仓库目录 / 全量渠道 / 按仓渠道 / 承运商代码去重 / 订单详情 / 订单列表。
|
|
|
|
|
异常只打印不中断。
|
|
|
|
|
- 计费明细的只读探针在 `HengjianReadOnlyProbeTest` 之外,
|
|
|
|
|
用 `-Dhengjian.probe.begin=` / `-Dhengjian.probe.end=` 加 `-Dhengjian.probe.feeType=`
|
|
|
|
|
(STORAGE / LAST_MILE / OPERATION)指定查哪一类。
|
|
|
|
|
- 订单详情需 `-Dhengjian.probe.orderNo=`;订单列表需 `-Dhengjian.probe.begin=` 与 `-Dhengjian.probe.end=`
|
|
|
|
|
(`yyyy-MM-dd`,跨度 ≤30 天)。没给就跳过对应用例。
|
|
|
|
|
- 只读,不建单。
|
|
|
|
|
|
|
|
|
|
异动单查询探针(只读):
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
mvn -pl warehouse-sdk-hengjian -DfailIfNoTests=false \
|
|
|
|
|
-Dhengjian.probe=true -Dhengjian.probe.token=<组织token> \
|
|
|
|
|
-Dhengjian.probe.changeOrderNo=<仓方异动单号> \
|
|
|
|
|
-Dtest=HengjianTrackingChangeProbeTest test
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
- 验证查询路径是 `/v1/trackingChange/findOrder`(文档写的 `/v1/saleOrder/findOrder` 是 404)。
|
|
|
|
|
|
|
|
|
|
写探针(会留下真实数据):
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
mvn -pl warehouse-sdk-hengjian -DfailIfNoTests=false \
|
|
|
|
|
-Dhengjian.probe=true -Dhengjian.probe.write=true \
|
|
|
|
|
-Dhengjian.probe.token=<组织token> \
|
|
|
|
|
-Dhengjian.probe.sku=PROBE-SKU-001 \
|
|
|
|
|
-Dhengjian.probe.postcode=90001 \
|
|
|
|
|
-Dhengjian.probe.cancelOrderNo=<要取消的探针单号> \
|
|
|
|
|
-Dtest=HengjianWriteProbeTest test
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
- 两个开关同时打开才跑;SKU 默认带时间戳,重跑不撞唯一约束。
|
|
|
|
|
- 5 个用例:建商品、同 SKU 再存一次(验证保存语义是否幂等)、建销售发货单、
|
|
|
|
|
取消订单、取消预判。
|
|
|
|
|
- 建单需 `-Dhengjian.probe.postcode`(可选 `carrierCode` / `shopName` / `state` / `city`);
|
|
|
|
|
- 取消与预判需 `-Dhengjian.probe.cancelOrderNo`,取消只在给了单号时执行
|
|
|
|
|
(验证「只给单号自动补 orderId」这条路)。
|
|
|
|
|
- **恒健没有删除产品的接口**,跑完需要人工在 Efulfill 后台清理;
|
|
|
|
|
**取消探针会真实取消一张单**,只对测试环境的探针单用。
|
|
|
|
|
|
|
|
|
|
## 6. 待确认(交给业务方 / 恒健)
|
|
|
|
|
|
|
|
|
|
| # | 要确认 | 影响 |
|
|
|
|
|
|---|---|---|
|
|
|
|
|
| 1 | **有效 token 与测试仓代码** | 没有就无法跑探针,后续接口一律「未验证」 |
|
|
|
|
|
| 2 | 两个授权头是否必须同时带、是否同值 | 决定 `HengjianRequestFactory` 能否精简 |
|
|
|
|
|
| 3 | 新约定(`Authorization: Bearer`)与旧双头是否二选一 | 冲突 #2,决定后续接口按哪套实现 |
|
|
|
|
|
| 4 | **是否有回调(Webhook)文档** | 没有回调就只能轮询订单状态 |
|
|
|
|
|
| 5 | 限流值、单日配额 | 现在是保守默认 2 req/s |
|
|
|
|
|
| 6 | 能否在 PR 环境走写操作(建单 / 取消) | 决定全链路探针怎么设计 |
|
|
|
|
|
| 7 | 计费 / 测算接口的真实域名 | 文档写的是 `ehenglin.com` / `thebizark.com` |
|
|
|
|
|
| 8 | 商品「产品长」到底是 `length` 还是 `itemLength` | 《创建/编辑产品》写 `length`、《查询 sku》写 `itemLength`;接查询接口前必须确认,否则尺寸错位 |
|
|
|
|
|
| 9 | 是否有沙箱测试 SKU | 建单需要仓方系统里真实存在的 SKU(运去哪的 `lineCode` 就踩过这个坑) |
|
|
|
|
|
| 10 | 时区口径 | 文档多处写 UTC,但仓在美国;需真机确认返回的时间到底是不是 UTC |
|
|
|
|
|
| 11 | 建单的 `channelAccount` 是否必填 | 两页文档都标「否」,但写的是「必须在 Efulfill 店铺管理中维护」;未给时仓方按什么路由需真机确认 |
|
|
|
|
|
| 12 | `isPrime` 的真实类型 | 文档类型列写 STRING,请求示例却是数字 `0`;适配器按示例发 Integer,真机报类型错就问仓方 |
|
|
|
|
|
| 13 | 签收类型能否区分成人 / 间接签收 | 统一模型只有布尔,目前全部映射成「直接签收(1)」;业务若需要 2 / 3,要在 `OutboundCommand` 上加行级签收类型 |
|
|
|
|
|
| 14 | 列表分页是 1 基入参还是 0 基 | 文档参数示例 `page: 1`,响应 `number: 0`;适配器按「入参 1 基、响应 0 基」处理,真机若错位只改 `pageNumberOf` |
|
|
|
|
|
| 15 | 详情 / 列表的 `paidAt` 是否真是 UTC | 两页都没写时区,只有创建接口注明 utc;适配器按 UTC 解析,若仓方回的是本地时间,时间会整体平移 |
|
|
|
|
|
| 16 | 列表 `enclosure[].type` 到底回字符串还是数字 | 列表页标 INTEGER、详情页标 STRING 且示例是 `"Shippinglabel"`;适配器按文本读,两种都能接住 |
|
|
|
|
|
|
|
|
|
|
## 7. 下一步
|
|
|
|
|
|
|
|
|
|
1. 拿到 token 后跑 `HengjianReadOnlyProbeTest` 与 `HengjianWriteProbeTest`,把结论补进本文档
|
|
|
|
|
「文档与实际不一致」表;重点验商品保存的必填组合、保存语义、建单的必填组合与 `orderId` 回传、
|
|
|
|
|
详情 / 列表的分页与时间口径、取消的双键与预判。
|
|
|
|
|
2. 按 [onboarding-checklist.md](../onboarding-checklist.md) 阶段 2 逐接口接入,建议顺序:
|
|
|
|
|
**库存(按 SKU + 分页)→ 商品查询 → 入库 → 退货 v2 → 订单上传附件 / 物流异动单**。
|
|
|
|
|
3. 每个写接口接入前先确认第 6 节的 1 / 6 / 9 三项,否则写接口只能停在「有代码、未验证」。
|
|
|
|
|
|
|
|
|
|
出库子能力到此全部接完(下单 / 详情 / 列表 / 取消 / 预判 / 包裹)。剩下与出库相关的是
|
|
|
|
|
订单上传附件与物流异动单,都不影响主链路,按需排期。
|
|
|
|
|
|
|
|
|
|
## 真机探针记录(2026-11-17,只读)
|
|
|
|
|
|
|
|
|
|
`HengjianReadOnlyProbeTest` 用真实 token 跑了全部查询接口,结论如下。
|
|
|
|
|
|
|
|
|
|
### 可用
|
|
|
|
|
|
|
|
|
|
| 接口 | 实测 |
|
|
|
|
|
|---|---|
|
|
|
|
|
| `POST /v2/warehouse/getWarehouse` | 55 个仓 |
|
|
|
|
|
| `POST /v2/carrierGroup/getCarrierGroup` | 95 个物流产品 |
|
|
|
|
|
| `POST /v2/carrierGroup/getWarehouseCarrierGroupServices` | EFCA 91 个 |
|
|
|
|
|
| `POST /v2/product/queryPage` | **799 条**,分页正常 |
|
|
|
|
|
| `GET /v1/saleOrder/findByPage` | 正常,**回 `orderId`** |
|
|
|
|
|
| `POST /v1/saleOrder/findOne` | 正常 |
|
|
|
|
|
| `GET /v2/inventory/get_inventory_by_page` | 正常 |
|
|
|
|
|
| `POST /v1/inventory/getInventory` | 正常(按 SKU 14 条) |
|
|
|
|
|
| `POST /v1/inbound/getInboundPlanPage` / `getInboundPlanInfo` | 正常 |
|
|
|
|
|
| `POST /v1/transferPlan/findByPage` | 正常 |
|
|
|
|
|
| `POST /v1/saleReturn/thirdParty/getReturnPlanOrderPage` / `getReturnPlanOrderInfo` | 正常 |
|
|
|
|
|
| `POST /v1/saleReturn/getReturnPlanHandlePage` | 正常,页码 0 基 |
|
|
|
|
|
| `POST /v2/api/shipping/calculate` | 正常(需发运仓) |
|
|
|
|
|
| `POST /v2/api/shipping/addressClassification` | 正常。Google / Apple 总部 → **BUSINESS**;仓方库覆盖不到的地址 → `UNKNOWN` |
|
|
|
|
|
|
|
|
|
|
### 真机纠正的错误
|
|
|
|
|
|
|
|
|
|
| 项 | 文档 | 真机 |
|
|
|
|
|
|---|---|---|
|
|
|
|
|
| 试算发运仓字段 | 只列 `shipper*` | **`warehouseCode`**;`shipper*` 给了不全会报「发货人信息不完整」 |
|
|
|
|
|
| 试算必填 | `shipper*` 全必填 | 「发运仓库」或「发运邮编」**至少一个** |
|
|
|
|
|
| 商品查询 `length` | 响应表没这一项 | **有**,且有值 |
|
|
|
|
|
| 商品查询 `productStatus` | 没有 | **有**(样例值 1),含义未确认,只存原值 |
|
|
|
|
|
| 商品 `nameEn` | STRING | 空值返回**字符串 `"null"`**,不是 JSON null |
|
|
|
|
|
| 商品 `cost` | DOUBLE | 可为 **0.0**,是合法成本不是「没给」 |
|
|
|
|
|
| 商品 `isInsuranceRate` | 保价费率 | 是**费率**不是金额,不能塞进 `insuranceFee` |
|
|
|
|
|
|
|
|
|
|
### 计费接口:重测结论(2026-11-17 晚间)
|
|
|
|
|
|
|
|
|
|
之前记录的 ES 故障<b>无法复现</b>。同一参数连打 20 次全部成功(0 失败),
|
|
|
|
|
换 `rows` = 5/10/20/50/100 也都成功。所以当时的 ES 异常是<b>仓方一次性抖动</b>,
|
|
|
|
|
不是稳定故障。
|
|
|
|
|
|
|
|
|
|
**但这轮重测发现了一个真问题**:
|
|
|
|
|
|
|
|
|
|
| 项 | 现象 |
|
|
|
|
|
|---|---|
|
|
|
|
|
| 未结算行的 `settlementAt` | 返回 **`1997-01-01 00:00:00`**(哨兵),**不是 null** |
|
|
|
|
|
| 未结算行的 `billNo` / `settlementName` | 空串 |
|
|
|
|
|
| 未结算行的 `currency` | 空串 |
|
|
|
|
|
| 未结算行的 `errorMessage` | 有内容,如「UAT 组织EFCA 仓库仓储费报价未匹配!」 |
|
|
|
|
|
|
|
|
|
|
直接落库会让对账以为「1997 年结过一笔」。适配器已加 `settledAt()`:
|
|
|
|
|
**哨兵日期转 null**,三个计费接口统一处理。
|
|
|
|
|
|
|
|
|
|
另外注意:仓储费的 `cost` 可以为 0 且 `currency` 为空——适配器用默认币种兜底
|
|
|
|
|
(`DEFAULT_CURRENCY`),不会丢行。
|
|
|
|
|
|
|
|
|
|
### 仓方自身故障(非我方问题)
|
|
|
|
|
|
|
|
|
|
三个计费接口在测试环境<b>间歇性</b>回 `code=999999`:
|
|
|
|
|
|
|
|
|
|
```
|
|
|
|
|
获取账单执行明细失败:org.springframework.data.elasticsearch.ElasticsearchException:
|
|
|
|
|
Error for search request with scroll ... indices=[charging_storage_settlements]
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
从异常里的 DSL 能看到我方报文正确(`orgWarehouseCode:["EFCA"]`、
|
|
|
|
|
`chargeAt` 区间、`disabledAt:0` 都对)。**是恒健侧 ES 索引故障**,
|
|
|
|
|
同一参数重试有时成功(返回 0 条)。
|
|
|
|
|
|
|
|
|
|
三个接口(仓储费 / 尾程费 / 作业费)都会中招,不是某一个的问题。
|
|
|
|
|
|
|
|
|
|
### 未覆盖
|
|
|
|
|
|
|
|
|
|
| 接口 | 原因 |
|
|
|
|
|
|---|---|
|
|
|
|
|
| `POST /v2/destroyPlanOrder/find` | 路径仍 404(26 个变体全试过) |
|
|
|
|
|
| `POST /v1/saleReturn/getReturnPlanHandlePage` 的分页游标 | 恒健返回 `number` 是 0 基,适配器已按 +2 处理 |
|