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.
lml b634ff2e93 feat(hengjian): 对接销毁计划创建 / 查询(路径待真机确认) 4 days ago
..
README.md feat(hengjian): 对接销毁计划创建 / 查询(路径待真机确认) 4 days ago

README.md

恒健(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 回调 — — ❌ 文档无回调页

前三个接口是无副作用查询、不依赖单号,用来先验证鉴权与信封;商品保存是写接口, 但只写主数据、不产生履约单据,所以放在第二阶段。出库下单是真正的履约写操作, 门面强制经幂等守卫(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。其它仓不读这些字段,行为不变。

未接入:入库查询 / 分页 / 取消 / 加附件 / 发运 / 箱标 / 预约单,调用显式抛异常。

销毁(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 不是数组);给多个时拒绝, 静默只取一个会让调用方以为筛全了。
  • 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)—— 已接入

恒健把三类费用拆成三个独立接口,行字段完全不同:

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),是已发生账目, 不是预估 → estimated(false)。
  • 金额:cost 是该行总费用,不是单价。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/HengjianAdapterTest.java     5 个:注册 / 能力拒绝 / 枚举
        ├── http/HengjianEnvelopeTest.java       12 个:三种信封形态 + 通用失败码 + 错误路径
        ├── probe/HengjianReadOnlyProbeTest.java 默认跳过,凭据走系统属性
        └── probe/HengjianWriteProbeTest.java    默认跳过,另需 -Dhengjian.probe.write=true

已验证:mvn -pl warehouse-sdk-hengjian -am test 全部通过(329 个 + 4 个跳过)。

5. 探针用法

只读探针:

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 天)。没给就跳过对应用例。
  • 只读,不建单。

异动单查询探针(只读):

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)。

写探针(会留下真实数据):

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 阶段 2 逐接口接入,建议顺序: 库存(按 SKU + 分页)→ 商品查询 → 入库 → 退货 v2 → 订单上传附件 / 物流异动单。
  3. 每个写接口接入前先确认第 6 节的 1 / 6 / 9 三项,否则写接口只能停在「有代码、未验证」。

出库子能力到此全部接完(下单 / 详情 / 列表 / 取消 / 预判 / 包裹)。剩下与出库相关的是 订单上传附件与物流异动单,都不影响主链路,按需排期。