畅捷通T+存货档案查询接口权威教程：从字段映射到轻易云配置全流程

这个接口解决什么问题

在旺店通与畅捷通T+的供应链集成场景里，存货档案（物料主数据）是所有下游单据同步的基石。我们需要把T+端的商品编码、规格、多单位、批次属性等基础资料稳定地拉到中间层，再分发给前端业务系统。该接口正是承担这一"主数据广播"职责的核心入口。

接口能力总览

• 接口地址：/tplus/api/v2/inventory/Query
• 认证方式：畅捷通T+标准OAuth/账套授权，轻易云适配器已封装凭据管理
• 请求方式：POST，JSON Body
• 核心参数：MadeRecordDate（建档日期，增量拉取锚点）、Disabled（是否停用过滤）、PageSize/PageIndex（分页）
• 响应结构：根节点返回存货数组，每条记录含 ID、Code、Name、对象型字段（InventoryClass、Unit、UnitByPurchase 等）
• 分页模式：传统页码分页，建议单页 200 条以内
• 增量模式：以 MadeRecordDate 作为时间锚点，配合轻易云的「末次同步时间」变量（如 {{LAST_SYNC_TIME|date}}）实现准实时增量
• 执行节奏：典型定时任务为 36 3 * * *，凌晨低峰拉取

典型字段映射

在轻易云上如何配置

在轻易云数据集成平台里，这个接口的调用通常采用 T+ 适配器 + 字段映射器的组合：

• 适配器层：选择「畅捷通T+」连接器，填入账套授权信息，平台会自动维护 Token 刷新
• 策略类型：选用「QUERY_ONLY」仅查询模式，Target 端配置「写入空操作」，把数据沉淀到轻易云的中间表
• 增量变量：轻易云的字段映射器会自动把 {{LAST_SYNC_TIME|date}} 注入请求 Body 的 MadeRecordDate 字段，无需手写脚本
• 对象展开：对于 InventoryClass、UnitByPurchase 这类对象型字段，轻易云提供「点路径」语法（如 InventoryClass.Code）直接取值
• 定时调度：在策略的 Cron 配置里设为 36 3 * * *，与上游数据库备份节奏错峰

跨方案实战要点

1. 编码优先于内键：跨系统对照一律使用 Code，ID 仅用于轻易云内部的幂等去重，避免因 T+ 账套迁移导致 ID 变化引发断链。
2. 增量锚点要稳：多个客户项目里，MadeRecordDate 的格式必须显式约定（如 yyyy-MM-dd HH:mm:ss），时区以 T+ 服务器所在时区为准。
3. 多单位按场景取：销售单据同步用 UnitBySale，采购用 UnitByPurchase，库存盘点用 UnitByStock，切勿一律取 BaseUnitCode。
4. 停用档案要过滤：T+ 的停用存货仍会返回，建议在请求参数固定传 Disabled=false，减少下游无效数据。
5. 对象型字段先展开再映射：InventoryClass、ProductInfo 等对象在轻易云里务必用点路径展开，否则下游会收到字符串化的 JSON。
6. 自定义字段透传：priuserdefnvc1~4 在轻易云中可直接映射到目标系统的扩展字段，无需脚本处理。

踩坑复盘

• 坑1：MadeRecordDate 时区漂移。T+ 服务器默认返回的时间可能不带时区，轻易云若用本地时区解析会导致增量漏拉。稳妥的做法是显式指定 T+ 账套所在时区，并在轻易云的时间格式化器里固定偏移。
• 坑2：对象型字段被整块写入。直接把 UnitBySale 拖到目标字段，会把整个对象序列化进去。务必先在轻易云字段映射器里展开为 UnitBySale.Code 与 UnitBySale.Name。
• 坑3：分页越界导致重复。T+ 的 PageIndex 从 1 开始，若按 0 开始传会跳过第一页或重复拉取。轻易云的分页器默认从 1 开始，但若客户改了脚本需复核。
• 坑4：Disabled 字段类型不一致。部分 T+ 版本返回的是布尔，部分返回 "true"/"false" 字符串。在轻易云的类型转换器里统一转成布尔再写入目标。
• 坑5：自定义字段命名漂移。T+ 升级后 priuserdefnvc1 的语义可能被客户二次定义，跨账套复用时务必在轻易云里加一层「字段语义映射表」，不要硬编码。

何时选用

该接口适合需要把畅捷通T+的物料主数据稳定同步到电商WMS或前端业务系统的供应链集成场景。若业务只涉及单据级同步、不需要主数据治理，可直接跳过；若涉及多单位、批次、保质期管理，则该接口是绕不开的基础设施。