# 易达云(EDAYUN)接入 ## 当前状态:骨架 | 项 | 状态 | |---|---| | 模块 | ✅ `warehouse-sdk-edayun` 已建、已注册 | | 适配器 / 工厂 | ✅ 类型就绪,能力位为空 | | 获取 token | ✅ 已对接(`POST /oauth/token`) | | 创建产品 | ✅ 已对接(`POST /webApi/skuInfo/v1/createProduct`) | | 创建出库单 | ✅ 已对接(`POST /webApi/order/v1/createOrder`) | | 查询出库单 | ✅ 已对接(`POST /webApi/order/v1/getOrderInfo`) | | 查询面单 | ✅ 已对接(`POST /webApi/order/v1/getOrderLabel`) | | 取消前校验 | ✅ 已对接(`POST /webApi/order/v1/checkCancelStatus`) | | 取消订单 | ✅ 已对接(`POST /webApi/order/v1/cancelOrder`) | | 交易明细(账户流水) | ✅ 已对接(`POST /webApi/accountFlow/list`) | | 订单费用明细 | ✅ 已对接(`POST /webApi/order/cost/v1/selectOrderCostInfoList`) | | 仓租费用明细 | ✅ 已对接(`POST /webApi/order/cost/v1/selectUserRentDetailList`) | | 费用试算(预估) | ✅ 已对接(`POST /webApi/estimate/v1/trial`) | | 库存查询 | ✅ 已对接(`POST /webApi/userSkuStock/v1/queryInventory`) | | 创建 / 编辑自发入库单 | ✅ 已对接(`POST /webApi/entryInfo/v1/saveEntrySpontaneousOrder`) | | 查询入库单 / 入库状态 | ✅ 已对接(`POST /webApi/entryInfo/v1/selectEntrySkuGoodsDetail`) | | 创建退货单 | ✅ 已对接(`POST /webApi/rma/info/v1/saveAndPublish`),仅「自行退回」 | | 退货单详情 | ✅ 已对接(`POST /webApi/rma/info/v1/getOrderDetail`) | | 取消退货单 | ✅ 已对接(`POST /webApi/rma/info/v1/cancel`) | | 退货检验后处理 | ⬜ 等文档(缺行 id) | | BOL 查询(平台仓订单) | ✅ 已对接(`POST /webApi/fbaOrder/v1/getOrderBolList`) | | 物流产品清单 | ✅ 已对接(`POST /webApi/order/listByLogisticProductHasPerm`) | | 物流轨迹 | ✅ 已对接(`POST /webApi/track/getTrackInfoList`) | | 打印箱唛 | ✅ 已对接(`POST /webApi/skuInfo/v2/printBarcode`) | | 打印 SKU 标 | ⚠️ 已实现(`POST /webApi/entryInfo/v1/newPrintCaseMarkContentType`),**真机未启用** | | 承运商清单(客户自有物流) | ✅ 已对接(`POST /webApi/carrier/v1/listCarrierByWarehouse`) | | 仓库清单 | ✅ 已对接(`warehouse/listWarehouseHasPerm` + `warehouse/listActive`) | | 其它业务接口 | ⬜ 等文档 | | 回调 | ⬜ 等文档 | | 真机验证 | ⬜ 等测试环境 | **骨架阶段的行为**:任何业务调用都会抛 `WarehouseUnsupportedCapabilityException`——这是有意为之,不返回空集合。 ## 鉴权(已确认部分) ``` ① POST /oauth/token body: { "client_id": "OMS授权用户名", "client_secret": "密码" } 无业务请求头 → 返回 token ② 业务请求头 token 来自 ① appKey 测试: 7289ded35b198243883151876eaf3213 timestamp 毫秒,5 分钟内有效 sign MD5(body + "." + appSecret),测试环境可传 openApiAdminSecret 免签 ``` **凭据映射**(复用 `ChannelSecret`): | 易达云 | ChannelSecret | |---|---| | appKey(请求头) | `appKey()` | | appSecret(签名用) | `appSecret()` | | client_id(换 token) | `clientId()` | | client_secret(换 token) | `clientSecret()` | **代码位置**: | 类 | 职责 | |---|---| | `auth/EdayunTokenClient` | 换 token,兼容三种响应形态,按 code 区分可重试 | | `http/EdayunRequestFactory` | 构造 token 请求与业务请求;`sign()` 算 MD5 | | `adapter/EdayunAdapter.token(ctx)` | 走 `TokenManager` 缓存(按 `appKey + clientId` 维度) | **真机验证(2026-11-12,PR 环境)**: ```bash POST https://test.omniselling.com.cn/saas-service/openapi/microService/oauth/token Content-Type: application/json {"client_id":"openapi-test","client_secret":"123456"} → HTTP 200 {"access_token":"0dabff46-...","token_type":"bearer","scope":"server"} ``` | 之前不确定的 | 实测结论 | |---|---| | 响应体结构 | **扁平结构**,没有 `code`、没有 `data` 包裹 | | 业务码 | **不返回** `code`;HTTP 200 + 有 `access_token` 即成功 | | 有效期 | **响应里没有**有效期字段(文档说「永久,建议留窗口刷新」) | | refreshToken | **不返回** | 因此实现调整为: - 缺 `code` 不算失败,交给「有没有 access_token」判断 - `expiresAt` 是**估算值**(按 2 小时兜底),作用只是让 `TokenManager` 定期重登一次,不是真的到期 - 兼容分支(`data.access_token` / 顶层 `token`)保留,生产确认后可删 ## 创建产品 ``` POST /webApi/skuInfo/v1/createProduct 请求头:Authorization: Bearer / appKey / timestamp / sign ``` ### 三处反向标志(最容易错) 易达云的布尔字段是 **0 是 / 1 否**,与直觉相反: | 字段 | 0 | 1 | |---|---|---| | `brandFlag` | 是品牌 | 非品牌 | | `logisticsPackagingType` | 自带物流包装 | 不带 | | `electricFlag` | **带电** | 不带电 | | `isMetalMaterial` | 含钢铁铝 | 不含 | 统一封装在 `EdayunYesNo`,**不要手写 `x ? 0 : 1`**——方向很容易写反。 ### 单位 | 项 | 标准模型 | 易达云 | |---|---|---| | 重量 | 克 | **千克** | | 尺寸 | cm | cm | 换算在 `EdayunProductMapper.gramsToKg`。 ### 申报信息必须出口 + 进口各一条 文档:「进出口都要传:一个 sku 至少需要一个出口申报信息和一个进口申报信息」。 但标准模型只有一组申报字段(HS / 原产国 / 申报价值)。当前做法: - 出口:国家 = `countryOfOrigin` - 进口:国家**默认 US**(`DEFAULT_IMPORT_COUNTRY`,**待业务确认**) - 两者共用同一个申报价值 **缺申报价值或原产国时整组不下发**,由仓方报错,不在本地编造。 ### 标准模型没有、暂时硬编码的字段 | 字段 | 当前值 | 说明 | |---|---|---| | `logisticsPackagingType` | 0 | 统一模型没有「是否自带物流包装」 | | `pmFlag` | false | 统一模型没有包材概念 | | `electricFlag` | 1 | 统一模型没有带电信息(默认不带电) | | `brandFlag` | 按 `customItemNo` 有无推 | 有客户编码算品牌 | 这几项等业务确认后,可能要在 `WarehouseProduct` 上加字段。 ### 探针 ```bash # dry-run:只打印要发的报文,不调用 mvn -pl warehouse-sdk-edayun -DfailIfNoTests=false -Dedayun.probe.product=true -Dtest=EdayunCreateProductProbeTest test # 真跑(会在测试仓建档,用 PROBE- 前缀的随机 SKU) ... -Dedayun.probe.write=true -Dedayun.probe.token=... -Dedayun.probe.appKey=... -Dedayun.probe.appSecret=... ``` ## 创建出库单 ``` POST /webApi/order/v1/createOrder 请求头:Authorization: Bearer / appKey / timestamp / sign ``` ### 幂等键是 `poNumber` 文档原话:「取消重推订单的话,请保证相同订单的平台单号(poNumber)跟之前的一样」。 映射:`OutboundCommand.orderRef()` 优先,缺失时退回 `outboundRequestNo()`。 **不能为 null**——它是仓侧唯一幂等依据。 ### 时间戳是毫秒 `promiseShipTime` 是**毫秒**时间戳(文档示例 `1777281423744`),不是秒。 ### 地址要州**全称** | 字段 | 我们要传的 | |---|---| | `destProvinceName` | **`California`**,不是 `CA` | 标准模型的 `ShipTo.stateOrProvince` 通常是二字码(`CA`)。当前**原样透传**, 所以调用方要么直接给全称,要么需要一张州码映射表——**待业务确认**。 ### 面单:要 **URL**,不是 base64 文档要求「物流产品 + 面单信息(carrierName / trackingNo / labels)」两个条件缺一不可, 且 `labels` 是「完整的可访问文件 URL」。 我们的 `labelContentBase64` 语义是 base64 内容,所以: - 传 `https://...` → 透传到 `labels` - 传 base64 → **本地直接拒绝**,提示先上传拿 URL ### 商品行 `unitPrice` 是单价 文档写 `unitPrice`,所以直接取 `OutboundLine.declareValue()`,**不乘数量**。 (注意:运去哪的 `skuAmount` 是总额,是反的。) ### 增值服务 | 标准模型 | 易达云 `addService` | |---|---| | `signatureRequired = true` | `is_signature` | 保价:任意商品行带 `insuredAmount` 就整单下发 `is_insurance`——`addService` 是订单级开关,易达云没有行级保价。 ## 查询出库单 / 面单 ``` POST /webApi/order/v1/getOrderInfo → OutboundOrder POST /webApi/order/v1/getOrderLabel → List(含 labelRef) ``` 两个接口都是 `orderNo`(仓侧单号)与 `poNumber`(我们的来源单号)**二选一**。 实现优先用 `outboundRequestNo` 当 `poNumber`,没有才用 `providerOrderId` 当 `orderNo`。 ### 状态映射(24 个取值折叠) 文档给了 24 个状态,按「宿主是否需要区分」折叠: | 类别 | 易达云取值 | 统一状态 | |---|---|---| | 待发货 | `ReadyToShip` | `SUBMITTED` | | 发货中 | `Shipment` | `PICKING` | | **已发货** | `Shipped` / `Online` / `Delivered` / `Returns` | `SHIPPED` | | **已取消** | `Cancelled` / `InterceptSuccess` | `CANCELLED` | | 异常(19 个) | `DistrError` / `NoCarrier` / `InvError` / `StockLack` … | `EXCEPTION` | 异常类全部归 `EXCEPTION`,**具体原因看 `exceptionCode()`(来自 `errorMsg`)与 `rawStatus`**。宿主对它们的处理都是「人工介入」,不需要 19 个细分状态。 注意 `Shipment`(发货中)不能因为含 `Ship` 就判成已发货——**精确匹配,不做子串**。 ### 面单:多包裹按位置对应 ```json "trackingNo": "1Z111,1Z222", "labels": "https://oss/1.png,https://oss/2.png" ``` 一个包裹(trackingNo)对应一个面单 URL,按逗号位置一一匹配。 输出到 `PackageResult.trackingNumber()` 与 `PackageResult.labelRef()`。 ### 地址:同时给了二字码和全称 `getOrderInfo` 的地址里两套都有: | 字段 | 示例 | |---|---| | `destProvince` | `CA` | | `destProvinceName` | `California` | 标准模型口径是**二字码**,所以优先取 `destProvince`,缺失才用全称。 ## 取消前校验 / 取消 ``` POST /webApi/order/v1/checkCancelStatus → CancelEligibility POST /webApi/order/v1/cancelOrder → CancelResult ``` ### 取消资格映射 | 易达云 `data` | 含义 | 统一资格 | |---|---|---| | `Published` | 可直接取消,**不收费** | `FREE` | | `Shipment` | 可取消,**收费** | `CHARGED` | | `Cancelled` / `InterceptSuccess` | 已取消 / 拦截成功 | `BLOCKED` | | `InterceptProcessing` / `InterceptFailure` | 拦截中 / 拦截失败 | `BLOCKED` | | `UnableCancel` | 状态不允许 | `BLOCKED` | | **未知值** | — | **`BLOCKED`** | **未知一律归 BLOCKED**:取消有代价(可能收费、不可逆),认不出时宁可拒绝。 ### 文档笔误 响应说明里 `InterceptSuccess` 出现了两次(一次是「拦截取消成功」、 一次是「拦截取消失败」)。按订单状态字典的命名,失败按 `InterceptFailure` 处理。 ### 请求体优先级 两个接口请求体相同:`orderNo`(仓侧 ORD 单号)优先级高于 `poNumber`(我们的来源单号)。 实现里两个都给,让仓方按优先级取。 ### 不做「收费必须 acceptCharge」拦截 `checkCancel` 与 `cancel` 是两次调用,中间状态可能变化;是否在 `CHARGED` 时继续取消 由宿主决定。`CancelResult.rawStatus()` 回填仓方的 `msg`(如「订单已出库」)。 `cancel` 返回 `data=false` 时**不是异常**——表示仓侧拒绝,`msg` 带原因。 ### 本期未接的出库能力 `query`(列表查询)显式抛 `WarehouseUnsupportedCapabilityException`——文档还没给。 ## 交易明细(费用) ``` POST /webApi/accountFlow/list → List ``` ### 三条与其它仓不同的口径 **① 同一单号的同一计费项有多条数据——不去重** 文档原文:「同一个单号(ORD-发货单 / REV-收货单)的某个计费项有多条数据」。 所以每条流水都映射成一条 `BillingDocument`,靠 **`serialNumber()`**(账户流水号)区分。 按单号去重会丢账。 **② 金额是 string 且可为负** ```json "billingAmount": "-0.500" ``` 负数 = 扣费,正数 = 充值 / 退费。**不能取绝对值**——那会让扣费和退费变成同一笔。 **③ 币种有两个,优先账户币种** | 字段 | 含义 | |---|---| | `accountCurrency` | 账户币种(**优先**) | | `originalCurrency` | 原币 | 跨币种账户时两者不同,`exchangeRate` 是汇率。 ### 查询约束 | 约束 | 处理 | |---|---| | 没给业务单号时,时间段必填 | 不传 bizNo 又没有时间窗 → 本地拒绝 | | 时间段不能超过 180 天 | 超过且没有 bizNo → 本地拒绝 | | `pageNum` / `pageSize` 必填 | 固定第 1 页、每页 200(上限) | | `bizNo` 支持模糊匹配 | 文档标注「不建议」,我们按精确值传 | **分页**:当前只取第一页(200 条),超过时截断。需要翻页的话要扩展——见 TODO。 ### 计费项分类 `billingCode` 是编码(如 `farawayFee`)而不是分类码,只能按关键字推断: | 关键字 | 归类 | |---|---| | storage / warehouse | `STORAGE` | | operation / handle / handling | `OPERATION` | | freight / shipping / delivery / faraway / remote | `LAST_MILE` | | service / value / pack / label | `VALUE_ADDED` | | **认不出** | **null(不猜)** | 对账时宁可不分类,也不能分错。 ### 统一模型扩展 `FeeQuery` 新增 **计费时间窗**(`settledAfter()` / `settledBefore()`), 与已有的「快照日期」(`snapshotStartDate`,运去哪按仓储费快照查)**语义不同**: | 字段 | 用于 | |---|---| | `snapshotStartDate/EndDate` | 运去哪仓储费的快照日期 | | `settledAfter/Before` | 易达云按 `billingTime` 查 | `BillingDocument` 新增 `serialNumber()`(流水号)与 `accountBalance()`(变动后余额)。 ## 订单费用明细 ``` POST /webApi/order/cost/v1/selectOrderCostInfoList → List ``` **与交易明细的区别**(两个都是费用,但口径完全不同): | | 交易明细 `accountFlow/list` | 订单费用 `selectOrderCostInfoList` | |---|---|---| | 视角 | **账户流水** | **按订单拆的费用报价** | | 金额 | `billingAmount`(string,可为负) | `应收 / 折扣 / 实付` 三个 | | 粒度 | 一条流水一个计费项 | 一个订单展开成多条计费项 | | 附带 | 账户余额、汇率 | 计费重、计费分区、是否偏远 | ### 金额取**实付** 每个计费项有三个金额: ```json "amountReceivable": 20.187, // 应收 "discountPrice": 5.745, // 折扣 "realPayPrice": 14.442 // 实付 ``` 落库金额取 **`realPayPrice`**——对账要以实际发生为准,应收只是报价。 ### 一个订单展开成多条 响应结构是 `rows[] → chargeDetails[] → feeDetails[]`,按**计费项**展开: ``` 一个订单 → 「尾程-运费」「尾程-出库处理费」… 各一条 BillingDocument ``` 多条记录的 `documentNo` 相同,靠 `feeName` 区分。 若某层只有 `chargeDetails` 汇总、没有 `feeDetails`,按汇总记一条「订单费用」。 ### 单号类型要配合 ```json "type": 0, // 0 订单号 / 1 平台单号 / 2 追踪号 "orderNo": "..." ``` 统一模型新增 `FeeQuery.noType()`(`FeeQueryNoType` 枚举)。 **传了不支持的类型会显式拒绝**——静默按别的口径查会让对账金额对不上。 ### 时间窗 ≤ 3 个月 文档写明「最大查询 3 个月」。超过在本地拒绝。 既没有单号也没有时间窗时同样拒绝(避免拉全量)。 ### 费用类型按中文名推断 `billingName` 是中文(如「尾程-出库处理费」),按关键字归类: | 关键字 | 归类 | |---|---| | 仓储 / storage / 仓租 | `STORAGE` | | 处理费 / operation / 操作 | `OPERATION` | | 尾程 / 运费 / 燃油 / 附加费 | `LAST_MILE` | | 增值 / 贴标 / 打包 | `VALUE_ADDED` | | 认不出 | null(不猜) | ## 仓租费用明细 ``` POST /webApi/order/cost/v1/selectUserRentDetailList → List ``` ### 三个费用接口的分工 | | 交易明细 `accountFlow/list` | 订单费用 `selectOrderCostInfoList` | 仓租 `selectUserRentDetailList` | |---|---|---|---| | 视角 | 账户流水 | 按订单拆的费用报价 | **按 SKU + 计费日逐条** | | 费用类型 | 全部 | 全部 | **只有仓储费** | | 金额 | `billingAmount`(string,可负) | 应收 / 折扣 / 实付 | **`rentPrice`**(实收) | | 独有 | 账户余额、汇率 | 计费重、计费分区 | **租期天数、库存件数、计费体积** | ### 时间窗:必填,且「3 个月」的阈值很怪 `billDateBegin` / `billDateEnd` 都必填(缺了报「请选择计费起止时间」)。 真机实测(2026-11-13)边界既不是自然月也不是固定天数: | 窗口 | 天数 | 结果 | |---|---|---| | 6/1 ~ 10/1 | 122 | ✅ 通过 | | 6/2 ~ 10/2 | 122 | ❌ 拒绝 | | 7/2 ~ 10/31 | 121 | ✅ 通过 | | 7/1 ~ 10/31 | 122 | ❌ 拒绝 | | 6/1 ~ 11/1 | 153 | ❌ 拒绝 | 同样的天数、不同的起点,结果不同——所以**没法在本地精确复刻**。 本地守卫(`EdayunQueryWindows`)因此只挡明显超限:超过「+4 个月」直接拒, 挡住「一次拉一年」这类错误;3~4 个月之间放行,由仓方返回 `code=500, msg=计费时间范围不能超过3个月`。订单费用明细用的是同一个守卫。 ### `warehouseIds` 是数字 `providerWarehouseId` 必须是易达云的数字仓 id(如 `98`)。配成 `EDY-WH-1` 这类 OMS 编码会在本地被拒绝——仓侧对非数字是静默查不到,不报错。 ### 金额取 `rentPrice`,币种按原值 ```json "originalPrice": 2.278, "discountPrice": 0, "currencyCode": "CAD", "rentPrice": 2.278 ``` `rentPrice` 缺失时用 `originalPrice - discountPrice` 兜底,两者都没有才记 0。 **币种按 `currencyCode` 原值**(示例是 `CAD`),不默认 USD—— 易达云这里不写死币种。 ### 翻页上限 200 页,超了显式失败 仓租按 SKU + 天出账,3 个月窗口下可能上万条。适配器一页 200 条、最多 20 页 (4000 条);拉满仍有剩余时**抛异常**而不是截断——少算仓租会让对账金额偏小。 遇到时请缩小时间窗再查。 终止条件只看「本页是否满 200 条」:不满即到底。文档里的 `total` 是总行数还是 总页数尚未确认,所以**不拿它当终止条件**。 ### 费用类型固定 STORAGE 这是仓租专口,费用类型不按 `billingName` 猜,直接归 `STORAGE`。 若宿主传了别的 `costType`,或传了运去哪口径的快照日期,都**显式拒绝**。 ### 独有字段不进统一模型 租期天数、库存件数、计费体积、单价这些只在 DTO 里(`EdayunRentDetailDtos.RentDetailRow`), `BillingDocument` 只落金额 / 计费日 / SKU / 单据号。也就是说统一模型拿不到 「这笔是不是按 CBFT 计的」——需要的话再扩展模型。 ### 真机验证(2026-11-13,PR 环境) ``` POST /webApi/order/cost/v1/selectUserRentDetailList {"pageNum":1,"pageSize":200,"billDateBegin":...,"billDateEnd":...} ``` | 结论 | 说明 | |---|---| | 接口通 | 任何窗口都返回 `{"total":0,"rows":[],"code":200}` | | **没有数据** | 2025-01 ~ 2026-12 逐季扫过,全部为空——**映射未在真机验证** | | 校验都在 | `pageSize>200` → 「每页数量最多200」;`warehouseIds>20` → 「仓库最多20个」;起止反了 → 「起始计费时间应小于等于结束时间」 | | 很慢 | `pageSize=200` 单页 6~13 秒(45 天窗口 1.3 秒)。探针把读超时调到 120 秒 | | `warehouseIds` 容错 | 传 `"98"` 字符串也接受(文档写 num_array) | 仓租 Mapping 目前只有单测覆盖(`EdayunRentDetailTest` 16 个)。等仓方在 PR 环境 造出仓租数据后,用探针跑一次拿到真实 `rows` 再校正。 ### 探针 ```bash # dry-run:只打印报文(不联网) mvn -pl warehouse-sdk-edayun -DfailIfNoTests=false \ -Dedayun.probe.rent=true -Dtest=EdayunRentProbeTest test # 真查(只读) ... -Dedayun.probe.rent=true -Dedayun.probe.call=true \ -Dedayun.probe.clientId=... -Dedayun.probe.clientSecret=... \ -Dedayun.probe.appKey=... -Dedayun.probe.appSecret=... \ -Dedayun.probe.warehouseId=98 [-Dedayun.probe.days=30] [-Dedayun.probe.bizNo=...] ``` ## 费用试算(预估) ``` POST /webApi/estimate/v1/trial → List ``` ### 三种预估方式,我们只做「按包裹」 | 方式 | 触发条件 | 我们的实现 | |---|---|---| | 虚拟包裹 | `hasOutboundFeeInputSkuSwitch=true` + `virtualPackageDetails` | ❌ 不下发 | | 按包裹 | `manualInputSwitch=true` + `packageDetails` | ✅ **唯一路径** | | 按 SKU | `manualInputSwitch=false` + `skuInfoDetails` | ❌ 标准模型没有 SKU 清单 | 标准模型 `FeeEstimateQuery` 只带包裹尺寸重量,所以固定走「按包裹」。 ### 三处定值 | 字段 | 值 | 原因 | |---|---|---| | `manualInputSwitch` | `true` | 按 SKU 预估要 SKU 清单 | | `estimatedGoodsType` | `GENERAL_CARGO` | 真机实测:缺了报「手动输入时,货物类型[estimatedGoodsType]不能为空!」;标准模型没有带电信息 | | `packageDetails` | 单元素数组 | 文档:目前仅支持单包裹 | ### 仓:id 或 code 二选一 `warehouseId` / `warehouseCode` 文档要求必填一个。`providerWarehouseId` 是数字就进 `warehouseId`,非数字(如 `USLA`)进 `warehouseCode`。 两者都没有时本地拒绝。 ### 物流产品 id 只认数字 `logisticsProductIds` 要的是数字 id。统一模型的 `logisticsServiceCode` / `logisticsProductCode` 是字符串,**非数字直接不下发**——让仓方返回全部渠道报价, 比传一个查不到的字符串好。`logisticsProductCode` 优先。 ### 响应:只取 successItems ```json {"data":{"successItems":[有报价的渠道],"failItems":[无报价的渠道],"showError":false,"errorInfo":null}} ``` 真机(warehouseId=2, 91761, 22×22×22cm 1000g):`successItems` 4 条、 `failItems` 25 条(全是「不支持派送」)。 - `successItems` → `CarrierQuote`(承运商名取 `logisticProductName`,渠道码取 `logisticProductId`) - `failItems` → **丢弃**。它们没有金额,混进结果就是一堆假渠道 - 全部失败时返回 `carriers()` 为空的仓结果——按能力接口约定表示「该仓无法承运」, 具体原因(`errorInfo`,如「没有物流产品符合预估!」)只在原报文里 ### 重量单位:请求 g、响应 kg 请求 `packageDetails[].weight` 是克;响应 `weight` 是 **kg** (请求 1000g → 响应 `1.000`)。映射时不要把响应重量当克回写。 ### 真机验证(2026-11-13,PR 环境) | 场景 | 结果 | |---|---| | warehouseId=2 + 91761 | ✅ 4 个渠道,最低 5.315 USD(美国经济派送) | | warehouseId=194 | ✅ 同样 4 个渠道(首次跑超时,重试正常) | | warehouseCode=USLA | ✅ 与数字 id 等价 | | 日本邮编 100-0001 + 仓 2 | ✅ code=200,`successItems` 为空、`errorInfo=没有物流产品符合预估!` | | 200×200×200cm / 643kg | ✅ code=200,全部失败(同上) | | 按 SKU 预估 | ❌ `sku[zicoyuio1]信息不存在,请确认!`(PR 环境没建这个 SKU) | | 虚拟包裹 | ❌ `内部服务器错误` | | `estimatedGoodsType` 传 `FOO` | ❌ 被当成未填 | | 缺 `manualInputSwitch` | ❌ 当成按 SKU 预估 | **超时**:首次调用常报 `Read timed out executing POST http://eda-tms/...`, 重试即好。探针读超时按 120 秒设,业务侧建议至少 30 秒以上并允许重试。 ## 创建 / 编辑自发入库单 ``` POST /webApi/entryInfo/v1/saveEntrySpontaneousOrder → InboundReceipt(inboundRequestNo, entryCode) ``` 自发入库单 = 卖家自己备货、自己找代理送到 EDA 仓,**物流信息由卖家维护**。 ### 一个接口三种语义,靠 `saveType` | saveType | 含义 | SDK 入口 | |---|---|---| | 0 | 新增(草稿) | 未暴露(探针可传) | | 1 | 更新 | `improve(ctx, entryCode, cmd)` | | 2 | **保存并发布** | `create(ctx, cmd)` | `create` 直接走 **2(保存并发布)**,不复刻「存草稿 → 再发布」两步。 `improve` 必须给 **仓侧 `entryCode`**(如 `REV25052032239`),不是我们的来源单号; 缺了本地拒绝——否则会变成新建,把单子建重复。 ### 只下发三组,四组服务块不下发 | 组 | 下发 | 说明 | |---|---|---| | `basicInfo` | ✅ | 仓、柜型、头程运输方式 | | `logisticsInfo` | ✅ | 柜号、预计离港 / 到港 | | `cargoInfos` | ✅ | 箱规 + 箱内 SKU | | `domesticTrailerInfo`(头程拖车) | ❌ | 标准模型无字段 | | `customsDeclarationInfo`(出口报关) | ❌ | 同上 | | `customsClearanceInfo`(进口清关) | ❌ | 同上 | | `overseasTrailerInfo`(海外拖车) | ❌ | 同上 | 这四组按「物流产品服务范围」条件必填。标准模型没有对应字段,**不编造**—— 需要时仓方报错,由宿主走人工。要支持得先扩 `InboundCommand`。 ### `cargoInfos` 只来自箱规 创建时 `cargoInfos` 是必填,但只有 `InboundCarton` 带箱长 / 宽 / 高 / 重。 只给 `lines()` 没有箱规 → **本地拒绝**,不凭空编一个箱子。 一箱多 SKU:`InboundCarton` 里同一 `sid` 的多行按 `sid` 归并成一个 `cargoInfo`, 下面挂多条 `boxSkuInfoList`;`sid` 缺失时用箱码归并。 重量 **g → kg**(与创建产品口径一致,`/1000`)。尺寸 / 重量为 0 视为未填不下发。 ### 快递类 / 卡车类的条件必填,我们没有 | 服务范围 | 仓方要求 | 标准模型 | |---|---|---| | 海快 / 空运 / 快递 | `shipCompany`(承运商)+ `waybill`(跟踪单号) | ❌ 无字段 | | 卡车 | `estimatedDepartureTime`(预计离港) | ✅ `predictionShipDate` | 快递类的两个字段不下发,发布时由仓方报错。**不要把柜号塞进 `waybill`** —— 那是两回事。 ### 几个字段的本地约定 | 字段 | 来源 | 说明 | |---|---|---| | `customerOrderNo` | `inboundRequestNo` | 上限 **30**,超了本地拒绝(不让仓方静默截断) | | `shelfWarehouseId` / `shelfWarehouseCode` | `cmd.warehouseId()` 优先,否则账户配置 | 数字走 id,非数字走 code | | `cabinetType` | `cmd.cabinetType()` | 字符串码 → 数字,非数字视为未给 | | `intShippingMethod` | `cmd.transportType()` | 已经是仓方口径的码 | | `shippingProductId` | — | 来自「查询入库物流产品」,标准模型无字段 | ### 入库状态:靠 SKU 明细接口反推 创建只返回 `entryCode`,**不带状态**。状态从 `POST /webApi/entryInfo/v1/selectEntrySkuGoodsDetail` 拿(下文)。 ## 入库单查询 / 状态 ``` POST /webApi/entryInfo/v1/selectEntrySkuGoodsDetail → InboundOrder ``` 按**入库单号**查 SKU 级的预报 / 清点 / 上架信息,一行一个 SKU。 ### 只能按 `entryCode` 查 ```json {"entryCode": "REV24050738176", "pageSize": 200, "pageNum": 1} ``` `entryCode` 是创建时返回的 **REV 单号**,**不能按客户单号查**。所以 `get(ctx, inboundRef)` 的入参必须是 REV 号;`query(ctx, cursor)` 同样把 cursor 当 REV 号用(接口没有列表 / 时间窗),传空直接拒绝,不假装支持增量同步。 创建返回的 `entryCode` 落库后就是查询键——这个要存好。 ### 数量三层 | 易达云 | 统一模型 | 说明 | |---|---|---| | `forecastQuantity` | `plannedQuantity` | 预报数量 | | `actualCheckedQuantity` | `packedQuantity` | 实际清点 | | `shelvesQuantity` | `receivedQuantity` | 上架数量 | 头级数量是各行求和。`firstripQuantity`(头程数量)没有对应字段,不映射。 ### 单头状态由 SKU 状态汇总 接口只给 SKU 级 `status` / `statusName`,没有单头状态。汇总规则: **取最靠前的那个状态**(`InboundStatus.code()` 数值小的优先), 即「还有 SKU 没上架,整单就不算完成」。全部认不出才归 `UNKNOWN`。 ### 状态码表只确认了一个 | 码 | 状态名 | 统一状态 | |---|---|---| | `4` | 已上架 | `COMPLETED` | | 其它 | — | **按中文名兜底推断**,认不出 `UNKNOWN` | 中文名兜底关键字:取消/作废/驳回 → `CANCELLED`;上架中 → `STORING`; 已上架/完成 → `COMPLETED`;清点/收货/卸柜/签收 → `RECEIVING`; 在途/运输/离港/到港 → `IN_TRANSIT`;待/预报/草稿 → `PENDING_SHIPMENT`。 **中文名兜底是临时方案**——名字随语言 / 配置变就会失效。拿到码表后要换成精确码值, 见 TODO #34。 ### 接口回不了的字段 | 字段 | 情况 | |---|---| | 仓库 | 接口不回,用 OMS 配置的 `warehouseCode` | | 创建 / 到仓 / 上架时间 | 接口不回,全部为 null | | 箱明细 `boxes` | 接口是 SKU 维度,没有箱号 | | 承运商 / 柜号 / 批次 | 接口不回 | 所以 `InboundOrder` 只是「数量 + 状态 + SKU 行」的骨架,不是完整单据。 要完整信息需要 entryInfo 的单头查询接口(文档还没给)。 ### 翻页 `pageSize` 固定 200(文档上限 1000),按「本页是否满页」判断到底,最多 20 页 (4000 个 SKU);超了显式失败而不是截断。 ### 探针 ```bash # 只读,不加 write 也会真查 mvn -pl warehouse-sdk-edayun -DfailIfNoTests=false \ -Dedayun.probe.inboundQuery=true -Dtest=EdayunInboundQueryProbeTest test ``` ### 探针 ```bash # dry-run:只打印报文(不联网) mvn -pl warehouse-sdk-edayun -DfailIfNoTests=false \ -Dedayun.probe.inbound=true -Dtest=EdayunInboundProbeTest test # 真发一次(写操作,会在测试仓建入库单,客户单号用 PROBE- 前缀) ... -Dedayun.probe.inbound=true -Dedayun.probe.write=true \ -Dedayun.probe.clientId=... -Dedayun.probe.clientSecret=... \ -Dedayun.probe.appKey=... -Dedayun.probe.appSecret=... \ -Dedayun.probe.warehouseId=2 -Dedayun.probe.sku=ybtest \ [-Dedayun.probe.saveType=0] ``` ## 库存查询 ``` POST /webApi/userSkuStock/v1/queryInventory → Page ``` 一行 = 一个 SKU 在一个仓的库存汇总。**默认只返回总库存大于 0 的数据**, 单页最多 500 条。 ### 字段映射 | 易达云 | 统一模型 | 说明 | |---|---|---| | `stock` | `available` | 可用库存 | | `totalStock` | `onHand` | 总库存 | | `frozenStock` | `reserved` | 冻结库存 | | `toDeliverStock` | `pendingOutbound` | 待出库 | | `inTransitStock` | `inTransit` | 在途 | | `safeStock` | `alertQuantity` | 安全库存(预警) | | `skuName` | `productName` | | | `warehouseCode` | `warehouseCode` | 缺失时回退 OMS 仓编码 | ### 零库存开关是反的 统一模型是「**包含**零库存」,仓方是「**只查**总库存大于 0」: | `includeZeroStock` | `totalStockGreaterThanZero` | |---|---| | null | 不下发(仓方默认 true) | | true | false | | false | true | ### 同步策略:全量拉取 接口没有时间维度,`syncStrategy()` 固定 `FULL_PULL_DIFF`,`updatedAfter` 不生效。 响应也没有更新时间,`asOfUtc` 用调用方注入的时钟。 ### 约束 | 约束 | 处理 | |---|---| | `skuCodeList` 最多 100 个 | 超过本地拒绝 | | `warehouseIdList` 是数字 id | 非数字本地拒绝(同仓租明细) | | 分页 | 游标是页码字符串;`total` 按文档当总行数用,缺失时按满页判断 | ### 真机验证(2026-11-13,PR 环境) | 场景 | 结果 | |---|---| | `warehouseIdList:[2]`,pageSize 100 | `total=339`,本页 100 条,翻页正常 | | 不传仓库过滤 | `total=436` | | `totalStockGreaterThanZero:false` | `total=2436` | | `pageSize` 传 501 / 2000 | **不报错,静默截断到 500** | | `pageSize` 传 0 / -1 | `total=0`、`rows` 为空(不是报错) | | 不传 `pageSize` | 服务端默认返回 **200** 条 | | 不传 `pageNum`,或传 0 | 按第 1 页返回 | | **页码超过最后一页** | **重复返回最后一页**,不是空列表 | | `skuCodeList` 101 个 | `code=500`「skuCode列表最大支持100」 | | `warehouseIdList:["USLA"]` | `code=500`「参数不符合文档规范…parseLong error」 | **页码越界重复返回最后一页**这点最坑:不能拿「本页为空」当循环终止条件, 必须用 `total` 判断。实现里 `nextCursor` 就是这么做的。 ### 字段类型:数字全是字符串 真机返回的 `totalStock` / `stock` / `frozenStock` / `toDeliverStock` / `inTransitStock` / `safeStock` / `nonSaleStock` 全是 **字符串**(`"15499"`), `warehouseId` 也是字符串。DTO 用 `Integer` 由 Jackson 自动转换,没问题。 ### `safeStock` 经常为 null 采样 500 行:**430 行的 `safeStock` 是 null**(`toDeliverStock` 则都有值)。 统一模型约定「仓方未给时为 -1」,所以这里映射成 **-1 而不是 0**, 否则真实的「安全库存 0」和「没配安全库存」分不出来。 ### 未映射的字段 `nonSaleStock`(不可售库存)、`snInStock`、`barcode`、`goodsType`、`countryName` 不在统一模型里。整行按 `inventoryType = 0`(可售)落,**不可售数量被丢弃**—— 需要对账不可售库存时要扩展模型,见 TODO。 ### 探针 ```bash # dry-run:只打印报文(不联网) mvn -pl warehouse-sdk-edayun -DfailIfNoTests=false \ -Dedayun.probe.inventory=true -Dtest=EdayunInventoryProbeTest test # 真查(只读) ... -Dedayun.probe.inventory=true -Dedayun.probe.call=true \ -Dedayun.probe.clientId=... -Dedayun.probe.clientSecret=... \ -Dedayun.probe.appKey=... -Dedayun.probe.appSecret=... \ [-Dedayun.probe.warehouseId=2] [-Dedayun.probe.sku=ybtest] \ [-Dedayun.probe.zeroStock=true] [-Dedayun.probe.page=1] ``` ## 创建退货单 ``` POST /webApi/rma/info/v1/saveAndPublish → WarehouseReturn ``` ### 四种退货方式,我们只做「自行退回」 | `returnType` | 含义 | 必填 | 我们的实现 | |---|---|---|---| | 0 | 未妥投退回(派送失败 / 拒收 / 拦截) | 关联单号 | ❌ | | 1 | 返邮退回(EDA 提供返邮面单) | 关联单号 + 退货人姓名/城市/地址/邮编 + 返邮标签 | ❌ | | **2** | **自行退回(买家自己寄回)** | **关联单号 + 跟踪号** | ✅ **唯一路径** | | 3 | FBA 退回 | 亚马逊单号 + 退货仓 + 承运商 + 跟踪号 + 标签数 | ❌ | `ReturnCommand` 强制要求 `returnTrackingNo`,正好对上「自行退回」; 另外三种要退货人地址或亚马逊单号,标准模型没有对应字段。见 TODO。 ### 响应 `data` 就是退货单号 ```json {"code":200,"msg":"操作成功","data":"RMA2411053149","traceId":"..."} ``` 和运去哪不同(那个只回 code/message,拿不到仓单号),这里能直接落 `providerReturnId`,后续查询 / 取消有单号可用。 接口不回状态,所以 `status` 固定 `UNKNOWN`——**不要当成「已受理」**。 ### 仓:数字优先 `warehouseId`(数字)优先级高于 `warehouseCode`。取命令上的 `warehouseId`, 没有再取账户配置的 `providerWarehouseId`;数字进 `warehouseId`,非数字进 `warehouseCode`(如 `USLA`)。两者都没有时不下发,由仓方按关联单号的仓处理。 ### 处理指令只有「销毁」能确定 `skus[].command` 文档说是「1 上架 / 2 销毁」,但没有给码表。统一模型的 `ReturnDealMethod` 是另一套码(客户自提 / 拍照确认 / 销毁 / 仓库确认),映射: | `ReturnDealMethod` | `command` | |---|---| | `DESTROY` | **2 销毁** | | 其余三种 | 1 上架(都要先入库再处理) | 见 TODO。 ### 未实现的退货能力 | 方法 | 状态 | |---|---| | `queryReturns(ctx, cursor)` | ❌ 文档只给了按单号查,没有列表接口 | | `process(ctx, cmd)` | ❌ 要仓侧明细行 id,而详情响应里**没有行 id**(`checkList` / `skuList` / `shelfList` 都没有) | `queryReturns` 抛 `WarehouseUnsupportedCapabilityException`,不返回空列表。 ### 探针 ```bash # dry-run:只打印报文(不联网) mvn -pl warehouse-sdk-edayun -DfailIfNoTests=false \ -Dedayun.probe.return=true -Dtest=EdayunReturnProbeTest test # 真发一次(会在测试仓建 RMA 单,relationNo 必须是真实出库单号) ... -Dedayun.probe.return=true -Dedayun.probe.write=true \ -Dedayun.probe.clientId=... -Dedayun.probe.clientSecret=... \ -Dedayun.probe.appKey=... -Dedayun.probe.appSecret=... \ -Dedayun.probe.warehouseId=2 -Dedayun.probe.sku=ybtest \ -Dedayun.probe.relationNo=ORD599493019 \ -Dedayun.probe.trackingNo=1Z84V7X00397803717 ``` 报文示例(dry-run 产出): ```json {"returnType":2,"relationNo":"ORD599493019","carrierName":"Fedex","customerRemark":"probe", "skus":[{"skuCode":"ybtest","command":1,"skuNum":1}], "trackingNo":"1Z84V7X00397803717","warehouseId":2} ``` ## 退货单详情 ``` POST /webApi/rma/info/v1/getOrderDetail → WarehouseReturn ``` 请求只有一个 `rmaCode`(**仓侧 RMA 号**,不是 OMS 单号)。响应七块,统一模型只承载 单头与明细行: | 响应块 | 用途 | 进统一模型 | |---|---|---| | `basicInfo` | 状态、关联单号、仓库、退货方式、创建时间 | ✅ 单头 | | `skuList` | 预报要退的 SKU | ✅ 明细(兜底) | | `checkList` | 仓实际收货检验结果 | ✅ **明细(优先)** | | `logisticsInfo` | 退货人地址、返邮信息 | ❌ 标准模型无字段 | | `shipmentParcelList` | 预报包裹尺寸重量 | ❌ | | `packageList` | 跟踪号与包裹状态 | ❌ | | `shelfList` | 实际上架数量 | ❌ | ### 明细行:检验优先,预报兜底 `skuList` 是买家预报要退什么,`checkList` 是仓实际收到的(带异常原因与照片)。 对账以**实际收到**为准,所以 `checkList` 优先;没有检验记录(还没收货)才退回预报。 两边字段类型还不一致:`skuNum` 在 `skuList` 是 **string**,在 `checkList` 是 **number**, 所以分开映射,不合并成一个循环。 ### 状态:码表缺失,只能按中文名推断 文档只给 `status: 1` 这类示例,**没有码表**。`EdayunRmaStatus` 因此只按 `statusName` 中文名兜底,码值一个都没映射: | 中文名关键字 | 归一化 | |---|---| | 驳回 / 拒绝 / 不通过 | `REJECTED` | | 关闭 / 取消 / 作废 | `CLOSED` | | 完成 / 已上架 / 结案 | `COMPLETED` | | 审核 | `PENDING_REVIEW` | | 收货 / 检验 / 清点 | `PENDING_RECEIPT` | | 在途 / 退货中 / 运输 / 已发出 / 待收 | `RETURNING` | | 草稿 / 预报 | `DRAFT` | | 认不出 | `UNKNOWN`(原文进 `rawStatus`) | **否定语义先判**:「审核不通过」不能被「审核」命中成待审核。 ### 响应只有仓名,没有仓编码 `basicInfo` 给的是 `warehouseId`(数字)+ `warehouseName`,没有仓编码。 `warehouseCode` 回退 OMS 仓编码。 ### `data: null` 当作查不到 单号不存在时仓方回 `code=200` + `data: null`,适配器返回 `null`—— 这是「接口通、单不存在」,不是失败,不当异常抛。 ## 取消退货单 ``` POST /webApi/rma/info/v1/cancel → boolean ``` 请求同样只有 `rmaCode`。响应 `data` 是**布尔值**,不是单号: ```json {"code":200,"msg":"操作成功","data":true} ``` ### `data=false` 是仓方拒绝,要抛异常 `code=200` 只说明请求被接受,`data=false` 表示仓方拒绝(如已收货)。 取消是状态变更,**不能静默返回 false** 让调用方以为没事——适配器抛 `WarehouseException`,`msg` 里的原因原样带出。 `data` 缺失同样按失败处理。 ### 只认仓侧 RMA 号 幂等键 `warehouseCode + providerReturnNo + "cancel"`。传 OMS 单号仓方查不到, 所以宿主必须先用创建 / 详情拿到 `providerReturnId`。 ## BOL 查询(平台仓订单) ``` POST /webApi/fbaOrder/v1/getOrderBolList → List ``` 店铺订单 / 平台仓订单共用,`orderNo` 传 EDA 的平台仓订单号(如 `FBA473182144`)。 ### 与入库 BOL 不是一回事 | | `inbound().bols()` | `orderBols()` | |---|---|---| | 对象 | 头程入库计划单 | 平台仓 / 店铺订单 | | 返回 | `List` 文件地址 | 带提货状态、约定/实际提货量、POD | 方法名带 `order` 前缀是因为 `InboundCapable.bols` 已有同签名同参数、 返回值不同的方法,同一适配器实现两者时擦除后无法区分。 ### 状态码表只有一个确认 `status = 11 → 已妥投` 是文档响应示例确认的。其余状态 `EdayunBolStatus` 按 `statusName` 中文名兜底,认不出归 `UNKNOWN`,原值留在 `BolDocument.rawStatus()`。 ### 真机验证(2026-11-16) `orderNo = FBA473182144` → `code=200, data.totalNum=null, bolList=null`。 **PR 环境没有 BOL 数据**,映射只被单测覆盖。 ## 物流产品清单 ``` POST /webApi/order/listByLogisticProductHasPerm → List ``` ### `-998` 是哨兵值,要跳过 最后一条常是 `productId = -998`、`productName = 使用分物流规则`, 其余字段全 null。它不是可选的物流产品,映射时**跳过**, 否则宿主的渠道清单里会多一个查不到的 id。 ### 入参 | 字段 | 我们的值 | |---|---| | `warehouseId` | 账户配置的 `providerWarehouseId`(数字);非数字时不传 | | `applicableBusiness` | 固定 **1 店铺订单**——统一模型不区分业务类型 | 文档说 `warehouseId` 必填,**实测不传会返回全部仓的产品**(162 条 vs 仓 2 的 36 条)。 ### 统一模型只有 3 个字段 `LogisticsProduct` 只有编码 / 名称 / 是否跨国;**易达云不回跨国标记**,恒 `false`。 承运商类型、派单方式、面单获取方式、增值服务选项、适用业务都在 DTO 里。 ### 真机验证(2026-11-16) | 场景 | 结果 | |---|---| | 仓 2 + 店铺订单 | 36 条 | | 仓 2 + 平台仓订单 | 23 条 | | 仓 2 + 退货单 | 35 条 | | 仓 2 不传业务类型 | 37 条(含 -998) | | 仓 98 + 店铺订单 | 22 条 | | 不传仓 | 162 条(全账号) | `-998` 每条都出现,确认是哨兵值。 ## 物流轨迹 ``` POST /webApi/track/getTrackInfoList → List / TrackingInfo ``` ### 请求体是**纯字符串数组** ```json ["1Z84V7X00397803717"] ``` 文档把字段名留空了,示例写成 `[{"": ["aa","bb"]}]` 是自动生成的占位。 真机实测只有纯数组能通:嵌套对象会被静默忽略,返回空 body。 ### 「未匹配到轨迹」不是错误 查不到时仓方回 `code=500, msg=未匹配到轨迹`。但对调用方来说, 这和「运单刚生成、还没揽收」是同一件事——适配器把它当**空结果**处理 (`track` 返回空列表,`trackShipment` 返回 `null`),不抛异常。 其它 500(如「系统异常」)仍然抛。 `msg=跟踪号为空` 同理按空结果处理。 ### 上网时间 / 妥投时间是**带时区的字符串** 文档说明「主要关注上网时间跟妥投时间」,所以统一模型的 `TrackingInfo` 新增两个字段直接承载: | 易达云 | 统一模型 | |---|---| | `onlineTime`(`2025-08-19 08:17:00`) | `firstOnlineAt()`(Instant) | | `deliveredTime` | `deliveredAt()`(Instant) | | `timeZone`(`GMT-04:00`) | 解释上面两个时间用 | **同一个响应里时间口径混杂**:`onlineTime` / `deliveredTime` 是字符串, 而节点时间 `recentDescribeTime` 是毫秒。字符串按 `timeZone` 解析,解析失败留 null。 时区解析认 `GMT±HH:mm` / `UTC±HH:mm` / `±HH:mm`;认不出按 UTC, **不猜成仓所在时区**(那是另一个概念)。 ### 节点状态优先 eventStatus 节点上的 `status` 是数字码(码表未给),`eventStatus` 是字符串。 映射时 `eventStatus` 优先,缺失才退回数字码的字符串形式。 ### 真机验证(2026-11-16) | 跟踪号 | 结果 | |---|---| | 文档示例 `LF-1741871641090` | `code=500 未匹配到轨迹` | | 出库单里的真实 `889542071709` | `code=500 未匹配到轨迹` | | `1Z84V7X00397803717` | 同上 | **PR 环境没有任何可查到的轨迹**,映射只被单测覆盖。 ## 打印箱唛 / SKU 标 ### 两个端点名与实际语义是反的 已与仓方确认: | 端点 | 实际打印 | 我们的方法 | 能力位 | |---|---|---|---| | `/webApi/skuInfo/v2/printBarcode` | **箱唛**(外箱标) | `printCaseMarks(...)` | `CASE_MARK_PRINT` | | `/webApi/entryInfo/v1/newPrintCaseMarkContentType` | **SKU 标** | `printSkuLabel(...)` | 走入库 `SKU_LABEL` 语义 | **不要被路径名误导**。代码里两个方法的 javadoc 都写了这条提醒。 ### 箱唛(printBarcode) ``` POST /webApi/skuInfo/v2/printBarcode → WarehouseLabel ``` 请求体按 SKU 列表打,服务端把每个 SKU 的条码排版成箱唛 PDF。 **四种纸张尺寸实测(MediaBox,单位 pt):** | `pageSize` | 文档标称 | 实测 MediaBox | 折算 | |---|---|---|---| | 0 | 7×3cm | `198 × 85` | 69.9 × 30.0 mm | | 1 | 10×6cm | `284 × 170` | 100.2 × 60.0 mm | | 2 | 6×4cm | `283 × 425` | **99.9 × 150.0 mm** | | 3 | A4 | `170 × 113` | **60.0 × 39.9 mm** | **`pageSize=2` 和 `pageSize=3` 的文档标称与实际相反**:文档说 2 是「6×4cm」、 3 是「A4」,实际 2 打出来是 100×150mm、3 打出来是 60×40mm。 枚举按**实测尺寸**命名(`SIZE_60_40` / `SIZE_100_150`),码值原样保留。 **本地提前挡的两条**(仓方都回「内部服务器错误」,看不出原因): | 约束 | 本地行为 | |---|---| | SKU 数 > 50 | 构造期拒绝(仓方提示「最多打印50个SKU」) | | 份数 ≤ 0 | 构造期拒绝 | `isPrintSkuName` 只在 `true` 时下发,`false` 交给仓方默认。 **真机(2026-11-16)**:`ybtest` 拿到真实 PDF,四种纸张都 `code=200`。 仓方其它校验:缺 `productInfos` →「产品信息不能为空」、缺 `pageSize` → 「纸张尺寸不能为空」、SKU 不存在 →「sku=XXX信息不存在」。 ### SKU 标(newPrintCaseMarkContentType) ``` POST /webApi/entryInfo/v1/newPrintCaseMarkContentType → WarehouseLabel ``` **真机未启用**:PR 环境该路径报「接口不存在或未启用」,去掉 `ContentType` 后缀的 `newPrintCaseMark` 能过参数校验(缺 `pageSize` 报 「纸张不能为空」、缺 `madeInChina` 报「产地标签不能为空」),但补全后一律 「内部服务器错误」。所以本接口实现是**按文档写的**,映射只有单测覆盖。 纸张码值不连续:`100×100=4` / `100×150=2` / `A4=5`。统一枚举 `LabelSizeType` 为此补了 `A4`。 统一模型的 `BoxLabelCommand` 没有「选哪些箱」,默认整单打印;部分箱用 `printSkuLabel(ctx, cmd, CaseSelection)` 重载(系统箱号 / SKU / 箱序号区间 / 客户箱号区间四选一,全空本地拒)。 `madeInChina` 与 `separation` 是易达云特有语义,统一模型没有对应概念 → 默认关。 ## 承运商清单(客户自有物流服务) ``` POST /webApi/carrier/v1/listCarrierByWarehouse → List ``` 客户自有物流(自有物流 + 客户上传面单)下单时要用:`carrierName` 可以填承运商名, 也可以用某个下属物流服务的名字。 ### 两层结构 ``` 承运商(carrierId / carrierNameEn / carrierNameCn) └── 物流服务(logisticId / logisticName) ``` 统一模型新增 `WarehouseCarrier`(带 `logists()`),挂到 `WarehouseDirectoryCapable.carrierDirectory(ctx)`,门面 `carrierDirectory()`。 原有的 `carriers()` 返回 `List`(只有码),保留不动; `carrierDirectory()` 的默认实现会把 `carriers()` 的码包装成无名条目, 能给出结构的仓覆盖它。 ### `ownLogisticList` 文档写成对象、真机是数组 ```json "ownLogisticList": [ {"logisticId":"583","logisticName":"..."}, ... ] ``` DTO 按 `List` 收。 ### 入参 | 字段 | 我们的值 | |---|---| | `warehouseId` | 账户配置的 `providerWarehouseId`(数字);非数字/为空时不传 | | `countryCode` | 本地不传(统一模型没有对应字段) | ### 真机验证(2026-11-16) | 场景 | 结果 | |---|---| | 仓 2 | **11 个承运商**,FedEx 下有 12 个物流服务 | | 不传仓 | 22 个承运商 | | `countryCode=US` | 10 个承运商 | ### 仓库清单 见下面的「仓库清单」一节——`warehouses()` 现在有实现了。 ## 仓库清单 两个接口用途完全不同,**不要混用**: | 接口 | 含义 | 实测条数 | 我们的方法 | |---|---|---|---| | `warehouse/listWarehouseHasPerm` | 当前客户**有权限**的仓 | 69(跳过 -999 后 68) | `warehouses(ctx)` | | `warehouse/listActive` | 平台**全量**激活仓 | 118 | `activeWarehouses(ctx, inbound)` | `listActive` 含当前客户**没授权**的仓(68 个有权限的仓里,有 50 个不在里面), 所以**给客户选仓必须用 `warehouses()`**。 ### `-999` 是「智能分仓」哨兵值 `listWarehouseHasPerm` 最后一条固定是: ```json {"warehouseId":"-999","warehouseName":"使用分仓规则","warehouseNameEn":"divideWarehouse", "warehouseCode":"USMC", ...其余全 null} ``` 不是真实仓,映射时跳过——和物流产品接口的 `-998` 是同一套路。 ### `listActive` 的 `warehouseOperationType` | 值 | 含义 | 实测 | |---|---|---| | 0 | 尾程仓 | 111 条 | | 1 | 头程仓 | 7 条 | | 不传 | 两者之和 | 118 条 | 文档说必填,实测不传也能通。`activeWarehouses(ctx, inboundWarehouse)` 会明确传 0 或 1。 ### 统一模型的口径 `WarehouseFacility.warehouseCode()` 放的是**仓编码**(`USLA` / `USALA-Q031`), 数字 id(`2` / `40269`)进 `providerWarehouseId()`——两者不能互换。 字段映射: | 易达云 | 统一模型 | 备注 | |---|---|---| | `warehouseCode` | `warehouseCode` | 下单用 | | `warehouseId` | `providerWarehouseId` | 数字,字符串形式 | | `warehouseName` | `name` | 缺失回退英文名 | | `address` | `address1` | 仓方只给单行地址 | | `provinceCode` | `province` / `state` | 两个字段都填 | | `warehouseManagerName` / `Tel` | `contactName` / `mobilePhone` | 仅 `listActive` 有 | ### 两个接口的字段数差很多 `listActive` 返回 47 个字段(容量、营业时间、负责人邮箱、地图链接等), `listWarehouseHasPerm` 只有 17 个。DTO 只声明统一模型用得上的十几个—— Jackson 会忽略未知字段。 ## 待确认(问易达云) | # | 要确认 | |---|---| | 1 | **后续业务接口文档**(出库 / 库存 / 费用 / 回调) | | 2 | ~~测试环境~~ ✅ 已确认:`test.omniselling.com.cn` + `openapi-test` | | 3 | 申报信息的**进口国**怎么取(当前默认 US,是猜的) | | 4 | `declarationType` 的码值(0 出口 / 1 进口,是推断的) | | 5 | 统一模型缺的字段(带电 / 包材 / 物流包装)要不要加到 `WarehouseProduct` | | 4 | **限流**:每秒许可数、单日配额 | | 5 | **能否在 PR 环境走写操作**(建单 / 取消 / 销毁),决定探针设计 | | 6 | **回调**:验签算法、时间戳单位、响应体格式、是否按路径区分 | | 7 | **费用口径**:是否有费用类型码(运去哪只有中文名) | | 8 | **库存同步**:支持按时间增量还是只能全量 | ## 骨架已定的部分 ``` warehouse-sdk-edayun/ ├── pom.xml └── src/main/java/common/ecommerce/edayun/ ├── EdayunConstants.java 端点 / 路径 / 限流(带 TODO 占位) ├── adapter/ │ ├── EdayunAdapter.java 能力位为空,未实现能力不声明 │ └── EdayunAdapterFactory.java ├── dto/package-info.java 一个接口一个文件 ├── enums/package-info.java 平台枚举约定 ├── http/package-info.java 信封校验约定 └── webhook/package-info.java 回调约定 ``` **测试**:`EdayunAdapterTest`(5 个)验证类型接对、能力位为空、 未实现能力显式拒绝、注册后可解析、能力查询不触发真实 API。 ## 接下来怎么推进 按 [onboarding-checklist.md](../onboarding-checklist.md): 1. 拿到文档后补 `EdayunConstants` 的路径常量 2. 按接口逐个补 `dto/` + `adapter/XxxMapper` + `enums/`(阶段 2 的 6 步) 3. 写只读探针 → 真机验证 → 全链路探针 4. 补回调实现 5. 更新本文档 ## 已知的坑(从运去哪/信仓带来的经验) | 坑 | 应对 | |---|---| | 文档参数名可能带 `query.` 前缀而实际不带 | 真机验证时必须核对 | | 有些接口没有 `code` 只有 `status` | 信封校验要兼容两种 | | 文档示例常是自动生成的占位符 | 不看示例值,看真机返回 | | 单位可能未标注 | 真机验证量级(kg vs lb 差 2.2 倍) | | 状态码可能依赖上下文(单据类型) | `(type, status)` 一起带出去 |