Phân trang

Mọi endpoint trả danh sách dùng phân trang theo con trỏ. Cách này ổn định khi dữ liệu thay đổi giữa các lần gọi và nhanh với danh sách lớn.

Tham số

Tham số	Ý nghĩa
limit	Số phần tử mỗi trang, từ 1 đến 200. Mặc định 50.
cursor	Con trỏ của trang kế tiếp, lấy từ next_cursor của phản hồi trước. Bỏ trống để lấy trang đầu.

Phản hồi

{
  "data": [],
  "next_cursor": "eyJ2IjoxfQ"
}

• data: mảng phần tử của trang hiện tại.
• next_cursor: chuỗi con trỏ của trang kế tiếp, hoặc null khi đã hết dữ liệu.

next_cursor là chuỗi mờ (opaque): chỉ truyền lại nguyên văn, đừng phân tích hay tự dựng. Định dạng bên trong có thể thay đổi.

Lấy toàn bộ dữ liệu

async function listAll(path, params = {}) {
  const items = [];
  let cursor = null;
  do {
    const url = new URL(`https://api.hoadon.pro${path}`);
    for (const [key, value] of Object.entries({ limit: 200, ...params })) {
      url.searchParams.set(key, String(value));
    }
    if (cursor) url.searchParams.set('cursor', cursor);

    const res = await fetch(url, {
      headers: { Authorization: `Bearer ${process.env.HOADON_API_KEY}` },
    });
    if (!res.ok) throw new Error(`HTTP ${res.status}`);

    const page = await res.json();
    items.push(...page.data);
    cursor = page.next_cursor;
  } while (cursor);
  return items;
}

Đếm tổng số

Phản hồi danh sách không kèm tổng số phần tử. Khi cần số lượng (ví dụ để hiển thị tiến độ), dùng endpoint thống kê riêng của từng tài nguyên (đường dẫn kết thúc bằng /stats), tra cứu ở Scalar.

Lưu ý

• Con trỏ gắn với bộ lọc của yêu cầu đã tạo ra nó: giữ nguyên các tham số lọc khi truyền cursor.
• Nên lấy limit lớn (tối đa 200) khi đồng bộ hàng loạt để giảm số yêu cầu, nhưng vẫn tôn trọng giới hạn tốc độ.