Decathlon OMS Finance · External API Spec
EXP 渠道账单流水分页查询
GET /open/channel-bill/collect/exp/page/v1
v1.22026-10-21 签发
只读 · 幂等 · 无副作用 Query 参数 · 无请求体 offset 页码分页 统一信封 code(string) 经 Apiportal 网关
01

接口概述

Overview

用于按指定店铺、指定月份分页拉取渠道账单公共表（channel_bill_collect）中 EXP 类资金流水记录。

查询维度单店铺 + 单月份。store_number 必填，不支持全店铺拉取；month 指定唯一月份（yyyy-MM）。
数据范围仅透出当前有效的 EXP 账务类型记录。EXP 集合由 so_reconciliations_config（ica 以 4/6 开头）与全量有效迪卡侬账务类型共同确定；bank/对账等非 EXP 类型、null 与已下线的历史类型不在范围内。
响应结构统一信封 + data 内为标准分页结构；流水明细位于 data.content[]，仅透出 id/out_order_code/income_amount/expenditure_amount/dkn_bill_type/bill_date。id 为唯一去重依据（同一 out_order_code 可能存在多条流水）。
月结确认下线本接口不再返回 confirm_status，下游不能从该接口获取月结确认信号。
接口语义只读、无副作用，失败可安全重试。
02

接口调用

Endpoint
项值
接口路径（网关）GET /open/channel-bill/collect/exp/page/v1
内网调试路径GET /finance/channelBill/exp/page/v1
协议 / 认证HTTPS，Apiportal 统一终止 TLS；网关鉴权（appId + 签名/密钥），应用侧不提供直连
参数位置全部为 URL Query 参数（无请求体）
限流网关侧按 appId 限流，配额以网关配置为准
03

请求参数（Query）

Request Parameters
字段类型必填默认约束 / 说明
store_numberstring(64)是-店铺编号（internal_platform_code，如 50-46-46）；必填，不支持全店铺
monthstring是-查询月份，格式 yyyy-MM（如 2026-10）；仅查询该店铺该月数据
pageint是规范默认 0页码，从 0 起
sizeint是规范默认 10每页条数，范围 [1, 500]
sortstring否sync_bill_date,asc排序，可重复多值；单值格式 属性,asc|desc（方向可省略，默认 asc）

sort 可用属性（白名单，未收录属性返回 "9000"）：

sync_bill_date bill_date out_order_code income_amount expenditure_amount dkn_bill_type id + id ASC（服务端恒定末位兜底）
服务端恒定追加 id ASC 末位兜底排序（用户显式指定 id 时不重复追加），保证同页重复请求结果序列稳定。
请求示例 · 首页
GET /open/channel-bill/collect/exp/page/v1?store_number=50-46-46&month=2026-10&page=0&size=10
请求示例 · 翻页 + 自定义排序
GET /open/channel-bill/collect/exp/page/v1?store_number=50-46-46&month=2026-10&page=2&size=100&sort=bill_date,desc&sort=id,desc
04

响应参数

Response Schema

顶层结构（统一信封）：

字段类型说明
codestring执行 code（报错时必有）；正常固定 "0"
errorstring报错信息概要（报错时必有）
error_descriptionstring报错信息详情（非必须，有更好）
error_linkstringurl 地址，指向文档解释如何解决该错误（非必须）
dataobject实际返回数据，见下表

data 对象（标准分页结构 + 店铺回显附加字段）：

字段类型说明
contentarray<object>当前页流水记录列表；无数据时为 []
pageableobject分页与排序信息，见 05
total_elementsint(long)总数据量（该店铺该月 EXP 流水总数）
total_pagesint(long)总页数；总数为 0 时为 0
lastboolean是否最后一页（请求越界页时为 true）
firstboolean是否第一页
sortobject排序标志位 {unsorted, sorted, empty}（同 pageable.sort）
sizeint(long)本次请求页大小
numberint(long)当前页码（从 0 起）
number_of_elementsint本页实际条数（可小于 size）
emptyboolean本页数据是否为空
store_numberstring(64)店铺编号，请求参数回显（schema 之外声明的附加字段）
store_namestring店铺名称；未映射店铺时为 null（schema 之外声明的附加字段）

content[] 记录字段：

