# 易达云:待确认事项 接入过程中发现、需要业务或仓方确认的点。**先记下来,不阻塞接口对接。** ## 待仓方确认 | # | 问题 | 当前处理 | 影响 | | 1 | **创建产品是否需要 `declarationInfoList` 的进口国** | 默认 `US` | 申报准确性 | | 2 | `declarationType` 码值(0 出口 / 1 进口) | 按示例推断 | 申报方向可能反 | | 3 | 业务接口能否用 `openApiAdminSecret` 免签 | 当前一律用 `appSecret` 算 MD5 | 若只有 token 接口免签,现在是正确的 | | 4 | 创建产品同 SKU 重复调用的行为 | 按「创建」语义处理,无更新接口 | 重复建档会报错 | | 5 | 出库单 `getOrderInfo` 的 `carrierInfoList` 是否总与追踪号一一对应 | 按数组原样映射 | 多包裹场景 | | 11 | 交易明细超过 200 条时如何翻页 | 当前只取第一页 | 大账户对账会漏 | | 12 | `billingCode` 有没有完整字典(现在按关键字推断) | 认不出归 null | 费用分类准确度 | | 13 | 订单费用明细的 `billingId` 能否作为幂等键 | 当前未用作主键 | 重复拉取去重 | | 14 | 仓租明细的 `rentDays` / `totalStock` 语义(累计值还是当日值) | 未使用,只落金额 | 宿主想按天分摊成本时需要 | | 15 | 仓租 `total` 是「总行数」还是「总页数」 | 不用它当终止条件,只看本页是否满 200 条 | 无(已规避) | | 16 | 仓租 3 个月窗口在 20 页(4000 条)内是否够用 | 超出显式失败 | 大仓对账可能需缩窗 | | 17 | **PR 环境没有仓租数据**(2025-01~2026-12 全空) | 映射只有单测覆盖 | 需仓方造数据才能真机验证 | | 18 | 3 个月阈值的确切规则(同天数不同起点结果不同) | 本地只挡 >4 个月,其余交仓方判定 | 无(已规避) | | 19 | 订单费用明细**只给单号、不给时间窗**会报「计费时间必填」 | 本地仍允许单号查询(会让仓方报错);是否改成必须给时间窗待定 | 按单号查费用会失败 | | 20 | 费用预算的 `preferentialEstimatedPrice`(实测 `0.000`)语义 | 未使用 | 有优惠时可能少算 | | 21 | 费用试算首次调用常 `Read timed out executing POST http://eda-tms/...` | 探针读超时 120 秒 | 宿主需允许重试 | | 22 | 货物类型 `estimatedGoodsType` 目前固定 `GENERAL_CARGO` | 标准模型没有带电信息 | 带电货预估不准 | | 23 | 虚拟包裹预估在 PR 环境「内部服务器错误」 | 不实现 | 无(暂不需要) | | 24 | 库存 `nonSaleStock`(不可售)在统一模型无独立字段 | 整行按可售落,不可售数量丢弃 | 想对账不可售库存时需扩展 `InventorySnapshot` | | 25 | 库存响应没有更新时间,`asOfUtc` 只能取本地时钟 | 用调用方注入的 clock | 快照时间与仓侧实际变动时间有偏差 | | 26 | 库存 `total` 是否确为总行数(文档写「响应数据总数」) | 按总行数用,缺失时退回满页判断 | 真机跑一次即可确认 | | 27 | ~~入库单没有查询接口~~ ✅ 已解决:`selectEntrySkuGoodsDetail` | `get()` / `query()` 按 `entryCode` 查 | 只能拿 SKU 级数据,单头 / 时间 / 箱明细仍缺 | | 28 | 入库状态是否有回调 | 未接 | 目前靠轮询 SKU 明细 | | 29 | 自发入库单的 `shippingProductId`(入库物流产品 id) | 不下发 | 发布时仓方可能报缺物流产品 | | 30 | 快递类必填的 `shipCompany` / `waybill` | 不下发,标准模型无字段 | 快递类入库单发布不了 | | 31 | `estimatedDepartureTime` 用 `predictionShipDate` 是否口径正确 | 按「预计发运日 = 预计离港」映射 | 卡车类可能对不上 | | 32 | 头程拖车 / 报关 / 清关 / 海外拖车四组服务块 | 不下发 | 这些服务范围的入库单发布不了 | | 33 | `intShippingMethod` / `cabinetType` / `logisticsType` 的码值字典 | 透传 `transportType` / `cabinetType` | 传错码仓方会拒绝 | | 34 | **入库 SKU 状态码表**:只确认了 `4=已上架` | 其余按 `statusName` 中文名兜底 | 中文名变化会让状态判错 | | 35 | 入库明细接口不回仓库 / 创建时间 / 到仓时间 / 箱号 | 仓库用 OMS 配置;时间与箱明细为 null | 拿不到完整单据,需要 entryInfo 单头查询接口 | | 36 | 是否有入库单列表 / 时间窗查询 | `query()` 的 cursor 当 entryCode 用 | 无法做增量同步,只能按单号轮询 | | 37 | `forecastWeight` / `weight` 是克、`firstWeight` 是千克 | 未映射(统一模型没有行级重量) | 想按箱对账重量时需要 | | 38 | 退货单**没有列表查询** | `queryReturns` 显式拒绝 | 无法批量同步退货单 | | 39 | 退货 `skus[].command` 码表(文档只写「1 上架 / 2 销毁」) | 只确定 DESTROY→2,其余都归 1 | 非销毁类处理方式可能与仓方预期不符 | | 40 | 退货 `valueAddedService` / `shelveSkuCode` / `catalog` / `picUrls` 码值与语义 | 不下发 | 重新包装 / 换标上架等场景发不了 | | 41 | 未妥投 / 返邮 / FBA 三种退货方式要不要做 | 只实现 `returnType=2` | 买家退货的返邮面单、FBA 退货都得人工 | | 42 | 退货创建是否需要「同一关联单号分次退」的幂等键 | 用 `returnRequestNo`(OMS 单号) | 同一单多次退要各自生成新 OMS 单号 | | 43 | 退货 `warehouseId` 缺省时仓方是否真按关联单号的仓走 | 不下发 | 可能落到错误仓 | | 44 | 库存 `pageNum` 超过最后一页会**重复返回最后一页** | 用 `total` 判断终止,不看空页 | 无(已规避) | | 45 | 库存 `pageSize` 超过 500 被**静默截断** | 本地也截到 500 | 无(已规避) | | 46 | 库存 `safeStock` 大量为 null(采样 500 行有 430 行) | 映射成 -1(统一模型约定) | 宿主展示时要区分 -1 与 0 | | 47 | 创建出库单的 eBay `ebayTransactionId` / `ebayItemId`、亚马逊 `salesPlatformOrderNo` / `sellerId` | 不下发(标准模型无字段) | 拿不到平台政策保护(OTDR 等) | | 48 | 创建出库单的 `carrierProductId` / `pickUpType` / `customerLogisticsAccountId` / `orderTag` | 不下发 | 指定物流产品、自有物流自提单发不了 | | 49 | 创建出库单的 `meteringResultList` / `truckAppointment` / `addServiceAttachFiles` | 不下发 | 定制打包、卡车约车、增值服务附件都不支持 | | 50 | **退货状态码表**(`basicInfo.status`)完全没给 | 只按 `statusName` 中文名推断,码值不映射 | 中文名变化会让状态判错 | | 51 | 退货详情**没有明细行 id**(`checkList` / `skuList` / `shelfList` 都没有) | `process()` 显式拒绝 | 检验后处理(上架 / 销毁)做不了 | | 52 | 退货详情的退货人地址、预报包裹、包裹状态、实际上架数量 | 只在 DTO,不进统一模型 | 宿主要这些数据得自己解析原报 | | 53 | `skuList[].command` 标 number、`shelfList[].command` 标 string | 两边分别声明 | 无(已兼容) | | 54 | 取消退货 `data=false` 的拒绝原因只有 `msg` 文本 | 抛异常并带出 msg | 宿主只能靠文本判断原因 | | 55 | **BOL 状态码表**(`bolList[].status`)只有 `11=已妥投` 确认 | 其余按 `statusName` 中文名兜底 | 状态判错 | | 56 | PR 环境没有 BOL 数据(`bolList=null`) | 映射只有单测覆盖 | 需仓方造数据才能真机验证 | | 57 | BOL 接口属「平台仓订单(FBA)」,统一模型没有平台仓订单概念 | 挂 `BolCapable.orderBols(providerOrderNo)` | 宿主需自行持有 EDA 的平台仓单号 | | 58 | 物流产品的 `carrierType` / `deliveryType` / `labelGetMethod` / `serviceAttribute` / `valueAddedOptions` 码表 | 不进统一模型,只在 DTO | 宿主想按业务类型筛渠道时缺依据 | | 59 | `LogisticsProduct.crossCountry` 易达云不回 | 恒 false | 跨国渠道无法识别 | | 60 | 物流产品接口的 `applicableBusiness` 只能固定 1(店铺订单) | 统一模型不区分业务类型 | 平台仓订单 / 退货单的专属渠道看不到 | | 61 | **轨迹 `status` / 节点 `status` 码表**完全没给 | 节点优先 `eventStatus` 字符串,汇总只透数字 | 状态判错 | | 62 | PR 环境查不到任何轨迹(连出库单里的真实跟踪号都「未匹配到轨迹」) | 映射只有单测覆盖 | 需仓方造数据才能真机验证 | | 63 | 轨迹接口一次可查多个跟踪号,统一模型只有单号口径 | 逐个查、按单号匹配 | 批量查只能循环调用 | | 64 | 轨迹的 `eventStatus` 取值(文档示例是 `"string"` 占位) | 原样透传 | 宿主无法按事件类型分支 | | 65 | 条码打印的纸张尺寸只有 4 档(7×3/10×6/6×4/A4),与入库贴标的 14 种不重叠 | 独立枚举 `BarcodePaperSize` | 宿主换标签纸时要选对枚举 | | 66 | 条码文件地址的**有效期**未知(OSS 链接) | 原样返回,不缓存 | 宿主存旧链接可能 403 | | 67 | 条码打印是否有限流 / 是否计费 | 未处理 | 大批量打印可能被限 | | 68 | **箱唛接口在 PR 环境未启用**(`newPrintCaseMarkContentType` 报「接口不存在或未启用」;去掉后缀的 `newPrintCaseMark` 能过参数校验但一律「内部服务器错误」) | 按文档实现,映射只有单测 | 上线前必须真机验证 | | 69 | 箱唛纸张码值 4/2/5 不连续 | 独立枚举 `EdayunCaseMarkPaper`,按映射表走 | 无(已规避) | | 70 | 箱唛的 `madeInChina` / `separation` 统一模型没有语义 | 默认关 | 需要打「Made in China」时得走扩展重载 | | 71 | 箱唛选箱条件(系统箱号 / SKU / 箱序号 / 客户箱号)统一模型没有 | 提供 `CaseSelection` 扩展重载 | 宿主想要部分箱打印必须用易达云专有 API | |---|---|---|---| ## 待业务确认 | # | 问题 | 当前处理 | 影响 | |---|---|---|---| | 6 | **派送地址的州要全称(California)还是二字码(CA)** | 原样透传 | 所有出库单地址 | | 7 | 统一模型缺的字段:带电 / 包材 / 物流包装 | 创建产品里硬编码为「不带」 | 带电商品无法正确申报 | | 8 | 保价服务(`is_insurance`) | 任意商品行有 `insuredAmount` 即整单下发 `is_insurance` | 混合保价单会整单保价 | | 9 | `OutboundCommand` 没有 `carrierProductId`(易达云物流产品 id) | 未下发,走仓方默认分物流规则 | 指定物流产品 | | 10 | `channelName` 从 `Platform` 枚举推(AMAZON_SC → Amazon) | 首段大写 | 非标准平台名可能对不上 | ## 已确认(不需要再问) | 项 | 结论 | |---|---| | 测试基址 | `https://test.omniselling.com.cn/saas-service/openapi/microService` | | 测试账号 | `openapi-test` / `123456` | | token 接口响应 | 扁平结构,无 `code`,无有效期,`token_type=bearer` | | token 请求头 | `POST /oauth/token` **不带** `token` 头 | | 业务请求头 | `Authorization: Bearer ` + `appKey` + `timestamp` + `sign` | | 签名算法 | `MD5(body + "." + appSecret)`,小写十六进制 | | 时间戳单位 | 毫秒,5 分钟内有效 | | 布尔标志 | **0 是 / 1 否**(与直觉相反) | | 重量单位 | kg(我们的是 g,需换算) |