Dokumentasi API

Dapatkan akses API

1. Minta tim dukungan membukakan akun untuk Anda.
2. Kirim ke tim dukungan layanan yang Anda butuhkan, akun Anda, dan IP keluar (egress) server Anda.
3. Kami kemudian menerbitkan kunci API dan panduan integrasi lengkap. Kunci berlaku 1–730 hari, dan setiap kunci mengizinkan hingga 32 IP keluar.

Dasar

Autentikasi

Kirim Authorization: Bearer <kunci API> di setiap permintaan

User-Agent

Wajib. Permintaan tanpa User-Agent diblokir Cloudflare (error 1010)

Format

Permintaan dan respons JSON dalam UTF-8, kecuali unggahan berkas

Waktu

Timestamp Unix UTC dalam milidetik

Nominal

Hingga delapan angka desimal. Gunakan tipe desimal dan jangan dibulatkan menjadi dua angka

Alur integrasi

1. Tampilkan daftar layanan dan cek saldo Anda. Simpan productId yang Anda butuhkan.
2. Baca pernyataan penggunaan data dan setujui jika Anda belum melakukannya.
3. Unggah berkas nomor dan simpan fileId yang dikembalikan.
4. Minta penawaran harga dengan productId dan fileId. Periksa jumlah, harga satuan, dan totalnya.
5. Buat dan simpan idempotency key, lalu buat pesanan. Langkah ini memotong saldo Anda.
6. Atur webhook untuk menerima pemberitahuan perubahan status pesanan, dan lakukan rekonsiliasi dengan updatedSince setiap 5–10 menit agar tidak ada yang terlewat.
7. Setelah pesanan selesai, tampilkan daftar berkas hasil, unduh semuanya, dan periksa sha256 masing-masing. Unduh juga berkas yang tidak berhasil.

Contoh curl

Ganti placeholder dengan nilai sebenarnya. Parameter lengkap untuk penawaran harga dan pesanan ada di panduan yang Anda terima bersama akses.

1. Atur kunci dan tampilkan layanan

   Salin

   export CHECKIM_TOKEN='ganti dengan kunci API dari tim dukungan'
   export CHECKIM_BASE='https://api.checkim.ai/openapi/v1'
   
   curl -H "Authorization: Bearer $CHECKIM_TOKEN" "$CHECKIM_BASE/products"

2. Unggah berkas nomor

   Salin

   curl -H "Authorization: Bearer $CHECKIM_TOKEN" \
     -F 'file=@./numbers.csv;type=text/csv' \
     "$CHECKIM_BASE/files"

3. Minta penawaran harga

   Salin

   curl -H "Authorization: Bearer $CHECKIM_TOKEN" \
     -H 'Content-Type: application/json' \
     -d '{"productId":"<productId>","name":"batch-001","fileId":"<fileId>"}' \
     "$CHECKIM_BASE/orders/check"

4. Buat pesanan

   Salin

   # Memotong saldo Anda. Gunakan kunci dan body yang sama persis saat mencoba ulang.
   curl -H "Authorization: Bearer $CHECKIM_TOKEN" \
     -H 'Content-Type: application/json' \
     -H 'Idempotency-Key: partner-request-001' \
     -d '{"quoteId":"<quoteId>","clientOrderId":"partner-batch-001"}' \
     "$CHECKIM_BASE/orders"

5. Baca pesanan, atau rekonsiliasi berdasarkan waktu perubahan

   Salin

   curl -H "Authorization: Bearer $CHECKIM_TOKEN" "$CHECKIM_BASE/orders/<orderId>"
   
   curl -H "Authorization: Bearer $CHECKIM_TOKEN" \
     "$CHECKIM_BASE/orders?updatedSince=<UTC ms>&size=100"

6. Tampilkan dan unduh hasil, lalu periksa sha256

   Salin

   curl -H "Authorization: Bearer $CHECKIM_TOKEN" "$CHECKIM_BASE/orders/<orderId>/results"
   
   curl -H "Authorization: Bearer $CHECKIM_TOKEN" -o result.csv \
     "$CHECKIM_BASE/orders/<orderId>/results/<fileId>/download"
   shasum -a 256 result.csv

Endpoint

Menampilkan dan merekonsiliasi pesanan

• Pesanan ditampilkan dari yang terbaru. Jika halaman berisi nextCursor, kirimkan kembali sebagai cursor untuk halaman berikutnya; paginasi cursor tidak pernah melewatkan atau mengulang pesanan meski ada pesanan baru.
• Filter berdasarkan status dan waktu pembuatan (createdFrom, createdTo, milidetik UTC), atau cari satu pesanan dengan clientOrderId.
• updatedSince hanya mengembalikan pesanan yang statusnya berubah setelah waktu tersebut, dari perubahan paling lama. Tarik data dengannya secara berkala agar webhook yang terlewat tidak membuat status hilang.

Mengunduh hasil

• Setiap berkas di daftar hasil memiliki sha256. ETag unduhan bernilai sama, jadi bandingkan setelah mengunduh.
• Permintaan Range dapat melanjutkan unduhan. Pastikan dulu sha256 tidak berubah; jika berubah, berkas telah dibuat ulang dan Anda perlu mengunduh seluruhnya lagi.
• Jika berkas lengkap sudah ada, kirim If-None-Match: berkas yang tidak berubah mengembalikan 304 tanpa body.
• Pesanan besar dengan pengiriman bertahap menampilkan tahap yang selesai saat masih berjalan; berkas akhir setelah selesai adalah versi resmi.
• Untuk layanan dengan avatar (cek lanjutan atau cek jenis kelamin dan usia Telegram dan WhatsApp), kolom avatar di CSV hasil berisi URL gambar bertanda tangan yang dapat diakses langsung dengan GET selama hasil disimpan (jangan kirim header Authorization; mendukung If-None-Match).

Webhook

• Saat status pesanan yang dibuat lewat API berubah, kami mengirim event dengan POST ke URL HTTPS Anda. Memerlukan izin webhook:manage.
• Setiap event membawa header CheckIM-Signature (t=timestamp,v1=tanda tangan). Verifikasi dengan HMAC-SHA256 dari "t.body permintaan asli" menggunakan secret penandatanganan Anda.
• Respons 2xx apa pun dianggap terkirim; kegagalan dicoba ulang 9 kali selama sekitar 2 hari. Anda bisa menerima event yang sama lebih dari sekali, jadi hapus duplikat berdasarkan id-nya.
• Permintaan datang dari IP keluar tetap 34.21.195.36, sehingga Anda bisa hanya mengizinkan alamat itu.

Status pesanan

Batas dan catatan

• Secara default, maksimal 1.200 permintaan per menit per IP keluar, 240 per akun, dan 120 per kunci. Header RateLimit-Limit, RateLimit-Remaining, dan RateLimit-Reset memberi tahu sisa kuota menit ini.
• Penawaran harga dan unggahan berjalan lambat, jadi setiap akun hanya boleh menjalankan paling banyak 3 sekaligus. Selebihnya menerima 429 TOO_MANY_CONCURRENT_REQUESTS.
• Saat menerima 429 atau 503, tunggu sesuai detik di Retry-After, lalu ulangi permintaan yang sama.
• Tidak ada sandbox. Setiap pesanan adalah tagihan sungguhan.
• Timeout saat polling tidak berarti pesanan gagal. Cari pesanan berdasarkan orderId atau clientOrderId sebelum memesan lagi.

Error umum

Error berisi code, requestId, message, dan detail.field (opsional). Tangani berdasarkan code; message dikirim dalam salah satu dari 9 bahasa sesuai Accept-Language dan hanya untuk ditampilkan.