|
|
|
|
package common.ecommerce.hengjian;
|
|
|
|
|
|
|
|
|
|
/**
|
|
|
|
|
* 恒健(HengJian / Efulfill)协议常量。
|
|
|
|
|
*
|
|
|
|
|
* <p>端点与路径是<b>协议的一部分</b>,写在代码里,不做成配置表。
|
|
|
|
|
* 运行时不使用 {@link #TEST_BASE_URL}:端点由调用方每次经
|
|
|
|
|
* {@code WarehouseConnection} 传入。</p>
|
|
|
|
|
*
|
|
|
|
|
* <p>依据恒健语雀《OpenAPI接口文档》(book tvzvkk,2026-11 核对)。
|
|
|
|
|
* 该文档单篇接口页里<b>没有</b>写鉴权细节,鉴权只在《基础API调用》一页,
|
|
|
|
|
* 且写了两个都叫「授权Token」的请求头。</p>
|
|
|
|
|
*/
|
|
|
|
|
public final class HengjianConstants {
|
|
|
|
|
|
|
|
|
|
/** 适配器标识。 */
|
|
|
|
|
public static final String ADAPTER_ID = "hengjian";
|
|
|
|
|
|
|
|
|
|
/**
|
|
|
|
|
* 测试 / 联调环境基址。
|
|
|
|
|
*
|
|
|
|
|
* <p>文档写的是 {@code https://pr-open-api.ehengjian.com},末尾不带斜杠,
|
|
|
|
|
* 与 {@code WarehouseConnection} 的归一化一致,路径直接以 {@code /} 开头拼接。</p>
|
|
|
|
|
*/
|
|
|
|
|
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}。
|
|
|
|
|
*
|
|
|
|
|
* <p>文档把 {@code Authorization} 与 {@code x-api-key} 两个头都标成「授权Token」,
|
|
|
|
|
* 且都标「必须」,所以两个都带、取值相同(复用 {@code ChannelSecret.appSecret()})。</p>
|
|
|
|
|
*
|
|
|
|
|
* <p><b>真机尚不能确认是否可以只带一个</b>:用一个无效 token 试过,
|
|
|
|
|
* 只带一个和两个都带都返回 500「未知的账户!」,区分不出是哪个头在起作用。
|
|
|
|
|
* 拿到有效 token 后应补一次对照实验,再决定能否精简。</p>
|
|
|
|
|
*/
|
|
|
|
|
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";
|
|
|
|
|
|
|
|
|
|
/**
|
|
|
|
|
* 创建 / 编辑产品。
|
|
|
|
|
*
|
|
|
|
|
* <p>接口是保存语义(同一 SKU 再调即更新),响应只有 {@code code/message},没有 data。</p>
|
|
|
|
|
*/
|
|
|
|
|
public static final String PATH_PRODUCT_SAVE = "/v1/product/save";
|
|
|
|
|
|
|
|
|
|
/**
|
|
|
|
|
* 创建销售发货单。
|
|
|
|
|
*
|
|
|
|
|
* <p>响应回 {@code data.orderId}(仓内部数字 id);取消时 {@code orderId} 与
|
|
|
|
|
* {@code orderNo} 都要,所以调用方必须落库这个 id。</p>
|
|
|
|
|
*/
|
|
|
|
|
public static final String PATH_ORDER_CREATE = "/v1/saleOrder/create";
|
|
|
|
|
|
|
|
|
|
/**
|
|
|
|
|
* 订单详情。
|
|
|
|
|
*
|
|
|
|
|
* <p>只按{@code orderNo}(来源单号)查,响应<b>不回 {@code orderId}</b>。</p>
|
|
|
|
|
*/
|
|
|
|
|
public static final String PATH_ORDER_FIND_ONE = "/v1/saleOrder/findOne";
|
|
|
|
|
|
|
|
|
|
/**
|
|
|
|
|
* 订单列表(分页)。
|
|
|
|
|
*
|
|
|
|
|
* <p>{@code GET},<b>时间、订单号、订单 id 三者必填其一</b>;时间跨度不超过 30 天。
|
|
|
|
|
* 是唯一会回 {@code orderId} 的查询接口。</p>
|
|
|
|
|
*/
|
|
|
|
|
public static final String PATH_ORDER_FIND_BY_PAGE = "/v1/saleOrder/findByPage";
|
|
|
|
|
|
|
|
|
|
/**
|
|
|
|
|
* 订单取消。
|
|
|
|
|
*
|
|
|
|
|
* <p><b>{@code orderId} 与 {@code orderNo} 都必填</b>。{@code orderId} 只有两条来路:
|
|
|
|
|
* 创建接口的响应、列表接口的行。详情接口不回它,所以只拿到单号时,
|
|
|
|
|
* 取消前要先用列表接口补一次 id。</p>
|
|
|
|
|
*/
|
|
|
|
|
public static final String PATH_ORDER_CANCEL = "/v1/saleOrder/cancel";
|
|
|
|
|
|
|
|
|
|
/**
|
|
|
|
|
* 创建物流异动单。
|
|
|
|
|
*
|
|
|
|
|
* <p>{@code trackingNo}、{@code orderNo}、{@code remark}、{@code handleType} 真机均为必填;
|
|
|
|
|
* 且仓方会校验「来源单号与 trackingNo 属于同一张单」。</p>
|
|
|
|
|
*/
|
|
|
|
|
public static final String PATH_TRACKING_CHANGE_CREATE = "/v1/trackingChange/create";
|
|
|
|
|
|
|
|
|
|
/**
|
|
|
|
|
* 物流异动单查询。
|
|
|
|
|
*
|
|
|
|
|
* <p><b>路径与文档不一致</b>:恒健文档页写的是 {@code /v1/saleOrder/findOrder}
|
|
|
|
|
* (疑似从销售订单页复制),真机该路径返回
|
|
|
|
|
* {@code 404 No handler found};实际路径是 {@code /v1/trackingChange/findOrder}
|
|
|
|
|
* (2026-11-13 真机确认)。</p>
|
|
|
|
|
*/
|
|
|
|
|
public static final String PATH_TRACKING_CHANGE_FIND = "/v1/trackingChange/findOrder";
|
|
|
|
|
|
|
|
|
|
/**
|
|
|
|
|
* 仓储费明细({@code POST},分页)。
|
|
|
|
|
*
|
|
|
|
|
* <p>三个计费接口的请求结构一致:{@code orgWarehouseCodes} / {@code relOrderNos} /
|
|
|
|
|
* {@code sourceNos} / {@code btChargeAt} 都可选,{@code page} / {@code size} 必填。</p>
|
|
|
|
|
*/
|
|
|
|
|
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;
|
|
|
|
|
|
|
|
|
|
/**
|
|
|
|
|
* 计费明细单页上限。
|
|
|
|
|
*
|
|
|
|
|
* <p><b>文档没写</b>这个值。上一版取 200 并<b>静默截断</b>,调用方传 9999 实际只发
|
|
|
|
|
* 200 却毫不知情,按自己的 pageSize 判末页会误判。现在改成:超过即<b>显式报错</b>,
|
|
|
|
|
* 由调用方自己决定用多大;真机确认仓方上限后再收紧。</p>
|
|
|
|
|
*/
|
|
|
|
|
public static final int FEE_PAGE_SIZE_MAX = 200;
|
|
|
|
|
|
|
|
|
|
/**
|
|
|
|
|
* 运费测算。
|
|
|
|
|
*
|
|
|
|
|
* <p>真机确认存在;包裹四项 + 两个单位 + 收货方五项必填
|
|
|
|
|
* ({@code shipper*} 系列可省)。</p>
|
|
|
|
|
*/
|
|
|
|
|
public static final String PATH_FEE_ESTIMATE = "/v2/api/shipping/calculate";
|
|
|
|
|
|
|
|
|
|
/**
|
|
|
|
|
* 地址属性识别。
|
|
|
|
|
*
|
|
|
|
|
* <p><b>文档写的域名是 {@code open-api.thebizark.com}(别家),是本仓的笔误。</b>
|
|
|
|
|
* 真机确认本仓域名下正常返回 {@code data: "BUSINESS"} 等值。</p>
|
|
|
|
|
*/
|
|
|
|
|
public static final String PATH_ADDRESS_CLASSIFICATION =
|
|
|
|
|
"/v2/api/shipping/addressClassification";
|
|
|
|
|
|
|
|
|
|
/**
|
|
|
|
|
* 按 SKU 查库存({@code POST},<b>不分页</b>)。
|
|
|
|
|
*
|
|
|
|
|
* <p>真机确认:{@code skus} 必填且不能是空数组。</p>
|
|
|
|
|
*/
|
|
|
|
|
public static final String PATH_INVENTORY_BY_SKU = "/v1/inventory/getInventory";
|
|
|
|
|
|
|
|
|
|
/**
|
|
|
|
|
* 批量查库存({@code GET},分页)。
|
|
|
|
|
*
|
|
|
|
|
* <p>真机确认 {@code warehouseCodes} 是<b>必填</b>的 List 参数;
|
|
|
|
|
* {@code page / rows / sidx / sort} 也必填,{@code rows} 默认最高 500。</p>
|
|
|
|
|
*/
|
|
|
|
|
public static final String PATH_INVENTORY_PAGE = "/v2/inventory/get_inventory_by_page";
|
|
|
|
|
|
|
|
|
|
/**
|
|
|
|
|
* 库存变动流水({@code POST},分页)。
|
|
|
|
|
*
|
|
|
|
|
* <p>真机确认 {@code skus} / {@code beginDateTime} / {@code endDateTime} 都必填;
|
|
|
|
|
* 日期跨度最多 30 个自然日。</p>
|
|
|
|
|
*/
|
|
|
|
|
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;
|
|
|
|
|
|
|
|
|
|
/**
|
|
|
|
|
* 库存流水的日期跨度上限(自然日)。
|
|
|
|
|
*
|
|
|
|
|
* <p>文档与真机一致:{@code 2026-10-01}~{@code 2026-10-30} 合法,
|
|
|
|
|
* {@code ~2026-10-31} 不合法(真机回 {@code 查询日期最多包含30个自然日})。</p>
|
|
|
|
|
*/
|
|
|
|
|
public static final int INVENTORY_MOVEMENT_MAX_DAYS = 30;
|
|
|
|
|
|
|
|
|
|
/**
|
|
|
|
|
* 入库计划创建({@code POST})。
|
|
|
|
|
*
|
|
|
|
|
* <p>真机确认必填:{@code orderNo} / {@code warehouseCode} / {@code inventoryType} /
|
|
|
|
|
* {@code productItems}。响应<b>不回仓单号</b>。</p>
|
|
|
|
|
*/
|
|
|
|
|
public static final String PATH_INBOUND_CREATE = "/v1/inbound/createInboundPlan";
|
|
|
|
|
|
|
|
|
|
/**
|
|
|
|
|
* {@code btChargeAt} 的日期区间分隔符。
|
|
|
|
|
*
|
|
|
|
|
* <p>文档示例是 {@code "2025-01-01 ~ 2025-02-01"}(前后各一个空格)。</p>
|
|
|
|
|
*/
|
|
|
|
|
public static final String FEE_DATE_RANGE_SEPARATOR = " ~ ";
|
|
|
|
|
|
|
|
|
|
/**
|
|
|
|
|
* 列表接口的<b>默认</b>排序字段。
|
|
|
|
|
*
|
|
|
|
|
* <p>文档:{@code sidx} 必填,可写死 {@code id}。调用方经
|
|
|
|
|
* {@code OutboundQuery.sortField()} 指定时以调用方为准——文档说「可写死」,
|
|
|
|
|
* 不是「只能写 id」。</p>
|
|
|
|
|
*/
|
|
|
|
|
public static final String ORDER_LIST_DEFAULT_SIDX = "id";
|
|
|
|
|
|
|
|
|
|
/**
|
|
|
|
|
* 列表接口的<b>默认</b>排序方向。
|
|
|
|
|
*
|
|
|
|
|
* <p>文档把 {@code sort} 列为必填,取值为 {@code asc} / {@code desc}。
|
|
|
|
|
* 这是<b>两个可选值</b>,不是常量:调用方经
|
|
|
|
|
* {@code OutboundQuery.sortDirection()} 选,未指定时才用这个默认。</p>
|
|
|
|
|
*/
|
|
|
|
|
public static final String ORDER_LIST_DEFAULT_SORT = "desc";
|
|
|
|
|
|
|
|
|
|
/**
|
|
|
|
|
* 列表接口的时间跨度上限(天)。
|
|
|
|
|
*
|
|
|
|
|
* <p>文档:{@code beginDateTime} 与 {@code endDateTime} 的跨度不要超过 30 天。
|
|
|
|
|
* 超过时适配器在本地拒绝,不把必然被拒的请求发出去。</p>
|
|
|
|
|
*/
|
|
|
|
|
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;
|
|
|
|
|
|
|
|
|
|
/**
|
|
|
|
|
* 未授权 / 未知账户的业务码。
|
|
|
|
|
*
|
|
|
|
|
* <p><b>真机观察</b>(2026-11-12,测试环境):不带任何授权头请求
|
|
|
|
|
* {@code /v2/warehouse/getWarehouse},HTTP 仍是 <b>200</b>,body 是
|
|
|
|
|
* {@code {"statusCode":500,"status":1,"code":999999,"message":"查询失败Unauthorized"}}。
|
|
|
|
|
* 带上任意一个头(值无效)时则返回 Spring 的 500 错误页
|
|
|
|
|
* {@code {"status":500,...,"message":"未知的账户!"}}。</p>
|
|
|
|
|
*
|
|
|
|
|
* <p>因此这个码必须按<b>认证失败</b>处理,不能当普通业务失败——否则宿主只会看到
|
|
|
|
|
* 一条「业务码非 200」,不会去刷新凭据。</p>
|
|
|
|
|
*/
|
|
|
|
|
public static final int UNAUTHORIZED_CODE = 999999;
|
|
|
|
|
|
|
|
|
|
/**
|
|
|
|
|
* 限流:每秒许可数。
|
|
|
|
|
*
|
|
|
|
|
* <p>恒健文档未公开限流值,先按三家仓的保守默认 2 req/s/仓;联调确认后只改这一处。</p>
|
|
|
|
|
*/
|
|
|
|
|
public static final int PERMITS_PER_SECOND = 2;
|
|
|
|
|
|
|
|
|
|
private HengjianConstants() {
|
|
|
|
|
}
|
|
|
|
|
}
|