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.

295 lines
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`:`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` | ✅ 已接入 |
| 查询 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. 探针用法
只读探针:
```bash
mvn -pl warehouse-sdk-hengjian -DfailIfNoTests=false \
-Dhengjian.probe=true \
-Dhengjian.probe.token=<组织token> \
-Dhengjian.probe.providerWarehouseId=EFCA \
-Dtest=HengjianReadOnlyProbeTest test
```
- 默认跳过;token 不入库、只走系统属性。
- 4 个用例:仓库目录 / 全量渠道 / 按仓渠道 / 承运商代码去重。异常只打印不中断。
- 只读,不建单。
写探针(会留下真实商品数据):
```bash
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. 下一步
1. 拿到 token 后跑 `HengjianReadOnlyProbeTest` 与 `HengjianWriteProbeTest`,把结论补进本文档
「文档与实际不一致」表;重点验商品保存的必填组合与保存语义。
2. 按 [onboarding-checklist.md](../onboarding-checklist.md) 阶段 2 逐接口接入,建议顺序:
**出库(创建 / 详情 / 列表 / 取消)→ 库存(按 SKU + 分页)→ 商品查询 → 入库 → 退货 v2**。
3. 每个写接口接入前先确认第 6 节的 1 / 6 / 9 三项,否则写接口只能停在「有代码、未验证」。
4. 出库状态枚举按 `orderStatusEnum` 全量建(8 个值),未知归 `UNKNOWN`,原值进 `rawStatus`;
注意 `unshipped` / `shipped` 必须精确匹配,不能用 `contains("SHIP")`。