这个接口解决什么问题

聚水潭销售出库单是电商供应链里出货与对账的事实表。通过非奇门简单版接口把出库单批量同步到本地 SQL Server 表,企业可以做发货状态追踪、物流信息归集、财务对账,以及与自有 ERP 系统的数据打通。本质上,它把线上分散的出库行为沉淀成结构化的、可追溯的本地数据资产。

接口能力总览

认证方式:聚水潭开放平台 OAuth/AppKey 签名方式,请求头携带授权凭证。
请求路径:/open/orders/out/simple/query(非奇门简单版)。
请求方法:HTTP POST,Body 为 JSON。
关键请求参数:page_index(默认 1)、page_size(默认 100,API 上限 25)、modified_begin/modified_end(按修改时间增量,间隔不超过 7 天)、date_type(0=修改时间,2=出库时间)、status(WaitConfirm/Confirmed/Cancelled)。
响应结构:外层 code 标识错误码;datas.orders 是出库单数组,每条订单包含主表字段与 items/batchs/sns 三个嵌套集合。
分页模式:基于 page_index 的页码翻页,逐页拉取直至空页。
增量模式:按修改时间或出库时间窗口增量,时间窗必须 ≤7 天,否则接口会拒绝返回。

字段名	类型	含义	实战注意事项
io_id	int	出库单号,主键	增量去重与主表主键的最终落点
o_id	int	内部单号	与聚水潭订单主数据关联
so_id	string	线上单号	与电商平台订单对账
outer_oi_id	string	子订单号	拆合单场景的溯源锚点,最长 50 字符
co_id / wms_co_id	string	公司/分仓编号	多仓场景路由关键
shop_id / shop_name	string	店铺编号/名称	多店铺区分
io_date / created	datetime	出库时间/创建时间	增量按 `date_type=2` 时主用 `io_date`
pay_amount / paid_amount / freight	float	应付/实付/运费	三者必须区分,别混
receiver_address	string	完整收货地址	简单版只返回合并地址,无省市区
l_id	string	物流单号	发货追踪
items	array	商品明细	落表时需展平为 `items_*` 扁平字段
batchs / sns	array	批次/唯一码	序列号管理商品必须用
code	string	错误码	用于流控与重试判断

在轻易云数据集成平台里,这个接口的调用通常被封装成「聚水潭销售出库单查询」适配器。我们建议的搭建路径是:

数据源连接:新建聚水潭数据源,填入 AppKey/Secret,完成授权。
适配器选择:在源系统组件里选择「销售出库单(非奇门·简单版)」适配器,平台已预置请求参数模板。
字段映射器:平台会预生成主表与 items 嵌套集合的扁平映射模板;字段映射器会自动把 items 数组展开为 items_oi_id、items_sku_id、items_qty、items_sale_price 等列,无需手写遍历逻辑。
增量策略:配置 date_type=2、status=Confirmed,时间窗默认按出库时间滚动 7 天切片;轻易云会帮你管理游标与翻页,直至空页自动停。
目标写入:对接 SQL Server,平台自动生成批量插入 SQL(batchexecute),主键使用 io_id,明细通过 items_* 系列字段写入。
调度:crontab 设置 1 0,1,2 * * *,即每日 0、1、2 点增量拉取,覆盖跨日边界。

从多个客户项目里沉淀出的共性经验,以下几条基本通用:

时间窗硬约束:聚水潭规定 modified_begin 与 modified_end 间隔不能超过 7 天,稳妥的做法是按出库时间(date_type=2)切片,每天滚动一次,避免因调度延迟导致跨窗。
状态过滤前置:默认拉取 Confirmed(已出库)状态数据,「待出库」与「作废」单独走分支查询,避免单次返回数据被作废单污染。
items 必须展平:聚水潭的明细在嵌套数组里,SQL Server 是关系表,落库前必须把 items 数组展平为 items_* 字段,并以 io_id 作为外键关联主表。
主键与去重双保险:主键用 io_id,增量去重建议用 {{o_id}}{{modified}} 组合 ID,防止极端情况下主键为空或重复。
地址字段缺失处理:简单版不返回省市区分级结构,目标表里的 receiver_country/state/city/district 字段需要从其他接口或地址解析逻辑补充,不要简单留空。
翻页上限注意:官方 page_size 上限 25,配置成 100 会被截断,这里容易翻车,务必按上限调小。

跨 7 天时间窗被拒:某客户把增量脚本部署成每周跑一次,接口直接返回空数据并报错。改成每日切片后问题消失。
items 嵌套没展平导致明细丢失:第一版直接把整段 JSON 塞进 SQL Server,前端查不到任何商品行;展平为 items_* 系列字段后明细才出现。
page_size=100 被静默截断:某客户配置 100 实际只返回 25 条,误以为上游已无数据,改为 25 后才完整拉取。
奇门版与简单版混用:两个版本字段集不一致(简单版没有 modified、status 等响应字段,奇门版有),同一映射模板两边用必出错,务必按版本选模板。
作废单混入对账:不筛 status 时作废单也会被同步,导致财务对账金额虚高。增加 status=Confirmed 过滤后金额对齐。

当业务方需要把聚水潭销售出库数据本地化、做发货追踪或与自有 ERP/SQL Server 对账时,这个接口是首选;若需要更细的省市区地址、批次/序列号明细,建议叠加奇门版或其他明细接口;对于纯电商前端展示,直接调用聚水潭前端 API 即可,不必落库。