NokosOTP API

API internal untuk pembelian nomor OTP virtual lewat akun bot Telegram kamu. Saldo, riwayat, dan status order sepenuhnya sinkron dengan bot — dua-duanya baca dan tulis ke data yang sama.

Base URL: receotp.my.id Format: JSON ⚠ Tidak untuk publik / unlisted

Perkenalan

API ini dibuat untuk pengguna bot @Jeeytsdbot yang ingin mengotomasi pembelian nokos dari sistem mereka sendiri (script, bot lain, dashboard internal, dsb) tanpa perlu klak-klik di Telegram.

Endpoint ini hanya menangani jual-beli nomor OTP — cek saldo, cek layanan/negara, order nomor, cek status, cancel, dan lihat order aktif. Top up saldo tetap dilakukan lewat bot Telegram (menu Top Up), tidak tersedia lewat API ini.

Dokumen ini tidak di-index dan tidak dipublikasikan di mana pun. Jangan sebarkan link atau isi halaman ini ke luar.

Autentikasi

Setiap request wajib membawa API key lewat header x-api-key, atau alternatifnya lewat query ?apikey=.

Ambil key kamu langsung dari bot: Menu Utama → 🔑 API Developer → Generate API Key. Satu akun Telegram hanya punya satu API key aktif — generate ulang akan otomatis mematikan key lama.

curl https://docs.receotp.my.id/api/balance \
  -H "x-api-key: nokos_xxx"

const res = await fetch("https://docs.receotp.my.id/api/balance", {
  headers: { "x-api-key": "nokos_xxx" }
});
const data = await res.json();

import requests
r = requests.get(
  "https://docs.receotp.my.id/api/balance",
  headers={"x-api-key": "nokos_xxx"}
)
data = r.json()

Jaga kerahasiaan API key. Jangan pernah embed di aplikasi client-side atau share ke orang lain. Kalau bocor, generate ulang lewat menu bot.

Kode Error

Semua response error berformat sama:

{
  "ok": false,
  "error": "NO_SALDO",
  "message": "Saldo kamu tidak cukup."
}

Status	Error Code	Kapan Muncul
401	`NO_API_KEY`	Header/query API key tidak dikirim
401	`INVALID_KEY`	API key salah atau sudah dihapus/diganti
429	`RATE_LIMITED`	Lebih dari 30 request/menit dari key yang sama
402	`NO_SALDO`	Saldo tidak cukup untuk order
404	`NOT_FOUND`	Order/negara tidak ditemukan atau bukan milik kamu
409	`NO_STOK`	Stok nomor habis untuk negara/layanan ini
409	`CANCEL_TOO_EARLY`	Belum bisa cancel, lihat `retryAfter`
502	`ORDER_FAILED`	Provider gagal membuat order (saldo tidak dipotong)
502	`SERVICES_ERROR` / `COUNTRIES_ERROR`	Provider gagal merespons

Akun

GET/api/balance

Cek sisa saldo untuk API key ini. Saldo ini adalah saldo yang sama dengan yang muncul di bot Telegram kamu.

Request

curl https://docs.receotp.my.id/api/balance \
  -H "x-api-key: nokos_xxx"

const r = await fetch("https://docs.receotp.my.id/api/balance", {
  headers: { "x-api-key": KEY }
});
console.log(await r.json());

Response 200

{
  "ok": true,
  "saldo": 15000
}

Field	Tipe	Keterangan
`saldo`	int	Sisa saldo (rupiah), sinkron langsung dengan bot

Nokos OTP

GET/api/services

Daftar layanan yang bisa dibeli nomornya (WhatsApp, Telegram, Facebook, dst).

Request

curl https://docs.receotp.my.id/api/services \
  -H "x-api-key: nokos_xxx"

Response 200

{
  "ok": true,
  "services": [
    { "code": "wa", "name": "Whatsapp" },
    { "code": "tg", "name": "Telegram" }
  ]
}

code di sini dipakai sebagai parameter service pada endpoint /api/countries dan /api/order.

GET/api/countries

Daftar negara yang tersedia untuk sebuah layanan, lengkap dengan harga termurah dan stok saat ini (real-time dari provider).

