列表、分页与导出

开发者文档

列表、分页与导出

游标分页约定、所有列表接口的通用参数，以及用于对账的 CSV 导出。

单笔查询回答"这一笔怎么样了"，列表回答"这段时间发生了什么"。所有列表接口共用同一套约定。

接口	游标字段	CSV 导出
`GET /api/v1/orders`	`trade_no`	✅
`GET /api/v1/refunds`	`refund_no`	✅
`GET /api/v1/disputes`	`dispute_no`	✅
`GET /api/v1/balance_transactions`	`id`	✅
`GET /api/v1/payment_links`	`link_id`	—
`GET /api/v1/events`	`id`	—
`GET /api/v1/logs`	`request_id`	—

它们都按创建时间倒序返回，并且只返回当前密钥所属商户、所属环境的数据。

通用参数

参数	类型	说明
`limit`	integer	每页条数，`1` ~ `100`，默认 `20`
`starting_after`	string	上一页最后一个对象的 id，用于翻到下一页
`ending_before`	string	当前页第一个对象的 id，用于往回翻。不能与 `starting_after` 同时使用
`created[gte]`	timestamp	只返回该时刻之后创建的对象。接受 ISO-8601 或 Unix 秒
`created[lte]`	timestamp	只返回该时刻之前创建的对象
`format`	string	传 `csv` 时返回 CSV 文件而不是 JSON

ℹ️

为什么是游标而不是 page / offset：用 offset 翻页时，如果翻的过程中有新订单产生，后面的数据会整体往后挪一位——你会漏掉一条记录而毫无察觉。游标锚定在具体对象上，新数据不会影响已经翻过的页。

响应结构

{
  "code": 200,
  "message": "success",
  "request_id": "req_9f2c1a7b4e8d0356c1ab77de90f4b215",
  "data": {
    "object": "list",
    "resource": "order",
    "has_more": true,
    "url": "/api/v1/orders",
    "data": [
      { "object": "order", "trade_no": "TRD_A1B2...", "status": "paid" },
      { "object": "order", "trade_no": "TRD_C3D4...", "status": "pending" }
    ]
  }
}

has_more 为 true 说明还有下一页。不要靠"返回条数 < limit"判断结束——那在边界上会多请求一次。

翻完全部数据

async function* allOrders(params = {}) {
  let startingAfter = undefined
 
  while (true) {
    const query = new URLSearchParams({ limit: "100", ...params })
    if (startingAfter) query.set("starting_after", startingAfter)
 
    const res = await fetch(
      `https://web.kukopay.com/api/v1/orders?${query}`,
      { headers: { "X-Api-Key": process.env.KUKOPAY_API_KEY } }
    )
    const { data: page } = await res.json()
 
    for (const order of page.data) yield order
    if (!page.has_more) return
 
    // 游标就是这一页最后一个对象的 trade_no
    startingAfter = page.data[page.data.length - 1].trade_no
  }
}
 
// 拉取昨天所有已支付订单
for await (const order of allOrders({
  status: "paid",
  "created[gte]": "2026-09-20T00:00:00Z",
  "created[lte]": "2026-09-20T23:59:59Z",
})) {
  console.log(order.trade_no, order.net_amount)
}

CSV 导出

传 format=csv 返回带 UTF-8 BOM 的 CSV 文件（Excel 直接打开不会乱码），金额列已换算成两位小数，可以直接求和。

curl -G "https://web.kukopay.com/api/v1/balance_transactions" \
  -H "X-Api-Key: kuko_live_你的密钥" \
  -d format=csv \
  -d "created[gte]=2026-09-01T00:00:00Z" \
  -d "created[lte]=2026-09-30T23:59:59Z" \
  -o 2026-09-对账.csv

限制	说明
单次上限	10,000 行，超出部分不返回
调用频率	10 次 / 分钟，单独计额度
分页参数	导出时 `limit` / `starting_after` 会被忽略，筛选参数照常生效

用 created[gte] / created[lte] 把窗口切小，而不是一次拉完整个历史。

⚠️

商品标题等字段如果以 = + - @ 开头，导出时会自动加一个前导单引号，防止被 Excel 当成公式执行。这是有意为之，不是数据错误。

每日对账建议

