Paginasi

Endpoint daftar mengembalikan data per halaman, terbaru dulu. Untuk halaman berikutnya, kirim nextCursor dari respons sebelumnya sebagai parameter cursor.

Bentuk respons daftar

Semua respons daftar punya bentuk yang sama:

{
  "data": [],
  "hasMore": true,
  "nextCursor": "WzE3OTE3NjMzMzAwMDAsIjY3MDkxYzJhIl0"
}

Field	Artinya
data	Isi halaman ini.
hasMore	true bila masih ada data setelah halaman ini.
nextCursor	Nilai untuk parameter cursor di permintaan berikutnya. null di halaman terakhir.

Daftar tidak menyertakan jumlah total data. Lanjutkan ke halaman berikutnya selama hasMore bernilai true.

Perlakukan nextCursor sebagai teks apa adanya. Jangan mengurai atau membuatnya sendiri, karena isinya bisa berubah.

Parameter

Parameter	Keterangan
limit	Jumlah data per halaman, bilangan bulat 1 sampai 100. Default 20.
cursor	nextCursor dari halaman sebelumnya. Kosongkan untuk halaman pertama.

Cursor yang rusak atau dibuat sendiri ditolak dengan 400 invalid_request. limit di luar 1 sampai 100 ditolak dengan 422 validation_error.

Endpoint yang memakai cursor

Endpoint	Urutan	Filter
GET /v1/shipments	Terbaru dulu, berdasarkan waktu dibuat	status (satu atau beberapa, dipisah koma), awb, externalRef, createdFrom, createdTo
GET /v1/wallet/transactions	Terbaru dulu, berdasarkan waktu mutasi	type, createdFrom, createdTo

createdFrom bersifat inklusif dan createdTo eksklusif, keduanya dalam format ISO 8601, misalnya 2026-10-01T00:00:00+07:00.

GET /v1/locations dan GET /v1/couriers memakai bentuk respons yang sama, tetapi nextCursor selalu null. Untuk lokasi, atur jumlah hasil dengan limit 1 sampai 50 dan persempit kata kunci bila hasMore bernilai true.

Mengambil semua halaman

Kirim filter yang sama di setiap halaman. Cursor menyimpan posisi, bukan filter, jadi mengganti filter di tengah jalan memberi hasil yang tidak konsisten.

# Halaman pertama: pengiriman terkirim sejak 1 Oktober 2026
curl "https://api.ongkirhub.com/v1/shipments?status=delivered&createdFrom=2026-10-01T00:00:00%2B07:00&limit=100" \
  -H "Authorization: Bearer ohk_test_xxx"

# Halaman berikutnya: filter sama, ditambah cursor
curl "https://api.ongkirhub.com/v1/shipments?status=delivered&createdFrom=2026-10-01T00:00:00%2B07:00&limit=100&cursor=NEXT_CURSOR" \
  -H "Authorization: Bearer ohk_test_xxx"

Tanda + di zona waktu perlu ditulis %2B di URL.

Contoh dalam JavaScript (Node.js 18 atau lebih baru):

async function semuaPengiriman(params) {
  const hasil = [];
  let cursor = null;
  do {
    const query = new URLSearchParams({ ...params, limit: "100" });
    if (cursor) query.set("cursor", cursor);
    const res = await fetch(`https://api.ongkirhub.com/v1/shipments?${query}`, {
      headers: { Authorization: `Bearer ${process.env.ONGKIRHUB_API_KEY}` },
    });
    if (!res.ok) throw new Error(`Gagal: ${res.status}`);
    const page = await res.json();
    hasil.push(...page.data);
    cursor = page.nextCursor;
  } while (cursor);
  return hasil;
}

Setiap halaman dihitung sebagai satu permintaan terhadap batas permintaan. Untuk sinkronisasi rutin, pakai filter createdFrom atau terima perubahan lewat webhook daripada membaca ulang semua data.