API IROTP

Mulai cepat

1. Masuk ke web, buka Profil → API Key, lalu buat kunci. Kunci lengkap hanya tampil sekali.
2. Ambil GET /services. Pilih layanan dengan stock > 0 dan needs_reprice = false.
3. Kirim POST /orders memakai id dan price dari katalog, lalu cek GET /orders/{id} setiap 3–5 detik.

Authorization: Bearer ir_KUNCI_ANDA

Semua endpoint

Semua path memakai base URL di atas dan header Authorization: Bearer …. POST dengan body memakai Content-Type: application/json.

GET /services mengembalikan {"data":[...],"last_sync":"..."}. Tiap layanan memiliki id, name, channel (whatsapp/sms), stock, price, dan needs_reprice. Layanan SMS juga memuat server, country, produk, serta variant.

Pesan & cek OTP

expected_price adalah harga jual per nomor dalam rupiah dari katalog terbaru. qty untuk endpoint ini harus 1. Pakai Idempotency-Key unik per pembelian; untuk SMS wajib.

curl -X POST 'https://irotp.my.id/api/public/v1/orders' -H 'Authorization: Bearer ir_KUNCI_ANDA' -H 'Content-Type: application/json' -H 'Idempotency-Key: order-saya-0001' -d '{"service_id":123,"expected_price":1500,"qty":1}'

Respons 201 berbentuk {"order":{...}}. Simpan order.id, lalu cek:

curl 'https://irotp.my.id/api/public/v1/orders/456' -H 'Authorization: Bearer ir_KUNCI_ANDA'

GET /orders/{id} mengembalikan objek order langsung. Baca status, phone_number, otp_code, otp_message, refunded, dan expire_at (Unix detik). otp_message berisi pesan lengkap jika tersedia; otp_code bisa kosong bila kode tidak dikenali.

Pilih server dan negara

SMS dimulai dari pilihan server 1–5. Server 4 memakai kode negara ISO seperti id; server lain memakai kode angka seperti 6. Ambil produk dari katalog.

curl 'https://irotp.my.id/api/public/v1/sms/countries?server=1' -H 'Authorization: Bearer ir_KUNCI_ANDA'

curl 'https://irotp.my.id/api/public/v1/sms/options?server=1&country=6&produk=wa' -H 'Authorization: Bearer ir_KUNCI_ANDA'

Respons pilihan berisi {"services":[...]} dengan maksimal tiga varian termurah. Gunakan id dan price varian itu saat membuat order. Pembatalan server 1, 2, 3, dan 5 baru dapat diajukan setelah dua menit; server 4 kapan saja. Penolakan penyedia tidak mengubah saldo.

Bulk & multi

Bulk membeli 1–10 nomor dari satu varian WhatsApp atau SMS. Setiap nomor menjadi order terpisah.

curl -X POST 'https://irotp.my.id/api/public/v1/orders/bulk' -H 'Authorization: Bearer ir_KUNCI_ANDA' -H 'Content-Type: application/json' -H 'Idempotency-Key: bulk-saya-0001' -d '{"service_id":123,"expected_price":1500,"qty":3}'

Multi membeli 2–10 layanan WhatsApp berbeda, masing-masing satu nomor; SMS tidak tersedia pada endpoint ini.

curl -X POST 'https://irotp.my.id/api/public/v1/orders/group' -H 'Authorization: Bearer ir_KUNCI_ANDA' -H 'Content-Type: application/json' -H 'Idempotency-Key: multi-saya-0001' -d '{"items":[{"service_id":123,"expected_price":1500},{"service_id":124,"expected_price":1700}],"qty":1}'

Kedua respons memuat group_id, status, dan array orders. 201 berarti dibuat, 202 berarti ada order yang perlu diperiksa, dan bulk dapat memberi 207 bila sebagian berhasil. Idempotency-Key wajib, 8–100 karakter (huruf, angka, titik, garis bawah, titik dua, atau minus). Jika koneksi putus, ulangi body dan kunci yang sama; jangan membuat pesanan baru sebelum hasilnya jelas.

Status & aksi

Status order: creating, active, pending, otp_received, completed, cancelled, expired, failed, refunded, dan needs_review. Order dengan OTP yang sudah masuk otomatis selesai ketika batas sewa lewat.

• POST /orders/{id}/ack: tandai selesai setelah OTP masuk.
• POST /orders/{id}/cancel: batalkan sebelum OTP masuk, sesuai aturan server.
• POST /orders/{id}/resend: WhatsApp setelah OTP pertama; SMS hanya saat penyedia berstatus sukses dan sewa belum habis. 429 berarti masih harus menunggu.
• POST /orders/{id}/reactivate: hanya WhatsApp, body {"expected_price":1500}; membuat order baru dan memotong saldo lagi jika berhasil.

GET /orders memuat maksimal 200 order terbaru dalam data; GET /orders/active hanya status active, pending, dan otp_received. API key hanya melihat order milik akun sendiri.

Webhook OTP

Buka Profil → Webhook OTP, isi URL HTTPS publik aplikasi Anda, lalu salin kunci tanda tangan yang hanya tampil sekali. Saat order dibuat, berubah status, atau menerima OTP, IROTP mengirim POST JSON ke URL itu. Tombol Kirim tes dan riwayat pengiriman ada di halaman yang sama.

{"id":71,"type":"order.otp_received","created_at":"2026-10-17 10:00:00","order":{"id":456,"status":"otp_received","phone_number":"628123456789","otp_code":"123456","otp_message":"Kode verifikasi Anda 123456"}}

Header: X-IROTP-Event-ID, X-IROTP-Timestamp (Unix detik), dan X-IROTP-Signature: v1=.... Verifikasi HMAC-SHA256 dari timestamp + "." + raw_body memakai kunci tanda tangan. Bandingkan secara konstan, tolak timestamp yang lebih tua dari 5 menit, dan proses setiap event ID satu kali saja. Balas HTTP 2xx setelah event tersimpan. Jika gagal, pengiriman dicoba lagi sampai delapan kali; urutan kedatangan tidak dijamin. webhook.test tidak berisi order. Jangan letakkan kunci di kode browser.

Error & batas

Error umum berbentuk {"error":"pesan"}. Harga berubah dapat menyertakan current_price; penolakan SMS tertentu menyertakan detail. Bila harga berubah, muat katalog dan minta konfirmasi harga baru.

400 data/saldo/aksi salah · 401 API key tidak valid · 404 order atau endpoint tidak ditemukan · 409 harga/stok berubah atau kunci bentrok · 429 terlalu banyak permintaan · 502/504 penyedia bermasalah.

Batas utama: 120 permintaan per menit per akun, 20 pembuatan order per menit, dan 30 aksi order per menit. Gunakan polling 3–5 detik jika belum memakai webhook.

Unduh api.json

File ini adalah spesifikasi OpenAPI 3.1 untuk Postman, Swagger, atau generator klien. /api.json mengunduh isi yang sama persis dengan /openapi.json.