每天拉取前一天的资金流水，按 type 分组求和，与自己的账目核对。它比订单列表更适合对账，因为手续费、退款、拒付、提现各记一行，加起来就是余额的变化。

当期余额本身用余额查询拿，两者相互印证。

API 调用日志 metadata

开发者文档

列表、分页与导出

游标分页约定、所有列表接口的通用参数，以及用于对账的 CSV 导出。

单笔查询回答"这一笔怎么样了"，列表回答"这段时间发生了什么"。所有列表接口共用同一套约定。

接口	游标字段	CSV 导出
`GET /api/v1/orders`	`trade_no`	✅
`GET /api/v1/refunds`	`refund_no`	✅
`GET /api/v1/disputes`	`dispute_no`	✅
`GET /api/v1/balance_transactions`	`id`	✅
`GET /api/v1/payment_links`	`link_id`	—
`GET /api/v1/events`	`id`	—
`GET /api/v1/logs`	`request_id`	—

它们都按创建时间倒序返回，并且只返回当前密钥所属商户、所属环境的数据。

通用参数

参数	类型	说明
`limit`	integer	每页条数，`1` ~ `100`，默认 `20`
`starting_after`	string	上一页最后一个对象的 id，用于翻到下一页
`ending_before`	string	当前页第一个对象的 id，用于往回翻。不能与 `starting_after` 同时使用
`created[gte]`	timestamp	只返回该时刻之后创建的对象。接受 ISO-8601 或 Unix 秒
`created[lte]`	timestamp	只返回该时刻之前创建的对象
`format`	string	传 `csv` 时返回 CSV 文件而不是 JSON

ℹ️

响应结构

{
  "code": 200,
  "message": "success",
  "request_id": "req_9f2c1a7b4e8d0356c1ab77de90f4b215",
  "data": {
    "object": "list",
    "resource": "order",
    "has_more": true,
    "url": "/api/v1/orders",
    "data": [
      { "object": "order", "trade_no": "TRD_A1B2...", "status": "paid" },
      { "object": "order", "trade_no": "TRD_C3D4...", "status": "pending" }
    ]
  }
}

has_more 为 true 说明还有下一页。不要靠"返回条数 < limit"判断结束——那在边界上会多请求一次。

翻完全部数据

async function* allOrders(params = {}) {
  let startingAfter = undefined
 
  while (true) {
    const query = new URLSearchParams({ limit: "100", ...params })
    if (startingAfter) query.set("starting_after", startingAfter)
 
    const res = await fetch(
      `https://web.kukopay.com/api/v1/orders?${query}`,
      { headers: { "X-Api-Key": process.env.KUKOPAY_API_KEY } }
    )
    const { data: page } = await res.json()
 
    for (const order of page.data) yield order
    if (!page.has_more) return
 
    // 游标就是这一页最后一个对象的 trade_no
    startingAfter = page.data[page.data.length - 1].trade_no
  }
}
 
// 拉取昨天所有已支付订单
for await (const order of allOrders({
  status: "paid",
  "created[gte]": "2026-09-20T00:00:00Z",
  "created[lte]": "2026-09-20T23:59:59Z",
})) {
  console.log(order.trade_no, order.net_amount)
}

CSV 导出

传 format=csv 返回带 UTF-8 BOM 的 CSV 文件（Excel 直接打开不会乱码），金额列已换算成两位小数，可以直接求和。

curl -G "https://web.kukopay.com/api/v1/balance_transactions" \
  -H "X-Api-Key: kuko_live_你的密钥" \
  -d format=csv \
  -d "created[gte]=2026-09-01T00:00:00Z" \
  -d "created[lte]=2026-09-30T23:59:59Z" \
  -o 2026-09-对账.csv

限制	说明
单次上限	10,000 行，超出部分不返回
调用频率	10 次 / 分钟，单独计额度
分页参数	导出时 `limit` / `starting_after` 会被忽略，筛选参数照常生效

用 created[gte] / created[lte] 把窗口切小，而不是一次拉完整个历史。

⚠️

商品标题等字段如果以 = + - @ 开头，导出时会自动加一个前导单引号，防止被 Excel 当成公式执行。这是有意为之，不是数据错误。

每日对账建议

当期余额本身用余额查询拿，两者相互印证。

API 调用日志 metadata