You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

12 KiB

易达云:待确认事项

接入过程中发现、需要业务或仓方确认的点。先记下来,不阻塞接口对接。

待仓方确认

# 问题 当前处理 影响
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 SKU 标接口调通但仓方内部报错:路径 /webApi/entryInfo/v1/newPrintCaseMark 确认存在(缺参数有中文校验提示),但参数补全后一律「内部服务器错误」,试过 6 种 pageSize、madeInChina 0/1、separation、箱序号区间、skuCode、caseCodeList、不存在的 entryCode 都一样 按文档实现,映射只有单测 上线前必须真机验证
69 SKU 标纸张码值 4/2/5 不连续 独立枚举 EdayunSkuLabelPaper,按映射表走 无(已规避)
72 printBarcode 的 pageSize=2 / pageSize=3 文档标称与实际相反(文档 2=6×4cm、3=A4;实测 2=100×150mm、3=60×40mm) 枚举按实测尺寸命名,码值不变 按文档标称选纸会打错
73 两个端点名与实际语义相反(printBarcode=箱唛、newPrintCaseMark=SKU 标) 代码按实际语义命名并在 javadoc 标注 无(已规避)
74 仓库清单有两个接口,listActive 含未授权仓 warehouses() 只走 listWarehouseHasPerm 用错会给出客户没权限的仓
77 listWarehouseHasPerm 末条固定是 -999(智能分仓) 映射时跳过 无(已规避)
78 warehouseRegionType / warehouseStatus / privateFlag 码表只部分确认 只在 DTO,不进统一模型 宿主想按区域类型筛选时缺依据
79 listActive 比 listWarehouseHasPerm 多 30 个字段(容量 / 营业时间 / 负责人邮箱等) 不声明,Jackson 忽略 想用这些字段需扩展 DTO
75 承运商接口的 countryCode 过滤统一模型没有对应字段 不下发 宿主想按国家筛承运商得用扩展方法
76 ownLogisticList 文档写成对象、真机是数组 DTO 按 List 收 无(已兼容)
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 <token> + appKey + timestamp + sign
签名算法 MD5(body + "." + appSecret),小写十六进制
时间戳单位 毫秒,5 分钟内有效
布尔标志 0 是 / 1 否(与直觉相反)
重量单位 kg(我们的是 g,需换算)