字段类型说明
idint(bigint)唯一主键（channel_bill_collect.id，雪花 ID）；下游去重唯一依据
out_order_codestring渠道订单号；部分非订单交易相关费项记录可能为空
income_amountnumber(10,2)收入金额（元）；无收入为 0
expenditure_amountnumber(10,2)支出金额（元）；支出为负值（如 -12.88），无支出为 0.00
dkn_bill_typestring迪卡侬账务类型名称（如 预付款-聚划算佣金）
bill_datestring账务发生时间，格式 yyyy-MM-dd HH:mm:ss
响应示例 · success（HTTP 200）
{
  "code": "0",
  "data": {
    "content": [
      {
        "id": 9012350,
        "out_order_code": "999001",
        "income_amount": 1,
        "expenditure_amount": 0,
        "dkn_bill_type": "预付款-聚划算佣金",
        "bill_date": "2026-10-31 09:12:03"
      }
    ],
    "pageable": {
      "sort": { "unsorted": false, "sorted": true, "empty": false },
      "page_size": 10,
      "page_number": 0,
      "offset": 0,
      "unpaged": false,
      "paged": true
    },
    "total_elements": 35,
    "total_pages": 4,
    "last": false,
    "first": true,
    "sort": { "unsorted": false, "sorted": true, "empty": false },
    "size": 10,
    "number": 0,
    "number_of_elements": 10,
    "empty": false,
    "store_number": "50-46-46",
    "store_name": "迪卡侬DTC官网"
  }
}
响应示例 · 店铺不存在（HTTP 200 + code"40003"）
{
  "code": "40003",
  "error": "store_number not found"
}
响应示例 · 参数非法（HTTP 400 + code"9000"）
{
  "code": "9000",
  "error": "invalid request parameter",
  "error_description": "月份格式必须为yyyy-MM"
}
05

分页说明

Pagination

offset 页码分页（v1.2 起，替代 keyset 游标）：

  1. 首页：page=0；翻页：page 依次 +1。
  2. GET 幂等，任意跳页合法；请求越界页（page ≥ total_pages 且 total_pages > 0）返回空 content 且不计入数据查询。
  3. pageable 字段：page_size 本次请求页大小；page_number 当前页码（0 起）；offset = page * size（SQL 偏移量，展示用途）；sort 排序标志位；unpaged=false/paged=true 为固定值。
  4. 违规 sort（属性不在白名单 / 方向非 asc|desc）返回 "9000"，SQL 不受影响。
不再承诺「不重不漏」：offset 分页在服务端快照基础上，若查询期间月份内有新流水写入，排序键相同时可能出现跨页重/漏。业务上以 content[].id 去重兜底，并建议在数据相对稳定（如出账后）时拉取。
06

错误码表

Error Codes
codeHTTP 状态含义调用方处理
"0"200成功—
"9000"400参数缺失/非法（store_number/month/page/size 缺失或越界、month 非 yyyy-MM）；sort 非法亦返回该码（HTTP 200）检查请求
"40003"200store_number 无法映射到店铺核对店铺编号
"50001"200系统内部错误退避重试
"50002"200数据查询超时退避重试（重试安全）
原 "40004"（cursor 非法/失效）随游标机制一并下线。
07

调用规约

Calling Conventions
  1. 拉取全量：按「店铺 + 月份」调用，从 page=0 开始循环，直到 last=true；每页 page+1。可用 total_elements/total_pages 预计算页数。
  2. 维度固定：store_number、month 必填（yyyy-MM）；一次请求只返回该店铺该月数据，无需再按日期区间拆分。翻页时其余请求参数应保持不变。
  3. 并发拉取：offset 分页支持任意跳页，但同一店铺同一月份并发拉取在数据写入期可能出现跨页重/漏；如需并行，请按不同店铺或不同月份拆分。
  4. 幂等去重：以 content[].id 作为唯一去重键。同一 out_order_code 可能存在多条有效流水，禁止用 out_order_code 去重；如需按业务键合并，请先按 id 去重后再聚合。
  5. 失败重试：接口只读，失败可安全重试；参数/业务校验错误（9000/40003）修复参数后再试，服务类错误（5xxxx）退避重试。
08

版本记录

Changelog
v1.22026-10-21

契约变更：新路径 GET /open/channel-bill/collect/exp/page/v1（与旧 POST /exp/page 并行）；HTTP 方法改 GET、参数移至 Query；游标分页 → 页码分页（page/size/sort）；响应改统一信封 + 标准分页结构；confirm_status 字段及月结确认语义下线；明细字段不变。

v1.12026-10-14

需求变更：查询维度改为「指定店铺 + 指定月份」；store_number 必填、不支持全店铺；sync_bill_date_start/end → month；响应 data 改对象并新增 confirm_status/store_name；明细字段 biz_code→out_order_code、dkn_bill_type 取名称、bill_date 改取账务发生时间。

v1.02026-10-13

对外版：由 channel-bill-exp-api-tech-design.md 提炼。