|
|
1 week ago | |
|---|---|---|
| .. | ||
| README.md | 1 week 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 错误页,说明鉴权在网关层,文档没覆盖 |
运去哪的教训:只按文档写代码,有 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: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(创建/编辑)、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. 下一步
- 拿到 token 后跑
HengjianReadOnlyProbeTest,把结论补进本文档「文档与实际不一致」表。 - 按 onboarding-checklist.md 阶段 2 逐接口接入,建议顺序: 出库(创建 / 详情 / 列表 / 取消)→ 库存(按 SKU + 分页)→ 商品 → 入库 → 退货 v2。
- 每个写接口接入前先确认第 6 节的 1 / 6 / 9 三项,否则写接口只能停在「有代码、未验证」。
- 出库状态枚举按
orderStatusEnum全量建(8 个值),未知归UNKNOWN,原值进rawStatus; 注意unshipped/shipped必须精确匹配,不能用contains("SHIP")。