|
|
3 days ago | |
|---|---|---|
| .. | ||
| README.md | 3 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 | 入库箱标生成 | 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/fileNamingTypeLabelPrintTask.taskNo改为可空(恒健不回任务号),Javadoc 说明了 null 的含义
销毁(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/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. 探针用法
只读探针:
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. 下一步
- 拿到 token 后跑
HengjianReadOnlyProbeTest与HengjianWriteProbeTest,把结论补进本文档 「文档与实际不一致」表;重点验商品保存的必填组合、保存语义、建单的必填组合与orderId回传、 详情 / 列表的分页与时间口径、取消的双键与预判。 - 按 onboarding-checklist.md 阶段 2 逐接口接入,建议顺序: 库存(按 SKU + 分页)→ 商品查询 → 入库 → 退货 v2 → 订单上传附件 / 物流异动单。
- 每个写接口接入前先确认第 6 节的 1 / 6 / 9 三项,否则写接口只能停在「有代码、未验证」。
出库子能力到此全部接完(下单 / 详情 / 列表 / 取消 / 预判 / 包裹)。剩下与出库相关的是 订单上传附件与物流异动单,都不影响主链路,按需排期。