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.

21 KiB

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

前三个接口是无副作用查询、不依赖单号,用来先验证鉴权与信封;商品保存是写接口, 但只写主数据、不产生履约单据,所以放在第二阶段。出库下单是真正的履约写操作, 门面强制经幂等守卫(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 是「产品测量图片」(复核长宽高用),不是商品主图;语义不同
packageStyle 恒健的 isSpecialOuterPackaging 是「是否特殊外包装」,不是同一套码
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, 一个请求都不发。

几个关键口径:

项 处理
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() 落库;拿不到就报错,不当创建成功。

未接入:查询 / 取消 / 包裹。调用这些方法会显式抛 WarehouseException,不返回 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、POST /v1/saleOrder/findOrder、POST /v1/trackingChange/cancel ⬜

接查询 / 取消时要注意:

  • orderStatusEnum 取值:pending / unshipped / approved / assigned / picked / shipped / canceled / refunded ——与运去哪同名但不同源,必须各建一套平台枚举,精确匹配、未知归 UNKNOWN。
  • 取消接口需要创建时由仓方返回的 orderId(findByPage 也回 orderId), 只给单号不行。
  • attachInfoItems.type:0 ShippingLabel / 1 PackingList / 2 BOL / 3 Other / 4 CartonLabel / 5 PalletLabel / 6 itemlabel。url 与 file(base64) 二选一。

库存(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/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 时间 / 行总额 / 面单附件)
    │   ├── dto/
    │   │   ├── HengjianWarehouseDtos.java
    │   │   ├── HengjianCarrierGroupDtos.java    两个渠道接口共用行模型
    │   │   ├── HengjianProductSaveDtos.java     /v1/product/save
    │   │   └── HengjianCreateOrderDtos.java     /v1/saleOrder/create
    │   ├── enums/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/HengjianAdapterTest.java     5 个:注册 / 能力拒绝 / 枚举
        ├── http/HengjianEnvelopeTest.java       11 个:三种信封形态 + 错误路径
        ├── probe/HengjianReadOnlyProbeTest.java 默认跳过,凭据走系统属性
        └── probe/HengjianWriteProbeTest.java    默认跳过,另需 -Dhengjian.probe.write=true

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

5. 探针用法

只读探针:

mvn -pl warehouse-sdk-hengjian -DfailIfNoTests=false \
    -Dhengjian.probe=true \
    -Dhengjian.probe.token=<组织token> \
    -Dhengjian.probe.providerWarehouseId=EFCA \
    -Dtest=HengjianReadOnlyProbeTest test
  • 默认跳过;token 不入库、只走系统属性。
  • 4 个用例:仓库目录 / 全量渠道 / 按仓渠道 / 承运商代码去重。异常只打印不中断。
  • 只读,不建单。

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

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 \
    -Dtest=HengjianWriteProbeTest test
  • 两个开关同时打开才跑;SKU 默认带时间戳,重跑不撞唯一约束。
  • 3 个用例:建商品、同 SKU 再存一次(验证保存语义是否幂等)、建销售发货单 (需额外给 -Dhengjian.probe.postcode;可选 carrierCode / shopName / state / city)。
  • 恒健没有删除产品的接口,跑完需要人工在 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 上加行级签收类型

7. 下一步

  1. 拿到 token 后跑 HengjianReadOnlyProbeTest 与 HengjianWriteProbeTest,把结论补进本文档 「文档与实际不一致」表;重点验商品保存的必填组合、保存语义、建单的必填组合与 orderId 回传。
  2. 按 onboarding-checklist.md 阶段 2 逐接口接入,建议顺序: 出库详情 / 列表 / 取消 → 库存(按 SKU + 分页)→ 商品查询 → 入库 → 退货 v2。
  3. 每个写接口接入前先确认第 6 节的 1 / 6 / 9 三项,否则写接口只能停在「有代码、未验证」。
  4. 出库状态枚举按 orderStatusEnum 全量建(8 个值),未知归 UNKNOWN,原值进 rawStatus; 注意 unshipped / shipped 必须精确匹配,不能用 contains("SHIP")。