Security & Limits

4.1 Keamanan API key

Peringatan. API key memberi akses penuh ke saldo wallet Anda. Siapa pun yang memegang key bisa membeli produk sampai saldo habis. API tidak punya batas belanja harian.

Pakai key hanya dari server Anda.

• Simpan key di environment variable atau secret manager di server. Jangan tulis di kode atau repositori Git.
• Jangan taruh key di aplikasi browser (JavaScript di halaman web) atau aplikasi mobile (Android, iOS), juga tidak di aplikasi desktop yang dibagikan. Apa pun yang sampai ke perangkat pengguna bisa dibongkar. Pola yang benar: aplikasi pelanggan memanggil server Anda, dan server Anda memanggil API ini.
• Server Anda yang memutuskan siapa boleh membeli apa dan berapa banyak. API hanya melihat satu pemanggil, yaitu Anda.
• Jangan kirim key lewat query string. Request seperti itu ditolak dengan 400 invalid_request (lihat bagian 1.4).
• Jangan mencatat header Authorization di log aplikasi, log proxy, atau alat pelacakan error.
• Minta toko mengisi allowlist IP key dengan IP server Anda (sampai 10 alamat IPv4, IPv6, atau CIDR). Key yang bocor lalu tidak bisa dipakai dari tempat lain.

Putar key bila diduga bocor.

1. Minta toko memutar key (rotate). Key lama langsung ditolak dengan 401 invalid_api_key mulai request berikutnya. Allowlist IP ikut terbawa ke key baru. Toko juga bisa mencabut key atau mematikan Akses API.
2. Perbarui key di semua aplikasi Anda. Karena satu key dipakai bersama, semua aplikasi berhenti sampai key barunya dipasang.
3. Periksa GET /balance/transactions dan GET /orders untuk pembelian yang tidak Anda kenali, lalu laporkan ke toko.

4.2 IP allowlist

Allowlist IP membatasi key supaya hanya bisa dipakai dari alamat server Anda. Toko mengisinya atas permintaan Anda dengan sampai 10 alamat IPv4, IPv6, atau CIDR, dan allowlist ikut terbawa ke key baru saat key diputar. Isinya terlihat di field ip_allowlist pada GET /me.

Bila allowlist IP key tidak kosong, hanya IP di daftar itu yang diterima. Alamat yang dipakai adalah alamat klien sebagaimana dilihat server API. Bila server Anda keluar lewat NAT atau proxy, daftarkan alamat keluarnya. Allowlist kosong berarti semua IP diizinkan.

Request dari IP di luar allowlist dijawab 403 ip_not_allowed. Kegagalan ini ikut dihitung sebagai kegagalan autentikasi (20 per 5 menit per IP, lihat bagian 4.3).

4.3 Batas rate dan beban

Hal yang perlu diketahui:

• Batas baca dan batas order terpisah. Semua GET memakai satu jatah, POST /orders memakai jatah sendiri. Header X-RateLimit-Limit menunjukkan jatah mana yang berlaku (120 atau 20).
• Satu key dipakai semua aplikasi Anda, jadi jatahnya dipakai bersama.
• Jendela bersifat bergulir (rolling), bukan reset pada menit penuh. Setiap request yang sampai ke pembatas dihitung, termasuk yang ditolak dan yang kemudian dijawab server_busy. Mengulang terus saat menerima 429 memperpanjang masa tunggu. Tunggu Retry-After.
• Batas request bersamaan dipakai bersama oleh semua reseller di toko yang sama, bukan hanya Anda. Jaga aplikasi Anda pada 1 sampai 2 request paralel, dan antre sisanya di sisi Anda.
• Nilai batas untuk key Anda bisa dibaca dari GET /me (rate_limits). Jangan menulis angkanya mati di kode.

Contoh jawaban 429:

HTTP/1.1 429 Too Many Requests
X-Request-Id: 66666666-6666-4666-8666-666666666666
Cache-Control: no-store
X-RateLimit-Limit: 20
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 38
Retry-After: 38

{
  "success": false,
  "error": { "code": "rate_limited", "message": "Terlalu banyak permintaan, coba lagi nanti." },
  "request_id": "66666666-6666-4666-8666-666666666666"
}

4.4 Header respons

Header X-RateLimit-* tidak ada pada jawaban yang dibuat sebelum pembatas per key, yaitu galat toko, galat autentikasi, channel_disabled, plan_not_eligible, dan not_found.

Header request yang dipakai:

4.5 Batasan

• Hanya pembayaran dengan saldo wallet. Tidak ada top up, QRIS, crypto, atau voucher lewat API.
• Tidak ada webhook keluar ke URL Anda dan tidak ada mode sandbox. Setiap pembelian memotong saldo sungguhan.
• Tidak ada notifikasi bot untuk order API. Isi produk hanya ada di respons.
• Order API Anda ikut tampil di riwayat pesanan bot Telegram akun Anda.
• Satu key per reseller, tanpa scope. Key yang bocor dari satu aplikasi membuka seluruh saldo Anda, dan memutar key berarti semua aplikasi diperbarui bersamaan.
• Toko mencatat setiap POST /orders yang lolos batas rate dan setiap penolakan ip_not_allowed selama 30 hari: waktu, endpoint, status, kode galat, IP, nomor order, dan latensi. Header Authorization, key, serta isi request dan respons tidak dicatat.
• Akses bergantung pada layanan toko. Bila toko tidak lagi menyediakan API Reseller, API menjawab plan_not_eligible tetapi key dan izin Anda tidak dihapus.