列表、分頁與導出

KukoPay 列表接口的游標分頁約定：limit、starting_after 與 ending_before 等通用參數、響應結構、如何翻完全部數據，以及用於每日對賬的 CSV 導出。

單筆查詢回答"這一筆怎麼樣了"，列表回答"這段時間發生了什麼"。所有列表接口共用同一套約定。

接口	游標字段	CSV 導出
`GET /v1/orders`	`trade_no`	支持
`GET /v1/refunds`	`refund_no`	支持
`GET /v1/disputes`	`dispute_no`	支持
`GET /v1/balance_transactions`	`id`	支持
`GET /v1/payment_links`	`link_id`	—
`GET /v1/events`	`id`	—
`GET /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": "/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://api.kukopay.com/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://api.kukopay.com/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 分組求和，與自己的賬目核對。它比訂單列表更適合對賬，因為手續費、退款、拒付、提現各記一行，加起來就是餘額的變化。

當期餘額本身用餘額查詢拿，兩者相互印證。

單筆查詢回答"這一筆怎麼樣了"，列表回答"這段時間發生了什麼"。所有列表接口共用同一套約定。

接口	游標字段	CSV 導出
`GET /v1/orders`	`trade_no`	支持
`GET /v1/refunds`	`refund_no`	支持
`GET /v1/disputes`	`dispute_no`	支持
`GET /v1/balance_transactions`	`id`	支持
`GET /v1/payment_links`	`link_id`	—
`GET /v1/events`	`id`	—
`GET /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": "/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://api.kukopay.com/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://api.kukopay.com/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 參考

接口約定

通用參數

響應結構

翻完全部數據

CSV 導出

每日對賬建議

開始

插件與集成

對接指南

資金

API 參考

接口約定

列表、分頁與導出

通用參數

響應結構

翻完全部數據

CSV 導出

每日對賬建議