NOKOS.co.id API Docs

Quick Start

Mulai integrasi dalam 3 langkah sederhana:

1
Daftar akun di Nokos.co.id (gratis)
2
Generate API Key dari dashboard di /dashboard/profile
3
Pakai API Key di header X-API-Key untuk semua request

Contoh request pertama — cek saldo:

# cURL example
curl "https://nokos.co.id/api/?action=getBalance" \
  -H "X-API-Key: YOUR_API_KEY"

# Response:
{
  "success": true,
  "data": { "balance": 50000 }
}

Authentication

Semua API request membutuhkan autentikasi via API Key yang dikirim di HTTP header.

Recommended: HTTP Header

X-API-Key: your_api_key_here

Alternative: Bearer Token

Authorization: Bearer your_api_key_here

Deprecated: mengirim api_key sebagai URL/POST parameter masih didukung untuk backward compat, tapi disarankan migrasi ke header. Server akan kirim Warning: 299 response header.

API Key Scopes

Scope	Akses
`full`	Semua endpoint (read + write). Default untuk web user.
`readonly`	Hanya endpoint baca: getBalance, getPrices, getStatus, getHistory.

Base URL

Semua endpoint menggunakan format query-string action. Base URL:

https://nokos.co.id/api/?action=<ACTION>

Contoh request:

GET https://nokos.co.id/api/?action=getBalance
POST https://nokos.co.id/api/?action=getNumber
GET https://nokos.co.id/api/?action=getStatus&id=12345

Server Selection

Nokos.co.id mengoperasikan 2 server pengiriman dengan stok & tarif yang independen. Pilih server lewat parameter server pada endpoint getPrices, getAvailability, dan getNumber.

Server Plus

server=s2

Default

Server utama dengan tarif paling kompetitif. Stok lengkap untuk WhatsApp, Telegram, Shopee, dan banyak negara internasional.

Server Express

server=s1

Server alternatif dengan kualitas pengiriman berbeda. Pakai untuk bandingkan respons time atau saat Server Plus lagi penuh / kosong stok.

Tarif & stok berbeda per server

Layanan yang sama bisa punya tarif & ketersediaan stok yang berbeda di tiap server. Cek harga di kedua server untuk dapat penawaran terbaik:

# Cek harga WhatsApp Indonesia di Server Plus (default, paling hemat)
curl "https://nokos.co.id/api/?action=getPrices&service=wa&country=6&server=s2" \
  -H "X-API-Key: YOUR_API_KEY"

# Cek harga di Server Express
curl "https://nokos.co.id/api/?action=getPrices&service=wa&country=6&server=s1" \
  -H "X-API-Key: YOUR_API_KEY"

Catatan: Untuk endpoint getStatus, setStatus, dan cancelActivation kamu tidak perlu kirim parameter server — sistem otomatis pakai server yang sama dengan saat getNumber dipanggil.

Kalau parameter server tidak dikirim atau tidak valid, sistem default ke s2 (Server Plus).

GET

getBalance

Cek saldo akun saat ini (dalam Rupiah).

Request

curl "https://nokos.co.id/api/?action=getBalance" \
  -H "X-API-Key: YOUR_API_KEY"

Response

{
  "success": true,
  "data": { "balance": 50000 }
}

GET

getServices

List 478+ layanan yang tersedia (WhatsApp, Telegram, Tinder, dll).

curl "https://nokos.co.id/api/?action=getServices" \
  -H "X-API-Key: YOUR_API_KEY"

Response

{
  "success": true,
  "data": [
    { "code": "wa", "name": "WhatsApp" },
    { "code": "tg", "name": "Telegram" },
    { "code": "oi", "name": "Tinder" }
  ]
}

GET

getCountries

List 76+ negara yang didukung beserta kode-nya.

curl "https://nokos.co.id/api/?action=getCountries" \
  -H "X-API-Key: YOUR_API_KEY"

Response

{
  "success": true,
  "data": [
    { "id": 6, "name": "Indonesia", "prefix": "+62" },
    { "id": 0, "name": "Russia",    "prefix": "+7" },
    { "id": 187,"name": "USA",       "prefix": "+1" }
  ]
}

GET

getPrices

Cek harga real-time untuk service + country tertentu.

