N
NOKOS.MY.ID
Dokumentasi Pengembang Production Ready

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.

Format Data
JSON UTF-8
Autentikasi
Bearer Key
Masa Aktif OTP
20 Menit
Refund Otomatis
100% Saldo
01 ยท KEAMANAN & KREDENSIAL

Autentikasi API Key

Setiap request ke endpoint publik wajib menyertakan API Key aktif yang dibuat melalui menu Dashboard → API Keys.

๐Ÿ’ก
Format Resmi: Header Authorization Bearer

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_....

02 ยท ENDPOINT ROOT

Base URL

Semua permintaan API v1 diarahkan ke base URL produksi berikut:

https://nokos.my.id/api/v1
03 ยท STATUS RESPON

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.
GET /balance

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"
  }
}
GET /catalog/countries

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" }
  ]
}
GET /catalog/services

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"
GET /catalog/operators

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).
โš ๏ธ
Penting Mengenai Operator ID

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.

GET /catalog/products

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"
    }
  ]
}
POST /orders/create

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"
  }
}
GET /orders/:id

Mengambil status pesanan dan kode OTP terkini. Saat order berstatus active, server otomatis melakukan live polling ke provider SMS.

๐Ÿ”„
Rekomendasi Polling OTP

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"
  }
}
POST /orders/:id/cancel

Membatalkan order aktif sebelum OTP masuk. Saldo akan di-refund 100% secara instan kembali ke akun Anda.

โš ๏ธ
Aturan Pembatalan

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."
}
POST /orders/:id/finish

Menandai pesanan sebagai selesai setelah OTP berhasil Anda gunakan. Wajib dipanggil setelah OTP diterima jika Anda ingin menutup sesi nomor lebih cepat.

POST /orders/:id/resend

Meminta pengiriman ulang kode SMS kedua jika layanan/platform yang Anda tuju mendukung verifikasi multi-SMS pada nomor yang sama.

POST /deposit

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"
  }
}
GET /deposit/:id

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"
  }
}
Real-time Push Event

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.

๐Ÿ”’
Verifikasi Signature HMAC-SHA256

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.
Contoh Verifikasi Signature (Node.js Express)
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.

Tersalin ke clipboard!