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.

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

三个接口都是无副作用查询、都不依赖单号,所以用来先验证鉴权与信封。

返回形状差异

接口 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(不是「不支持跨国」)

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:0 ShippingLabel / 1 PackingList / 2 BOL / 3 Other / 4 CartonLabel / 5 PalletLabel / 6 itemlabel。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(创建/编辑)、POST /v1/product/getBySku、GET /v1/productChannel/findByPage、 POST /v2/product/queryPage(分页 SKU,含产品打托信息)、POST /v1/product/createProductAlias。 尺寸 cm / 重量 g,与统一模型一致(不需要换算)。

入库(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     字段搬运
    │   ├── dto/
    │   │   ├── HengjianWarehouseDtos.java
    │   │   └── HengjianCarrierGroupDtos.java    两个渠道接口共用行模型
    │   ├── 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/HengjianAdapterTest.java     4 个:注册 / 能力拒绝 / 枚举
        ├── http/HengjianEnvelopeTest.java       11 个:三种信封形态 + 错误路径
        └── probe/HengjianReadOnlyProbeTest.java 默认跳过,凭据走系统属性

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

5. 探针用法

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

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 接入商品前必须确认,否则尺寸错位
9 是否有沙箱测试 SKU 建单需要仓方系统里真实存在的 SKU(运去哪的 lineCode 就踩过这个坑)
10 时区口径 文档多处写 UTC,但仓在美国;需真机确认返回的时间到底是不是 UTC

7. 下一步

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