这个接口解决什么问题

小满OKKICRM的/v1/invoices/order/list接口用于按时间窗口与多条件过滤,批量拉取销售订单主数据及行项目明细。在我们接触的多个客户方案里,典型用途是把CRM侧的销售订单同步到ERP(如吉客云),实现订单状态、金额、客户与产品明细的统一对账。该接口支持增量查询、状态过滤与详情补全,是销售订单域最常用的入口接口之一。

接口能力总览

认证方式:采用小满OKKICRM标准的Access Token鉴权,请求头中携带Authorization: Bearer {token},token需提前通过授权接口获取并定时刷新。
请求结构:POST /v1/invoices/order/list,表单/JSON体传参,核心参数含start_time、end_time、start_index(页码,默认1)、count(每页,默认10)、status(状态过滤,半角逗号分隔)、approval(0/1)、removed(0/1)。
响应结构:返回JSON对象,核心字段为data(订单数组)、total(总记录数)、total_page(总页数)。每条订单记录包含订单主信息及product_list行项目。
分页与增量模式:基于start_time/end_time+页码start_index的双层增量机制。在多个客户项目里,稳妥的做法是把start_time绑定到{{LAST_SYNC_TIME}},end_time取当前时间,每5分钟执行一次(crontab: */5 7-22 * * *),既保证时效又避免遗漏。
详情补全:当列表接口返回的product_list为空或不完整时,可调用详情接口/v1/invoices/order/info,以order_id为主键(info_key)二次拉取完整数据。

典型字段映射

字段名	类型	含义	实战注意事项
order_id	string	订单主键,小满内唯一	作为详情接口主键传参,务必做空值校验
order_no	string	订单业务编码	用于跨系统订单去重与对账
name	string	订单名称	用于单据展示,可能含中文与符号
amount	float	订单总金额	注意币种与汇率换算
addition_cost_amount	float	附加费用合计	运费、税费,不含产品金额
product_total_amount	float	产品金额合计	与`amount`差额即附加费用
product_total_count	float	产品总数量	用于订单规模判断
company_name	string	客户公司名称	扁平化字段,优先使用
company_phone	string	客户电话	优先使用扁平化字段
company_address	string	客户地址	与`company`对象可能重复
customer_name	string	联系人姓名	区别于公司名称
customer_phone	string	联系人电话	区别于公司电话
customer_email	string	联系人邮箱	可为空,需做好空值处理
transport_mode	string	运输方式	用于物流环节衔接
account_date	datetime	结单日期	用于订单生命周期分析
product_list	array	订单行项目	列表接口可能为空,需走详情补全
users_info	object	业绩归属人	销售业绩统计依据
handler_info	object	订单跟进人	用于CRM归属判定
status_info	object	订单状态	含状态码与名称
exchange_rate	string	汇率	多币种场景必备

在轻易云上如何配置

在轻易云数据集成平台里,这个接口通常以「查询适配器」的形式封装。我们配置过多个客户方案,总结出三条关键经验:

适配器注册:在轻易云的「源系统」中选择小满OKKICRM,填写/v1/invoices/order/list作为入口路径,配置token鉴权与刷新策略。轻易云的认证管理器会自动处理token过期重试。
字段映射器:平台字段映射器会自动把order_id、order_no、amount等核心字段映射到轻易云的统一概念模型(如order_id、order_no、order_amount),下游目标系统(吉客云)可直接引用,无需重复定义。
增量策略:在轻易云的「调度策略」中配置crontab为*/5 7-22 * * *,把start_time绑定到轻易云的{{LAST_SYNC_TIME}}变量,end_time取{{CURRENT_TIME}},平台会持久化最后一次同步时间戳,断点续传无需人工干预。

此外,当product_list为空时,可在轻易云的「数据加工」节点配置详情补全规则,自动调用/v1/invoices/order/info按order_id补齐行项目,避免下游数据缺失。

跨方案实战要点

从我们做过的多个客户方案里,以下六条共性经验值得重点关注:

增量时间窗口必须保守:start_time比end_time早1-2分钟,避免因服务器时钟差导致漏单;end_time不能取未来时间,否则部分订单会被排除。
分页上限与性能平衡:count建议设为50-100,既能提升单次拉取效率,又不会触发接口限流;总页数超过50时,务必做并发分片。
列表与详情双接口配合:列表接口的product_list经常为空或字段精简,真实场景中必须配置详情补全,否则下游订单行项目会大量缺失。
空操作Target的特殊处理:本策略Target配置为「写入空操作」,属于纯查询策略,通常作为下游写入策略的「数据准备」阶段,必须在依赖关系中排在前面。
状态过滤的语义陷阱:status=0表示「不按状态过滤」,而非「查询状态为0的订单」,这里容易翻车,稳妥的做法是显式传入需要的多个状态值。
扁平化字段优先于对象字段:company_name、customer_phone等扁平化字段在小满接口中已经做了展平,直接使用即可,无需再解析company/customer对象,能显著降低映射复杂度。

踩坑复盘

漏单问题:某零售企业上线初期,因start_time直接取上次同步完成时间,未考虑小满服务器时钟比本地快约30秒,导致每天漏掉约10笔订单。修复方案是把start_time往前回拨2分钟,并加告警监控。
product_list为空:多个客户都遇到过列表接口返回的product_list为[],导致下游订单行项目数量为0。我们通过配置详情补全节点,按order_id调用/v1/invoices/order/info拉取完整行项目后才彻底解决。
token过期无感知:小满token有效期较短,某方案未配置自动刷新,运行数小时后所有接口调用401。轻易云的认证管理器默认开启token自动刷新与重试,建议在适配器中明确启用。
状态过滤反义:工程师把status=0理解为「查询草稿状态订单」,实际是「不过滤状态」。结果返回了全量订单,触发下游重复写入。后改为显式传入status=2,3才正确。
币种与汇率换算错误:多币种场景下,直接把amount累加,未乘以exchange_rate,导致订单总金额偏差。修复后,在轻易云字段映射器中加入汇率换算节点,统一折算为人民币。

何时选用

该接口适用于CRM与ERP之间的销售订单主数据同步、订单状态与金额对账、行项目明细补全等场景。不适用于需要实时下单(应使用订单创建接口)或大文件附件传输(应走独立附件接口)的场景。当业务以「T+1批量对账」或「近实时增量同步」为主时,本接口是首选入口。

查询小满销售订单接口字段手册权威教程