Query Parameters

Nama	Tipe	Wajib	Keterangan
`service`	string	Ya	Service code dari `/api/services`, mis. `wa`

Request

curl "https://docs.receotp.my.id/api/countries?service=wa" \
  -H "x-api-key: nokos_xxx"

Response 200

{
  "ok": true,
  "countries": [
    {
      "numberId": "6",
      "isoCode": "id",
      "name": "Indonesia",
      "price": 3677,
      "stock": 142
    }
  ]
}

numberId dipakai sebagai parameter numberId pada /api/order. price sudah termasuk markup — angka ini yang akan dipotong dari saldo saat order.

POST/api/order

Beli 1 nomor OTP baru. Server otomatis memilih provider termurah yang stoknya tersedia untuk negara tersebut. Saldo dipotong saat order berhasil dibuat — kalau provider gagal, saldo tidak jadi dipotong.

Body (JSON)

Nama	Tipe	Wajib	Keterangan
`service`	string	Ya	Service code, mis. `wa`
`numberId`	string	Ya	`numberId` dari `/api/countries`

Request

curl -X POST https://docs.receotp.my.id/api/order \
  -H "x-api-key: nokos_xxx" \
  -H "Content-Type: application/json" \
  -d '{"service":"wa","numberId":"6"}'

const r = await fetch("https://docs.receotp.my.id/api/order", {
  method: "POST",
  headers: {
    "x-api-key": KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ service: "wa", numberId: "6" }),
});

r = requests.post(
  "https://docs.receotp.my.id/api/order",
  headers={"x-api-key": KEY},
  json={"service": "wa", "numberId": "6"},
)

Response 200

{
  "ok": true,
  "orderId": "1234567890",
  "phone": "+6281234567890",
  "price": 3677,
  "saldoSisa": 11323
}

Order yang dibuat lewat API muncul juga di menu Pesanan Aktif pada bot, dan otomatis kirim notifikasi ke channel testimoni begitu OTP diterima — sama seperti order dari bot.

GET/api/status/:orderId

Cek status order & ambil kode OTP kalau sudah masuk. Disarankan polling tiap 5 detik.

Request

curl https://docs.receotp.my.id/api/status/1234567890 \
  -H "x-api-key: nokos_xxx"

Response 200 — Menunggu OTP

{
  "ok": true,
  "orderId": "1234567890",
  "state": "waiting",
  "hasOtp": false
}

Response 200 — OTP diterima

{
  "ok": true,
  "orderId": "1234567890",
  "state": "sukses",
  "hasOtp": true,
  "otp": "123456"
}

State	Arti
`waiting`	Order masih aktif, menunggu OTP masuk
`sukses`	OTP sudah diterima, order pindah ke riwayat

POST/api/cancel

Batalkan order & refund saldo. Cancel baru bisa dilakukan setelah 3 menit dari order dibuat, memberi kesempatan OTP masuk lebih dulu.

Body (JSON)

Nama	Wajib	Keterangan
`orderId`	Ya	ID order dari `/api/order`

Request

curl -X POST https://docs.receotp.my.id/api/cancel \
  -H "x-api-key: nokos_xxx" \
  -H "Content-Type: application/json" \
  -d '{"orderId":"1234567890"}'

Response 200

{
  "ok": true,
  "orderId": "1234567890",
  "refunded": 3677,
  "saldoSisa": 15000
}

Kalau muncul CANCEL_TOO_EARLY, tunggu jumlah detik di field retryAfter lalu coba lagi.

GET/api/orders

List semua order yang masih aktif (belum selesai/di-cancel) milik API key ini.

Request

curl https://docs.receotp.my.id/api/orders \
  -H "x-api-key: nokos_xxx"

Response 200

{
  "ok": true,
  "count": 1,
  "orders": [
    {
      "orderId": "1234567890",
      "phone": "+6281234567890",
      "service": "Whatsapp",
      "country": "Indonesia",
      "price": 3677,
      "createdAt": "2026-08-31T10:45:00.000Z"
    }
  ]
}

NokosOTP API · internal use only · receotp.my.id