Penting: cost dalam response ini masih dalam USD (harga provider + markup, belum dikonversi). Untuk dapat harga Rupiah final: harga_rupiah = round(cost * usd_idr_rate), pakai field usd_idr_rate yang ada di response yang sama.

Parameters

Param	Type	Required	Description
`service`	string	No	Service code (e.g. `wa`). Empty = semua.
`country`	int	No	Country ID (e.g. `6` for Indonesia)
`server`	string	No	`s2` = Server Plus (default), `s1` = Server Express. Lihat Server Selection.

curl "https://nokos.co.id/api/?action=getPrices&service=wa&country=6&server=s2" \
  -H "X-API-Key: YOUR_API_KEY"

Response

{
  "success": true,
  "prices": {
    "6": {
      "wa": { "cost": 0.24, "count": 63591 }
    }
  },
  "markup": 60,
  "usd_idr_rate": 17830.69
}

Contoh di atas: round(0.24 * 17830.69) = Rp 4.279 per nomor.

GET

getAvailability

Cek stok real-time untuk service+country tertentu.

Tip: endpoint getPrices sudah mengembalikan count (stok) bersamaan dengan cost per service — untuk kebanyakan kebutuhan itu cukup, tanpa perlu panggil getAvailability terpisah.

Parameters

Param	Type	Required	Description
`service`	string	No	Belum difilter oleh server saat ini — response selalu berisi semua service. Cari key service kamu (mis. `wa`) di object hasil.
`country`	int	No	Country ID. Default: 6 (Indonesia)
`server`	string	No	`s2` (default) atau `s1`

curl "https://nokos.co.id/api/?action=getAvailability&country=6&server=s2" \
  -H "X-API-Key: YOUR_API_KEY"

# Response — flat map of ALL service codes -> stock count for that country
# (the "service" param is currently not applied as a filter; look up your
# service's key, e.g. "wa", in the returned object):
{
  "success": true,
  "availability": { "wa": 63466, "tg": 81072, "...": "(all other service codes)" }
}

POST

getNumber

Memerlukan scope full

Order nomor virtual untuk service+country target. Saldo akan dipotong otomatis.

Parameters

Param	Required	Description
`service`	Yes	Service code (e.g. `wa`)
`country`	No	Country ID. Default: 6 (Indonesia)
`operator`	No	Operator filter, contoh `telkomsel`, `indosat`, `xl` (default: `any`)
`server`	No	`s2` = Server Plus (default, paling hemat) atau `s1` = Server Express. Lihat Server Selection.

curl -X POST "https://nokos.co.id/api/?action=getNumber" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "service=wa&country=6&operator=telkomsel&server=s2"

Response

{
  "success": true,
  "data": {
    "activation_id": 38496653,
    "phone": "6281234567890",
    "price": 250,
    "expires_at": "2026-05-04 12:30:00"
  }
}

Idempotency

Untuk mencegah double-purchase saat retry, kirim header:

X-Idempotency-Key: unique-string-max-100-chars

GET

getStatus

Cek status aktivasi (apakah OTP sudah masuk).

curl "https://nokos.co.id/api/?action=getStatus&id=38496653" \
  -H "X-API-Key: YOUR_API_KEY"

Response (waiting)

{
  "success": true,
  "data": { "status": "STATUS_WAIT_CODE" }
}

Response (OTP received)

{
  "success": true,
  "data": {
    "status": "STATUS_OK",
    "code": "482910",
    "sms": "Your WhatsApp code: 482910"
  }
}

POST

setStatus

Update status aktivasi (cancel, finish, atau request another SMS).

Status Values

Status	Action
`-1`	Cancel activation
`3`	Request another SMS code
`6`	Finish/complete activation
`8`	Cancel activation

curl -X POST "https://nokos.co.id/api/?action=setStatus" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d "id=38496653&status=6"

POST

cancelActivation

Shortcut untuk cancel aktivasi. Refund 100% jika OTP belum diterima.

curl -X POST "https://nokos.co.id/api/?action=cancelActivation" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d "id=38496653"

GET

getHistory

Riwayat aktivasi user (paginated).

Parameters

limit — int (default 20, max 100)
offset — int (default 0)
status — filter (pending, received, cancelled)

curl "https://nokos.co.id/api/?action=getHistory&limit=20&offset=0" \
  -H "X-API-Key: YOUR_API_KEY"

