17 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 错误页,说明鉴权在网关层,文档没覆盖 |
运去哪的教训:只按文档写代码,有 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 | 回调 | — | — | ❌ 文档无回调页 |
前三个接口是无副作用查询、不依赖单号,用来先验证鉴权与信封;商品保存是写接口, 但只写主数据、不产生履约单据,所以放在第二阶段。
返回形状差异
| 接口 | 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),不做换算。
3. 未接入(文档已有,按需排期)
按能力位分组,路径取自文档(标注 ⚠ 的表示文档没写路径或路径可疑,需真机核对):
出库(OUTBOUND)
| 接口 | 路径 |
|---|---|
| 创建销售发货单(带附件) | POST /v1/saleOrder/create → 返回 data.orderId |
| Create Sale Order With Label(英文版,同路径) | POST /v1/saleOrder/create |
| 订单详情 | 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 |
要点:
- 创建接口的必填字段:
orderNo、shipToCountry、shipToState、shipToCity、shipToPostal、shipToAddress1、shipToContact、shipToTelephone、createdAt(英文版页标注Y;中文版页标否, 两页矛盾)、productItems(每行的sku/quantity/isInsure/isSignature)、attachInfoItems。 attachInfoItems.type:0ShippingLabel /1PackingList /2BOL /3Other /4CartonLabel /5PalletLabel /6itemlabel。url与file(base64) 二选一。orderStatusEnum取值:pending / unshipped / approved / assigned / picked / shipped / canceled / refunded——与运去哪同名但不同源,必须各建一套平台枚举。isSignature:0否 /1直接签收 /2成人签收 /3间接签收(仅 FedEx)。- 取消接口需要创建时由仓方返回的
orderId(findByPage也回orderId), 只给单号不行——所以OutboundReceipt.providerOrderId必须落库。
库存(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 商品报文 + 恒健必填项本地校验
│ ├── dto/
│ │ ├── HengjianWarehouseDtos.java
│ │ ├── HengjianCarrierGroupDtos.java 两个渠道接口共用行模型
│ │ └── HengjianProductSaveDtos.java /v1/product/save
│ ├── 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/HengjianAdapterTest.java 4 个:注册 / 能力拒绝 / 枚举
├── http/HengjianEnvelopeTest.java 11 个:三种信封形态 + 错误路径
├── probe/HengjianReadOnlyProbeTest.java 默认跳过,凭据走系统属性
└── probe/HengjianWriteProbeTest.java 默认跳过,另需 -Dhengjian.probe.write=true
已验证:mvn -pl warehouse-sdk-hengjian -am test 全部通过(48 个 + 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 \
-Dtest=HengjianWriteProbeTest test
- 两个开关同时打开才跑;SKU 默认带时间戳,重跑不撞唯一约束。
- 2 个用例:建商品、同 SKU 再存一次(验证保存语义是否幂等)。
- 恒健没有删除产品的接口,跑完需要人工在 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 |
7. 下一步
- 拿到 token 后跑
HengjianReadOnlyProbeTest与HengjianWriteProbeTest,把结论补进本文档 「文档与实际不一致」表;重点验商品保存的必填组合与保存语义。 - 按 onboarding-checklist.md 阶段 2 逐接口接入,建议顺序: 出库(创建 / 详情 / 列表 / 取消)→ 库存(按 SKU + 分页)→ 商品查询 → 入库 → 退货 v2。
- 每个写接口接入前先确认第 6 节的 1 / 6 / 9 三项,否则写接口只能停在「有代码、未验证」。
- 出库状态枚举按
orderStatusEnum全量建(8 个值),未知归UNKNOWN,原值进rawStatus; 注意unshipped/shipped必须精确匹配,不能用contains("SHIP")。