Panduan

Pagination & konvensi

Aturan bersama untuk list, timestamp, nilai uang, dan identifier.

Cursor pagination

Endpoint list mengembalikan satu halaman beserta cursor ke halaman berikutnya.

Query parameter	Arti
`cursor`	String opaque dari pageInfo.nextCursor halaman sebelumnya. Kosongkan untuk halaman pertama.
`limit`	Ukuran halaman, 1 sampai 200. Default 50.

Bentuk response

{
  "items": [
    "…"
  ],
  "pageInfo": {
    "nextCursor": "eyJ0Ijoi…",
    "hasMore": true
  }
}

Terus kirim request dengan cursor=pageInfo.nextCursor selama pageInfo.hasMore bernilai true. Di halaman terakhir, nextCursor bernilai null.
Perlakukan cursor sebagai opaque: jangan di-parse, disusun sendiri, atau disimpan lama. Jangan ubah filter lain di antara halaman.
Beberapa list kecil (toko, label, gudang) dikembalikan utuh tanpa pageInfo; referensi menampilkan setiap response.

Timestamp

Timestamp berupa string ISO 8601 dalam UTC, misalnya 2026-11-04T08:00:00.000Z. Kirim filter seperti from dan to dengan format yang sama (dengan Z atau offset eksplisit seperti +07:00). Waktu Indonesia Barat (WIB) adalah UTC+7. Field khusus tanggal memakai YYYY-MM-DD.

Nilai uang

Nominal berupa string desimal dengan tepat dua digit pecahan, misalnya "189000.00", tidak pernah float. Mata uangnya ada di field saudara currency dan bernilai IDR untuk toko Indonesia. Parse dengan tipe desimal (BigInt dalam sen, decimal.Decimal), bukan binary floating point.

Identifier

Jenis	Contoh	Arti
Id TheComNet	`0192f0c4-8d1e-7a4b-…`	UUID (field bernama id, orderId, storeId, itemId, …). Stabil; pakai ini di path API.
Id eksternal	`578123456789012345`	Field berawalan external (externalOrderId, externalReturnId, externalProductId, externalSkuId, …) adalah id milik marketplace, seperti yang tampil di TikTok Shop atau Shopee Seller Center. Hanya unik bila digabung dengan toko atau marketplace.

marketplace bernilai salah satu dari tiktok, shopee, lazada, tokopedia. Pakai id eksternal untuk mencocokkan data dengan ekspor marketplace dan tiket support; pakai id TheComNet untuk hal lainnya.

Null dan field yang tidak dikenal

Field yang tercantum wajib selalu ada; field nullable bisa bernilai null. Field opsional bisa tidak ada.
Field baru dan nilai enum baru bisa muncul tanpa perubahan versi. Abaikan field yang tidak dikenal dan tangani nilai enum yang tidak dikenal.
Parameter dan body divalidasi terhadap kontrak; input yang tidak valid dijawab 400 VALIDATION_FAILED beserta error per field (lihat Error).