吉客云组装拆卸出库查询接口字段手册权威教程(对接用友NCC形态转换单)

这个接口解决什么问题

在吉客云与用友NCC的供应链集成场景里,组装拆卸业务会同时产生「组装拆卸单」与「组装拆卸出库单」两条数据流。后者用于把成品与原料的形态转换、库存变化、批次与成本信息实时同步到用友NCC的形态转换单。本接口(erp.storage.goodsdocout.v2)正是为此而生的增量查询通道,固定出库类型 inouttype=207,按创建时间窗口拉取单据与明细。

接口能力总览

• 认证方式:吉客云开放平台 AppKey/AppSecret 签名鉴权,Header 透传;在轻易云里通过「吉客云适配器」统一封装,无需手写签名。
• 请求结构:POST 形式,Body 携带 startDate、endDate、inouttype=207、pageIndex、pageSize 与可选过滤项(goodsDocNo、warehouseCode、outBillNo、billNo)。
• 响应结构:JSON,顶层为 data.list(主表数组)与 data.hasMore;每条主表带 goodsDocDetailList 明细行数组。
• 分页/增量模式:pageIndex 从 0 起、pageSize 建议 50;startDate 默认取上次同步时间({{LAST_SYNC_TIME}}),endDate 取当前时间,实现按创建时间的滚动增量。
• 频率参考:定时任务 1-59/3 6-23 * * *,每日 6–23 点每 3 分钟一轮。

典型字段映射

在轻易云上如何配置

1. 适配器选型:数据源选「吉客云」,接口动作选 erp.storage.goodsdocout.v2 出库查询。
2. 参数固化:在轻易云的请求参数区把 inouttype 默认值固定为 207;startDate/endDate 直接绑定内置变量 {{LAST_SYNC_TIME}} 与 {{CURRENT_TIME}}。
3. 字段映射:目标侧选「写入空操作」(本策略为纯查询),但仍建议在字段映射器里把 recId、goodsdocNo、gmtCreate 落到一张中间表,供下游「组装拆卸出库 → 用友形态转换单」写入策略复用。
4. 分页与限流:轻易云的吉客云适配器内置 pageSize=50、hasMore 翻页逻辑,无需写循环;高频调用时可在「调度策略」里把每 3 分钟一轮作为基线。
5. 错误重试:网络抖动或限流时,轻易云会自动按指数退避重试,失败单据进入「待处理队列」可人工补拉。

跨方案实战要点

1. 出库类型必须硬编码:207 之外的单据不要混进本通道,否则下游形态转换单会接收到销售出库、调拨出库等脏数据。
2. 以 goodsdocNo 做业务键、以 recId 做技术键:双键策略在跨系统对账与幂等写入时最稳。
3. 增量游标用 gmtCreate 而非 inOutDate:业务日期可被反审修改,创建时间一旦落库便不再变化。
4. 批次与有效期是组装拆卸的关键:原料的 batchNo、成品的 productionDate/expirationDate/shelfLife 都要原样透传到 NCC。
5. 成本字段看 financeBillStatus:21/25 之前不要拿 transHasTaxAmount 做总账,容易出现成本反复变更。
6. 明细行单独建唯一索引:主表recId + 明细recId 组合主键,避免重复行覆盖。

踩坑复盘

• 坑1:把 inouttype 写成「207-组装拆卸出库」中文。吉客云要求纯数字编码,传中文会直接返回空集。
• 坑2:忽略 redStatus=9 的红冲单。红冲单若不过滤,下游会出现「成本为负」「库存虚减」的诡异现象,稳妥的做法是在轻易云过滤器里加 redStatus != 9。
• 坑3:startDate 用业务日期而非创建时间。结果反审单据后增量窗口错位,大量漏单。
• 坑4:pageSize 调到 200 以上被限流。吉客云默认上限 50,超过会 429;轻易云适配器默认就是 50,这里别手抖改大。
• 坑5:明细行的 estCost 与 transHasTaxAmount 同时写下游。两套口径打架,后续对账极痛苦,务必按财务状态择一。

何时选用

本接口适用于吉客云侧组装拆卸业务的出库数据需要增量同步到用友NCC形态转换单、或需要把批次、有效期、成本、税额等信息透传到下游 ERP/MES 的场景。若只需总账汇总或仅做看板展示,建议改用现存量查询接口,本接口的明细粒度会带来不必要的性能开销。