API KodeOTP

Integrasi server-to-server melalui HTTPS untuk menghubungkan akun KodeOTP dengan website atau aplikasi Anda.

Keamanan: jangan menaruh API key pada frontend/browser, aplikasi publik, repositori, atau log. Setiap key hanya dapat membaca dan mengelola data milik akun pemilik key. Batas: 120 request per menit per key; sinkronisasi OTP minimal jeda 3 detik.

Autentikasi & API key

Login sebagai member, buka menu API & Docs, lalu buat key dengan label integrasi. Key penuh ditampilkan satu kali dan tidak dapat dilihat kembali. Simpan di secret manager atau environment variable server. Maksimal lima key aktif; cabut key yang tidak dipakai atau terindikasi bocor.

Authorization: Bearer KUNCI_API_ANDA
Base URL: https://kodeotpku.my.id/api/v1

Panggil API dari backend Anda menggunakan HTTPS. Jangan mengirim request API key dari browser pengguna. Sertakan header User-Agent yang deskriptif, mis. KodeOTP-Integration/1.0; request tanpa User-Agent atau User-Agent bawaan Python-urllib dapat diblokir proteksi edge (HTTP 403/1010).

Endpoint tersedia

GET /me — identitas member, saldo, dan biaya reuse terkini.
GET /inventory?service=telegram&country=US — stok produk yang tersedia; maksimal 200 hasil.
GET /orders — hingga 100 order terbaru milik akun, tanpa isi OTP.
POST /orders — membeli produk dengan konfirmasi harga, stok, dan kecukupan saldo.
GET /orders/{id} — detail order milik sendiri; OTP hanya disertakan jika tersedia dan order sudah dibayar.
POST /orders/{id}/sync-otp — menyinkronkan pesan SMS masuk untuk order tersebut; jeda minimal 3 detik per key.
POST /orders/{id}/verify-otp — verifikasi kode 4–8 angka; tidak menagih ulang biaya pembelian nomor.
POST /orders/{id}/reuse — memulai siklus OTP baru setelah order selesai diverifikasi; memakai tarif reuse terkini.

Membaca saldo dan stok

export KODEOTP_API_KEY='simpan-key-di-environment-backend'

curl -H "Authorization: Bearer $KODEOTP_API_KEY" \
  -H "User-Agent: KodeOTP-Integration/1.0" \
  'https://kodeotpku.my.id/api/v1/me'

curl -H "Authorization: Bearer $KODEOTP_API_KEY" \
  'https://kodeotpku.my.id/api/v1/inventory?service=telegram&country=US'

Membeli produk

Ambil product_id dan price terkini dari inventori. Tampilkan harga ke pengguna website Anda dan minta persetujuan sebelum mengirim request. Server memeriksa kembali stok/harga dan memotong saldo secara atomik.

curl -X POST 'https://kodeotpku.my.id/api/v1/orders' \
  -H "Authorization: Bearer $KODEOTP_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"product_id":123,"price":250,"purchase_confirmed":true}'

Jika harga atau stok berubah, request ditolak. Ambil data terbaru dan minta persetujuan baru; jangan mengulang dengan harga lama.

Menyinkronkan dan memverifikasi OTP

curl -X POST 'https://kodeotpku.my.id/api/v1/orders/456/sync-otp' \
  -H "Authorization: Bearer $KODEOTP_API_KEY"

curl -H "Authorization: Bearer $KODEOTP_API_KEY" \
  'https://kodeotpku.my.id/api/v1/orders/456'

curl -X POST 'https://kodeotpku.my.id/api/v1/orders/456/verify-otp' \
  -H "Authorization: Bearer $KODEOTP_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"code":"123456"}'

Order wajib sudah dibayar. Layanan tujuan tetap yang meminta kode; API hanya menyinkronkan SMS inbound yang tersedia. Contoh kode di atas adalah placeholder, bukan OTP sungguhan. Jangan masukkan kode OTP ke log.

Memulai reuse

Baca tarif terkini dari GET /me, tampilkan kepada pengguna akhir, dan minta persetujuannya. Kirim tarif aktual—bukan angka contoh berikut—serta flag konfirmasi:

{"fee":250,"fee_confirmed":true}

Saldo harus mencukupi. Jika tarif berubah, ambil nilai terbaru dan minta persetujuan ulang.

Respons dan kode error

200 — berhasil.
201 — API key berhasil dibuat.
401 — login/key tidak valid atau tidak disertakan.
402 — saldo tidak cukup atau order belum dibayar.
409 — harga, stok, atau status berubah.
422 — input tidak valid.
429 — batas request tercapai; tunggu sesuai respons.
502/503 — provider atau konfigurasi belum siap.

Respons API menggunakan JSON. Periksa status HTTP dan pesan error sebelum mencoba ulang.