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 POST},分页)。 * *三个计费接口的请求结构一致:{@code orgWarehouseCodes} / {@code relOrderNos} / * {@code sourceNos} / {@code btChargeAt} 都可选,{@code page} / {@code size} 必填。
*/ public static final String PATH_FEE_STORAGE = "/v1/chargingSettlement/getChargingStorageSettlement"; /** 尾程配送费明细({@code POST},分页)。 */ public static final String PATH_FEE_TAIL_DELIVERY = "/v1/chargingSettlement/getChargingTailDeliverySettlement"; /** 作业费明细({@code POST},分页)。 */ public static final String PATH_FEE_OPERATION = "/v1/chargingSettlement/getChargingOperationSettlement"; /** 计费明细默认每页条数;调用方未指定时使用。 */ public static final int FEE_PAGE_SIZE_DEFAULT = 100; /** * 计费明细单页上限。 * *文档没写这个值。上一版取 200 并静默截断,调用方传 9999 实际只发 * 200 却毫不知情,按自己的 pageSize 判末页会误判。现在改成:超过即显式报错, * 由调用方自己决定用多大;真机确认仓方上限后再收紧。
*/ public static final int FEE_PAGE_SIZE_MAX = 200; /** * 运费测算。 * *真机确认存在;包裹四项 + 两个单位 + 收货方五项必填 * ({@code shipper*} 系列可省)。
*/ public static final String PATH_FEE_ESTIMATE = "/v2/api/shipping/calculate"; /** * 地址属性识别。 * *文档写的域名是 {@code open-api.thebizark.com}(别家),是本仓的笔误。 * 真机确认本仓域名下正常返回 {@code data: "BUSINESS"} 等值。
*/ public static final String PATH_ADDRESS_CLASSIFICATION = "/v2/api/shipping/addressClassification"; /** * 按 SKU 查库存({@code POST},不分页)。 * *真机确认:{@code skus} 必填且不能是空数组。
*/ public static final String PATH_INVENTORY_BY_SKU = "/v1/inventory/getInventory"; /** * 批量查库存({@code GET},分页)。 * *真机确认 {@code warehouseCodes} 是必填的 List 参数; * {@code page / rows / sidx / sort} 也必填,{@code rows} 默认最高 500。
*/ public static final String PATH_INVENTORY_PAGE = "/v2/inventory/get_inventory_by_page"; /** * 库存变动流水({@code POST},分页)。 * *真机确认 {@code skus} / {@code beginDateTime} / {@code endDateTime} 都必填; * 日期跨度最多 30 个自然日。
*/ public static final String PATH_INVENTORY_MOVEMENTS = "/v1/inventory/task/query"; /** 批量库存分页默认页大小;文档:默认最高 500。 */ public static final int INVENTORY_PAGE_ROWS_DEFAULT = 100; /** 批量库存分页单页上限;文档明写 500。 */ public static final int INVENTORY_PAGE_ROWS_MAX = 500; /** 库存流水分页上限;文档明写 1~100。 */ public static final int INVENTORY_MOVEMENT_ROWS_MAX = 100; /** * 库存流水的日期跨度上限(自然日)。 * *文档与真机一致:{@code 2026-10-01}~{@code 2026-10-30} 合法, * {@code ~2026-10-31} 不合法(真机回 {@code 查询日期最多包含30个自然日})。
*/ public static final int INVENTORY_MOVEMENT_MAX_DAYS = 30; /** * 入库计划创建({@code POST})。 * *真机确认必填:{@code orderNo} / {@code warehouseCode} / {@code inventoryType} / * {@code productItems}。响应不回仓单号。
*/ public static final String PATH_INBOUND_CREATE = "/v1/inbound/createInboundPlan"; /** * {@code btChargeAt} 的日期区间分隔符。 * *文档示例是 {@code "2025-01-01 ~ 2025-02-01"}(前后各一个空格)。
*/ public static final String FEE_DATE_RANGE_SEPARATOR = " ~ "; /** * 列表接口的默认排序字段。 * *文档:{@code sidx} 必填,可写死 {@code id}。调用方经 * {@code OutboundQuery.sortField()} 指定时以调用方为准——文档说「可写死」, * 不是「只能写 id」。
*/ public static final String ORDER_LIST_DEFAULT_SIDX = "id"; /** * 列表接口的默认排序方向。 * *文档把 {@code sort} 列为必填,取值为 {@code asc} / {@code desc}。 * 这是两个可选值,不是常量:调用方经 * {@code OutboundQuery.sortDirection()} 选,未指定时才用这个默认。
*/ public static final String ORDER_LIST_DEFAULT_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() { } }