POST

createDeposit

Full scope only

Buat transaksi deposit baru. Server akan generate QRIS code dan return URL gambar QR yang siap dipindai user. Setelah dibayar, saldo otomatis terkredit ke akun.

Body Parameters

amount — int (required). Nominal deposit dalam Rupiah. Min Rp 10.000, max Rp 10.000.000.

Headers

X-API-Key — API key (required, scope full)
Idempotency-Key — string (optional, recommended). Hindari double-create kalau request retry.

Request

curl -X POST "https://nokos.co.id/api/?action=createDeposit" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Idempotency-Key: deposit-19c4c23c" \
  -d "amount=50000"

Response 200

{
  "success": true,
  "data": {
    "transaction_id": "DPS-20260504-AB12CD",
    "qris_url": "data:image/png;base64,iVBORw0KGgo...", // Gambar QRIS (PNG)
    "amount": 50000,           // Saldo masuk (sudah include bonus jika ada)
    "pay_amount": 50000,       // Yang user bayar
    "expires_at": "2026-05-04 14:30:00",
    "bonus_percent": 5,        // Optional, hanya muncul jika ada bonus
    "bonus_amount": 2500        // Optional
  }
}

Catatan Penting

Rate limit: max 1 deposit baru per 30 detik per user.
Max 3 deposit pending aktif. Selesaikan / tunggu expired sebelum buat lagi.
QRIS biasanya expired dalam 15 menit. Cek field expires_at untuk waktu pasti.
Saldo otomatis terkredit via callback gateway saat dibayar — tidak perlu polling, tapi bisa pakai checkDeposit untuk konfirmasi manual.
Setup webhook di dashboard untuk notifikasi real-time saat deposit paid (event deposit.paid).

GET

checkDeposit

Cek status deposit. Jika masih pending, server otomatis re-check ke gateway QRIS. Aman dipanggil dari readonly key.

Parameters

transaction_id — string (required). ID dari response createDeposit.

Request

curl "https://nokos.co.id/api/?action=checkDeposit&transaction_id=DPS-20260504-AB12CD" \
  -H "X-API-Key: YOUR_API_KEY"

Response 200

{
  "success": true,
  "data": {
    "transaction_id": "DPS-20260504-AB12CD",
    "amount": 50000,
    "pay_amount": 50000,
    "status": "paid",        // pending | paid | expired | failed
    "expires_at": "2026-05-04 14:30:00",
    "paid_at": "2026-05-04 14:21:33",
    "created_at": "2026-05-04 14:15:00"
  }
}

Status Values

Status	Arti
`pending`	Menunggu pembayaran user.
`paid`	Sudah dibayar, saldo sudah terkredit.
`expired`	QRIS kadaluarsa, tidak terbayar.
`failed`	Pembayaran ditolak gateway.

Error Codes

Semua error response menggunakan format konsisten:

{
  "success": false,
  "error": "Pesan error dalam Bahasa Indonesia"
}

Common Errors

HTTP	Error	Penyebab
401	API key tidak valid	Header X-API-Key salah/kosong
403	IP not in whitelist	IP whitelist diaktifkan, IP request tidak terdaftar
403	Scope read-only	Endpoint write dipanggil dengan readonly key
405	Method not allowed	getNumber/setStatus harus POST
429	Too many requests	Rate limit tercapai
400	NO_NUMBERS	Stok kosong untuk service+country
400	Insufficient balance	Saldo kurang untuk order

Rate Limits

60 requests/menit per IP (untuk endpoint baca)
3 detik cooldown antar getNumber per user (anti-spam)
10 attempts/5 menit untuk auth gagal per IP

Saat rate limit tercapai, response akan return 429 Too Many Requests dengan pesan rate limit. Tunggu sesuai window dan retry.

Code Samples

Contoh integrasi lengkap dalam beberapa bahasa pemrograman populer.

PHP

<?php
$apiKey = 'YOUR_API_KEY';
$baseUrl = 'https://nokos.co.id/api/';

// 1. Cek saldo
$ch = curl_init($baseUrl . '?action=getBalance');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => ['X-API-Key: ' . $apiKey],
]);
$resp = json_decode(curl_exec($ch), true);
echo "Saldo: Rp " . $resp['data']['balance'];

