package common.ecommerce.hengjian; /** * 恒健(HengJian / Efulfill)协议常量。 * *

端点与路径是协议的一部分,写在代码里,不做成配置表。 * 运行时不使用 {@link #TEST_BASE_URL}:端点由调用方每次经 * {@code WarehouseConnection} 传入。

* *

依据恒健语雀《OpenAPI接口文档》(book tvzvkk,2026-11 核对)。 * 该文档单篇接口页里没有写鉴权细节,鉴权只在《基础API调用》一页, * 且写了两个都叫「授权Token」的请求头。

*/ public final class HengjianConstants { /** 适配器标识。 */ public static final String ADAPTER_ID = "hengjian"; /** * 测试 / 联调环境基址。 * *

文档写的是 {@code https://pr-open-api.ehengjian.com},末尾不带斜杠, * 与 {@code WarehouseConnection} 的归一化一致,路径直接以 {@code /} 开头拼接。

*/ public static final String TEST_BASE_URL = "https://pr-open-api.ehengjian.com"; /** 生产环境基址;运行时不使用,调用方需要时自己传。 */ public static final String PRODUCTION_BASE_URL = "https://open-api.ehengjian.com"; /** * 授权请求头 1:{@code Authorization}。 * *

文档把 {@code Authorization} 与 {@code x-api-key} 两个头都标成「授权Token」, * 且都标「必须」,所以两个都带、取值相同(复用 {@code ChannelSecret.appSecret()})。

* *

真机尚不能确认是否可以只带一个:用一个无效 token 试过, * 只带一个和两个都带都返回 500「未知的账户!」,区分不出是哪个头在起作用。 * 拿到有效 token 后应补一次对照实验,再决定能否精简。

*/ public static final String AUTHORIZATION_HEADER = "Authorization"; /** 授权请求头 2:{@code x-api-key};取值同 {@link #AUTHORIZATION_HEADER}。 */ public static final String API_KEY_HEADER = "x-api-key"; /** 获取当前组织仓库(无参数)。 */ public static final String PATH_WAREHOUSE_LIST = "/v2/warehouse/getWarehouse"; /** 获取物流渠道(无参数):全部承运商服务的扁平清单。 */ public static final String PATH_CARRIER_GROUP = "/v2/carrierGroup/getCarrierGroup"; /** 获取仓库支持的物流渠道:按仓代码过滤。 */ public static final String PATH_WAREHOUSE_CARRIER_GROUP = "/v2/carrierGroup/getWarehouseCarrierGroupServices"; /** * 创建 / 编辑产品。 * *

接口是保存语义(同一 SKU 再调即更新),响应只有 {@code code/message},没有 data。

*/ public static final String PATH_PRODUCT_SAVE = "/v1/product/save"; /** * 创建销售发货单。 * *

响应回 {@code data.orderId}(仓内部数字 id);取消时 {@code orderId} 与 * {@code orderNo} 都要,所以调用方必须落库这个 id。

*/ public static final String PATH_ORDER_CREATE = "/v1/saleOrder/create"; /** * 订单详情。 * *

只按{@code orderNo}(来源单号)查,响应不回 {@code orderId}。

*/ public static final String PATH_ORDER_FIND_ONE = "/v1/saleOrder/findOne"; /** * 订单列表(分页)。 * *

{@code GET},时间、订单号、订单 id 三者必填其一;时间跨度不超过 30 天。 * 是唯一会回 {@code orderId} 的查询接口。

*/ public static final String PATH_ORDER_FIND_BY_PAGE = "/v1/saleOrder/findByPage"; /** * 订单取消。 * *

{@code orderId} 与 {@code orderNo} 都必填。{@code orderId} 只有两条来路: * 创建接口的响应、列表接口的行。详情接口不回它,所以只拿到单号时, * 取消前要先用列表接口补一次 id。

*/ public static final String PATH_ORDER_CANCEL = "/v1/saleOrder/cancel"; /** * 创建物流异动单。 * *

{@code trackingNo}、{@code orderNo}、{@code remark}、{@code handleType} 真机均为必填; * 且仓方会校验「来源单号与 trackingNo 属于同一张单」。

*/ public static final String PATH_TRACKING_CHANGE_CREATE = "/v1/trackingChange/create"; /** * 物流异动单查询。 * *

路径与文档不一致:恒健文档页写的是 {@code /v1/saleOrder/findOrder} * (疑似从销售订单页复制),真机该路径返回 * {@code 404 No handler found};实际路径是 {@code /v1/trackingChange/findOrder} * (2026-11-13 真机确认)。

*/ public static final String PATH_TRACKING_CHANGE_FIND = "/v1/trackingChange/findOrder"; /** * 列表接口的排序字段。 * *

文档:{@code sidx} 可写死 {@code id},{@code sort} 取 {@code asc} / {@code desc}; * 两个都是必填。

*/ public static final String ORDER_LIST_SIDX = "id"; /** 列表接口的排序方向。 */ public static final String ORDER_LIST_SORT = "desc"; /** * 列表接口的时间跨度上限(天)。 * *

文档:{@code beginDateTime} 与 {@code endDateTime} 的跨度不要超过 30 天。 * 超过时适配器在本地拒绝,不把必然被拒的请求发出去。

*/ public static final int ORDER_LIST_MAX_DAYS = 30; /** 列表接口单页最大行数(文档:默认最高 100)。 */ public static final int ORDER_LIST_MAX_ROWS = 100; /** 业务成功码;文档各接口一致写 {@code 200}。 */ public static final int SUCCESS_CODE = 200; /** * 未授权 / 未知账户的业务码。 * *

真机观察(2026-11-12,测试环境):不带任何授权头请求 * {@code /v2/warehouse/getWarehouse},HTTP 仍是 200,body 是 * {@code {"statusCode":500,"status":1,"code":999999,"message":"查询失败Unauthorized"}}。 * 带上任意一个头(值无效)时则返回 Spring 的 500 错误页 * {@code {"status":500,...,"message":"未知的账户!"}}。

* *

因此这个码必须按认证失败处理,不能当普通业务失败——否则宿主只会看到 * 一条「业务码非 200」,不会去刷新凭据。

*/ public static final int UNAUTHORIZED_CODE = 999999; /** * 限流:每秒许可数。 * *

恒健文档未公开限流值,先按三家仓的保守默认 2 req/s/仓;联调确认后只改这一处。

*/ public static final int PERMITS_PER_SECOND = 2; private HengjianConstants() { } }