金蝶云星辰物流公司查询接口字段手册权威教程

这个接口解决什么问题

在零售业跨系统集成里，物流公司是销售出库、发货、运输结算的共同主数据。聚水潭侧需要稳定的物流公司编码与联系方式，金蝶云星辰侧负责维护官方主数据。通过 /jdy/v2/bd/logistics_company 这个查询接口，可以把金蝶的物流公司主数据稳定地同步到聚水潭，支撑发货单映射、物流费用结算和编码对照，避免两边手工维护。

接口能力总览

• 认证方式：金蝶云星辰 V2 标准的 OpenAPI 鉴权，需在请求头携带 AccessToken（通过 /jdy/v2/oauth/token 获取），通常配合 AppKey/AppSecret 使用。
• 请求结构：GET /jdy/v2/bd/logistics_company，支持 page、page_size 两个分页参数；明细数据通过 otherRequest.detailAPI（/jdy/v2/bd/logistics_company_detail）获取。
• 响应结构：标准 JSON，包含 data（数组）与分页元数据（总条数、总页数）。每条记录同时提供 id（主键）和 number/bill_no（业务编码）。
• 分页/增量模式：基于页码分页（默认 page_size=10），定时任务按 */5 * * * * 轮询；增量判断一般依赖 modify_time 做时间戳增量。
• 策略类型：effect: QUERY，Target 配置为「写入空操作」，属于纯查询主数据策略。

典型字段映射

在轻易云上如何配置

1. 适配器：在轻易云「数据源管理」里新建「金蝶云星辰 V2」连接，填入租户 ID、AppKey/AppSecret，先调用 /jdy/v2/oauth/token 拿到 AccessToken。
2. 接口封装：选择「金蝶云星辰 · 业务单据」分类下的「物流公司查询」模板，请求方法默认 GET，自动追加 page、page_size。
3. 元数据映射：metadata 中将 id 指向 id 字段，number 指向 bill_no，并开启 idCheck: true 与 autoFillResponse: true。轻易云字段映射器会自动展开 contact_*、dispatcher_* 分组，并支持「省/市/区 + 详情地址 → 全地址」合并规则。
4. 明细下钻：在「其他请求」里勾选 detailAPI，把 /jdy/v2/bd/logistics_company_detail 作为明细接口，主表查询后自动按 id 拉取明细。
5. 写入策略：本策略为纯查询，Target 配置为「写入空操作」，通常作为主数据前置任务，依赖它的下游任务（如销售出库单同步）按 depends_on 串行执行。

跨方案实战要点

1. 主键 + 编码双轨制：金蝶侧同时返回 id 和 bill_no，在轻易云里我们坚持「id 做幂等键、bill_no 做业务编码」，避免下游因编码变更导致匹配失败。
2. 地址分组要分别处理：contact_（联系地址）与 dispatcher_（发货地址）结构完全一致但语义不同，绝不能合并到同一个目标字段，否则发货地址会被覆盖。
3. object 字段按需解析：payment_entry、cus_bear_fee_entry、attachments_url、custom_field 都是结构化对象，轻易云支持 JSONPath 提取，但建议先在「响应预览」里看完整结构再写表达式。
4. 增量同步选 modify_time：在多个零售客户项目里，物流公司变更频率低但偶有调整，用 modify_time 做增量过滤比全量扫描稳得多，建议每 5 分钟跑一次。
5. 金额字段统一 BigDecimal：total_amount、all_debt 等都是 string 类型，跨系统传输时务必用 BigDecimal 解析，避免浮点精度差导致对账不平。
6. 拼写兼容：recevice_delivery 是金蝶接口保留的拼写问题，目标侧最好同时兼容 receive_delivery 与 recevice_delivery，防止后续升级被清空。

踩坑复盘

1. page_size 默认 10，导致首次同步漏数据：金蝶默认每页仅 10 条，物流公司超过 10 家就会被分页截断。稳妥做法是在轻易云策略里显式把 page_size 调到 50 或 100，并在分页器里设置最大页数保护。
2. 把 id 当编码同步：直接把金蝶的 id 同步成聚水潭的物流公司编码，后续若金蝶侧重建主键，聚水潭端就找不到对应记录。我们一律用 bill_no 作为业务编码，id 仅做内部幂等。
3. 发货地址被联系地址覆盖：源数据两条地址都叫「address」，映射时容易配错字段。轻易云字段映射器会按 dispatcher_* 前缀明确分组，工程师只需把分组对齐即可。
4. object 字段被当成字符串写入：payment_entry 等 object 类型若原样写入目标，会变成 [object Object]，必须用轻易云的 JSONPath 或脚本节点展开后再映射。
5. 增量字段缺失导致全量重跑：少数客户未启用 modify_time，策略每次都全量。建议在轻易云「字段设置」里把 modify_time 标为「增量字段」，并在过滤器里启用「按修改时间增量」。

何时选用

适合「需要把金蝶云星辰作为物流公司主数据来源，跨系统同步到电商 ERP、零售中台或 WMS」的场景；如果只是单向从金蝶读取发货单物流信息，可直接复用销售出库单接口；若目标侧已是物流公司主数据源，则本接口可省去。