// 2. Order nomor WhatsApp Indonesia (server=s2 = Server Plus, paling hemat)
$ch = curl_init($baseUrl . '?action=getNumber');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST           => true,
    CURLOPT_POSTFIELDS     => http_build_query([
        'service'  => 'wa',
        'country'  => 6,
        'server'   => 's2',
    ]),
    CURLOPT_HTTPHEADER     => ['X-API-Key: ' . $apiKey],
]);
$order = json_decode(curl_exec($ch), true);
$activationId = $order['data']['activation_id'];

// 3. Polling status sampai OTP masuk
while (true) {
    $ch = curl_init($baseUrl . "?action=getStatus&id={$activationId}");
    curl_setopt_array($ch, [
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_HTTPHEADER     => ['X-API-Key: ' . $apiKey],
    ]);
    $status = json_decode(curl_exec($ch), true);
    if ($status['data']['status'] === 'STATUS_OK') {
        echo "OTP Code: " . $status['data']['code'];
        break;
    }
    sleep(3);
}

Python

import requests
import time

API_KEY = 'YOUR_API_KEY'
BASE_URL = 'https://nokos.co.id/api/'
HEADERS = {'X-API-Key': API_KEY}

# 1. Cek saldo
r = requests.get(BASE_URL, params={'action': 'getBalance'}, headers=HEADERS).json()
print(f"Saldo: Rp {r['data']['balance']}")

# 2. Order nomor (server=s2 = Server Plus, paling hemat)
r = requests.post(BASE_URL, params={'action': 'getNumber'},
                  data={'service': 'wa', 'country': 6, 'server': 's2'},
                  headers=HEADERS).json()
activation_id = r['data']['activation_id']
phone = r['data']['phone']
print(f"Phone: {phone}, ID: {activation_id}")

# 3. Polling OTP
while True:
    r = requests.get(BASE_URL, params={'action': 'getStatus', 'id': activation_id},
                     headers=HEADERS).json()
    if r['data']['status'] == 'STATUS_OK':
        print(f"OTP: {r['data']['code']}")
        break
    time.sleep(3)

Node.js

const apiKey = 'YOUR_API_KEY';
const baseUrl = 'https://nokos.co.id/api/';
const headers = { 'X-API-Key': apiKey };

// 1. Cek saldo
const balanceRes = await fetch(`${baseUrl}?action=getBalance`, { headers });
const { data: balance } = await balanceRes.json();
console.log(`Saldo: Rp ${balance.balance}`);

// 2. Order nomor
// server=s2 (Server Plus, paling hemat) — pakai s1 untuk Server Express
const orderRes = await fetch(`${baseUrl}?action=getNumber`, {
    method: 'POST',
    headers: { ...headers, 'Content-Type': 'application/x-www-form-urlencoded' },
    body: 'service=wa&country=6&server=s2'
});
const { data: order } = await orderRes.json();
console.log(`Phone: ${order.phone}`);

// 3. Polling
while (true) {
    const r = await fetch(`${baseUrl}?action=getStatus&id=${order.activation_id}`, { headers });
    const { data } = await r.json();
    if (data.status === 'STATUS_OK') {
        console.log(`OTP: ${data.code}`);
        break;
    }
    await new Promise(r => setTimeout(r, 3000));
}

API Documentation
NOKOS REST API

Quick Start

Authentication

Recommended: HTTP Header

Alternative: Bearer Token

API Key Scopes

Base URL

Server Selection

Endpoints

getBalance

getServices

getCountries

getPrices

getAvailability

getNumber

getStatus

setStatus

cancelActivation

getHistory

Deposit / Top Up Saldo

createDeposit

checkDeposit

Error Codes

Common Errors

Rate Limits

Code Samples

PHP

Python

Node.js

Siap Mulai Integrasi?

API Documentation NOKOS REST API

Quick Start

Authentication

Recommended: HTTP Header

Alternative: Bearer Token

API Key Scopes

Base URL

Server Selection

Endpoints

getBalance

getServices

getCountries

getPrices

getAvailability

getNumber

getStatus

setStatus

cancelActivation

getHistory

Deposit / Top Up Saldo

createDeposit

checkDeposit

Error Codes

Common Errors

Rate Limits

Code Samples

PHP

Python

Node.js

Siap Mulai Integrasi?

API Documentation
NOKOS REST API