NOKOS.MY.ID REST API
Integrasikan layanan nomor virtual dan penerimaan SMS OTP otomatis ke dalam bot Telegram, aplikasi, atau platform Anda. Seluruh transaksi bersifat atomik, aman, dan mendukung pengembalian saldo (auto-refund) 100% jika nomor tidak menerima SMS dalam 20 menit.
Autentikasi API Key
Setiap request ke endpoint publik wajib menyertakan API Key aktif yang dibuat melalui menu Dashboard → API Keys.
Kirimkan API Key menggunakan header standar HTTP. API Key NOKOS.MY.ID selalu diawali dengan prefix nokosmyid_.
curl -X GET "https://nokos.my.id/api/v1/balance" \ -H "Authorization: Bearer nokosmyid_98f12a3bcde456..."
Alternatif pendukung: Server juga menerima header X-API-Key: nokosmyid_... atau query param ?api_key=nokosmyid_....
Base URL
Semua permintaan API v1 diarahkan ke base URL produksi berikut:
Kode Status & Error Handling
Respon error selalu mengembalikan format JSON dengan kunci success: false dan pesan deskriptif pada error.
| Status | Nama | Keterangan |
|---|---|---|
| 200 OK | Berhasil | Permintaan GET berhasil atau aksi selesai diproses. |
| 201 Created | Dibuat | Order nomor virtual baru atau invoice deposit berhasil dibuat. |
| 400 Bad Request | Parameter Salah | Parameter wajib hilang atau format parameter tidak valid. |
| 401 Unauthorized | Auth Gagal | API Key hilang, format salah, atau telah dicabut (revoked). |
| 402 Payment Required | Saldo Kurang | Saldo akun Anda tidak mencukupi untuk harga produk yang diminta. |
| 404 Not Found | Tidak Ditemukan | Order ID atau Deposit ID tidak ditemukan di bawah akun Anda. |
| 409 Conflict | Konflik Status | Contoh: Membatalkan order yang sudah menerima OTP, atau menyelesaikan order sebelum OTP masuk. |
| 429 Rate Limit | Limit Terlampaui | Terlalu banyak permintaan dalam 1 menit. Harap beri jeda polling. |
Mengambil saldo terkini akun NOKOS.MY.ID Anda dalam mata uang Rupiah (IDR).
curl -X GET "https://nokos.my.id/api/v1/balance" \ -H "Authorization: Bearer nokosmyid_your_key"
Contoh Respon Berhasil (200 OK)
{
"success": true,
"data": {
"balance_idr": 250000,
"balance_formatted": "Rp 250.000"
}
}
Mengambil seluruh daftar negara yang tersedia beserta ID negara untuk pemfilteran layanan dan produk.
curl -X GET "https://nokos.my.id/api/v1/catalog/countries" \ -H "Authorization: Bearer nokosmyid_your_key"
Contoh Respon Berhasil (200 OK)
{
"data": [
{ "id": 7, "name": "Indonesia", "iso": "ID", "code": "62" },
{ "id": 1, "name": "Russia", "iso": "RU", "code": "7" },
{ "id": 187, "name": "United States", "iso": "US", "code": "1" }
]
}
Mengambil daftar aplikasi/platform OTP yang tersedia (WhatsApp, Telegram, Google, TikTok, dll).
| Query Param | Tipe | Status | Keterangan |
|---|---|---|---|
country_id |
integer | Opsional | Filter layanan berdasarkan ID negara spesifik (misal: 7 untuk Indonesia). |
curl -X GET "https://nokos.my.id/api/v1/catalog/services?country_id=7" \ -H "Authorization: Bearer nokosmyid_your_key"
Mengambil daftar operator seluler yang tersedia untuk kombinasi negara dan platform tertentu.
| Query Param | Tipe | Status | Keterangan |
|---|---|---|---|
country_id |
integer | Wajib | ID negara yang dipilih (misal: 7). |
platform_id |
integer | Wajib | ID platform/layanan (misal: 3 untuk WhatsApp). |
Operator ID harus bertipe numerik (angka). Jangan mengirim string seperti "Any" atau nama operator. Jika ingin sembarang operator yang tersedia, kosongkan parameter operator saat order.
Mengambil produk nomor virtual yang siap di-order lengkap dengan jumlah stok dan harga final dalam IDR (Rupiah).
| Query Param | Tipe | Status | Keterangan |
|---|---|---|---|
country_id |
integer | Opsional | Filter berdasarkan ID negara. |
platform_id |
integer | Opsional | Filter berdasarkan ID layanan. |
operator_id |
integer | Opsional | Filter operator khusus (numerik). |
sort |
string | Opsional | Urutan harga: price_asc (termurah) atau price_desc. |
limit |
integer | Opsional | Batas item per halaman (default 20, max 100). |
page |
integer | Opsional | Nomor halaman paginasi (default 1). |
curl -X GET "https://nokos.my.id/api/v1/catalog/products?country_id=7&platform_id=3&sort=price_asc&limit=10" \ -H "Authorization: Bearer nokosmyid_your_key"
Contoh Respon Berhasil (200 OK)
{
"data": [
{
"id": 142,
"catalog_product_id": 87,
"name": "WhatsApp - ID Indonesia",
"operator_name": "Any",
"quantity": 458200,
"country_name": "Indonesia",
"nokosmyid_price_idr": 13700,
"nokosmyid_price_formatted": "Rp 13.700"
}
]
}
Membuat pesanan nomor virtual baru. Saldo akun akan terpotong secara atomik. Jika saldo tidak cukup, API mengembalikan HTTP 402.
| Field Body (JSON) | Tipe | Status | Keterangan |
|---|---|---|---|
catalog_product_id |
integer | Wajib* | ID produk dari GET /catalog/products (wajib jika tanpa product_id). |
product_id |
integer | Alternatif | Alternatif ID produk jika tidak menggunakan catalog_product_id. |
country_id |
integer | Sangat Disarankan | ID negara untuk menjamin keakuratan kalkulasi harga lokal. |
platform_id |
integer | Sangat Disarankan | ID platform/layanan produk. |
service_name |
string | Opsional | Nama layanan untuk label deskripsi transaksi (misal: "WhatsApp"). |
country_name |
string | Opsional | Nama negara untuk label transaksi (misal: "Indonesia"). |
operator_id |
integer | Opsional | Operator khusus. Harus berupa angka numerik. |
curl -X POST "https://nokos.my.id/api/v1/orders/create" \
-H "Authorization: Bearer nokosmyid_your_key" \
-H "Content-Type: application/json" \
-d '{
"catalog_product_id": 87,
"country_id": 7,
"platform_id": 3,
"service_name": "WhatsApp",
"country_name": "Indonesia"
}'
Contoh Respon Berhasil (201 Created)
{
"success": true,
"data": {
"id": "ord_a98f12c4e56b",
"status": "active",
"phone_number": "+6283812345678",
"service_name": "WhatsApp",
"country_name": "Indonesia",
"price_idr": 13700,
"otp_code": null,
"expires_at": "2026-11-03T00:45:00.000Z",
"created_at": "2026-11-03T00:25:00.000Z"
}
}
Mengambil status pesanan dan kode OTP terkini. Saat order berstatus active, server otomatis melakukan live polling ke provider SMS.
Panggil endpoint ini dengan interval setiap 3 hingga 5 detik sampai properti otp_code terisi. Jangan melakukan polling di bawah 1 detik agar tidak terkena rate-limiting.
curl -X GET "https://nokos.my.id/api/v1/orders/ord_a98f12c4e56b" \ -H "Authorization: Bearer nokosmyid_your_key"
Contoh Respon Saat OTP Diterima (200 OK)
{
"success": true,
"data": {
"id": "ord_a98f12c4e56b",
"status": "active",
"phone_number": "+6283812345678",
"otp_code": "849201",
"price_idr": 13700,
"service_name": "WhatsApp",
"country_name": "Indonesia"
}
}
Membatalkan order aktif sebelum OTP masuk. Saldo akan di-refund 100% secara instan kembali ke akun Anda.
Jika nomor sudah menerima SMS atau status OTP telah terisi, pembatalan akan ditolak dengan error 409 OTP_ALREADY_RECEIVED. Jika pesanan baru saja dibuat kurang dari 60 detik, provider mungkin meminta jeda sebelum pembatalan dapat diproses (CANCEL_TOO_EARLY).
curl -X POST "https://nokos.my.id/api/v1/orders/ord_a98f12c4e56b/cancel" \ -H "Authorization: Bearer nokosmyid_your_key"
Contoh Respon Berhasil (200 OK)
{
"success": true,
"message": "Order cancelled and balance refunded."
}
Menandai pesanan sebagai selesai setelah OTP berhasil Anda gunakan. Wajib dipanggil setelah OTP diterima jika Anda ingin menutup sesi nomor lebih cepat.
Meminta pengiriman ulang kode SMS kedua jika layanan/platform yang Anda tuju mendukung verifikasi multi-SMS pada nomor yang sama.
Buat Tagihan Deposit Saldo (QRIS Instan)
Membuat tagihan pengisian saldo via QRIS otomatis. API mengembalikan raw string QRIS (EMVCo) serta tautan gambar QR untuk langsung ditampilkan kepada pengguna.
| Field Body (JSON) | Tipe | Status | Keterangan |
|---|---|---|---|
amount |
integer | Wajib | Nominal deposit dalam Rupiah (minimum Rp 3.000). |
method |
string | Opsional | Metode pembayaran. Nilai default: qris. |
curl -X POST "https://nokos.my.id/api/v1/deposit" \
-H "Authorization: Bearer nokosmyid_your_key" \
-H "Content-Type: application/json" \
-d '{"amount": 50000, "method": "qris"}'
Contoh Respon Berhasil (201 Created)
{
"success": true,
"data": {
"id": "dep_b812f0a1c9",
"depositId": "dep_b812f0a1c9",
"amount": 50000,
"qris_data": "00020101021226680016ID.CO.QRIS.WWW...",
"qr_image": "https://nokosnesia.com/api/qr/...",
"payment_link": "https://nokosnesia.com/pay/...",
"gateway": "nokosnesia",
"fee": 0,
"diterima": 50000,
"expired": "2026-11-03T01:30:00.000Z"
}
}
Mengecek status pembayaran deposit. Saat pembayaran terdeteksi lunas (PAID / SUCCESS), sistem otomatis mengkreditkan saldo secara atomik dan idempoten (anti double-credit).
Contoh Respon Pembayaran Berhasil (200 OK)
{
"success": true,
"data": {
"status": "success"
}
}
Webhook & Callback
Gunakan Webhook agar sistem Anda tidak perlu melakukan polling terus-menerus. Setiap kali ada event baru (seperti OTP masuk atau deposit berhasil), server NOKOS.MY.ID akan mengirimkan HTTP POST ke endpoint callback Anda.
Setiap request webhook menyertakan header x-nokosmyid-signature: sha256=... yang di-hash menggunakan Webhook Secret Anda. Hitung HMAC-SHA256 dari raw body untuk memastikan integritas pesan.
Daftar Event Webhook yang Didukung
| Nama Event | Waktu Trigger | Deskripsi |
|---|---|---|
order.created |
Order Baru | Nomor virtual berhasil dialokasikan dan aktif menunggu SMS. |
order.otp_received |
SMS Masuk | Kode OTP pertama kali tiba dari provider dan tersimpan di database. |
order.completed |
Order Selesai | Order ditandai selesai atau selesai otomatis setelah 20 menit. |
order.cancelled |
Dibatalkan | Order dibatalkan dan pengembalian saldo 100% diproses. |
deposit.completed |
Deposit Lunas | Pembayaran QRIS diverifikasi dan saldo akun Anda telah bertambah. |
const express = require('express');
const crypto = require('crypto');
const app = express();
app.post('/webhook', express.raw({ type: 'application/json' }), (req, res) => {
const secret = 'whsec_your_webhook_secret';
const sigHeader = req.headers['x-nokosmyid-signature'];
const event = req.headers['x-nokosmyid-event'];
const expectedSig = 'sha256=' + crypto.createHmac('sha256', secret).update(req.body).digest('hex');
if (sigHeader !== expectedSig) {
return res.status(401).send('Invalid signature');
}
const payload = JSON.parse(req.body.toString());
console.log('Event diterima:', event, payload);
if (event === 'order.otp_received') {
console.log('Nomor:', payload.data.phone_number, 'OTP:', payload.data.otp_code);
}
res.status(200).send('OK');
});
app.listen(8080);
Siklus Otomatis 20 Menit & Auto-Refund
NOKOS.MY.ID mengoperasikan background worker pemantau pesanan yang memeriksa siklus hidup setiap nomor virtual setiap 15 detik:
Jika SMS OTP Diterima
Setelah OTP diterima, status order tetap aktif hingga 20 menit agar Anda bisa meminta pengiriman ulang (resend SMS) jika diperlukan, sebelum ditutup otomatis sebagai pesanan selesai.
Jika SMS Tidak Masuk
Jika setelah 20 menit tidak ada satu pun SMS yang diterima pada nomor tersebut, sistem otomatis membatalkan pesanan di provider dan mengembalikan saldo 100% ke akun Anda tanpa perlu komplain manual.