Telekos Developer API

REST API untuk membeli nomor OTP (SMS) Server 1–3 secara otomatis dari program kamu.

Base URL: https://dev.telekos.id/v1

Pendahuluan

API ini memakai akun bot Telekos kamu yang sudah ada. Artinya:

• Saldo & harga ikut akun bot kamu. Kamu top up lewat bot seperti biasa; setiap order lewat API memotong saldo yang sama.
• Harga = harga Telekos (sudah termasuk diskon level akunmu). Kalau akunmu VIP, harga API ikut turun otomatis.
• Markup ke pelangganmu urusanmu. Kamu jual ke customer-mu dengan harga berapapun — selisihnya keuntunganmu. Telekos tidak ikut campur.
• Progres level tetap jalan. Pembelian lewat API dihitung sama seperti pembelian di bot.

Semua request & response memakai application/json. Semua nominal dalam Rupiah (integer), tanpa desimal. Semua waktu format ISO 8601 UTC (contoh 2026-11-05T16:04:00Z).

Quickstart

Dari nol sampai dapat OTP dalam 3 langkah:

1. Ambil API key

Di bot @TelekosOtpBot, buka menu Lainnya → API Developer → Buat API Key. Key berupa string acak (mis. Jaozb72habB2kbUwbakz), muncul sekali — simpan baik-baik.

2. Cek akun kamu

curl https://dev.telekos.id/v1/me \
  -H "Authorization: Bearer Jaozb72habB2kbUwbakz"

3. Beli nomor & ambil OTP

# Beli nomor WhatsApp Indonesia di Server 1
curl -X POST https://dev.telekos.id/v1/orders \
  -H "Authorization: Bearer Jaozb72habB2kbUwbakz" \
  -H "Idempotency-Key: 1b9f0c7a-order-01" \
  -H "Content-Type: application/json" \
  -d '{"server":1,"service":"wa","country":"ID"}'

# Response memberi order id + nomor. OTP datang beberapa detik/menit kemudian:
curl https://dev.telekos.id/v1/orders/TRX-18472993 \
  -H "Authorization: Bearer Jaozb72habB2kbUwbakz"

Autentikasi

Setiap request wajib membawa API key pada header:

Authorization: Bearer Jaozb72habB2kbUwbakz

Harga & Saldo

Harga tidak dikirim oleh kamu — harga selalu ditentukan server. Sebelum order, cek harga real-time lewat GET /stock. Harga yang dikembalikan sudah termasuk diskon level akunmu, dan nominal itulah yang dipotong saat order dibuat (snapshot — perubahan harga setelahnya tidak memengaruhi order yang sudah jalan).

Order memotong saldo saat nomor berhasil dialokasikan. Kalau OTP tidak pernah masuk sampai kedaluwarsa, atau order dibatalkan sesuai aturan, saldo dikembalikan otomatis.

Alur Pembelian OTP

Cabang lain:

• OTP tak kunjung datang (15 menit) → status expired, saldo otomatis kembali.
• Kamu batalkan (setelah batas waktu minimum) → status cancelled, saldo kembali.

Nomor OTP aktif 15 menit sejak dialokasikan.

Status Order

Nomor telepon selalu dikirim dalam format E.164 (contoh +6281234567890).

Idempotency

Endpoint yang memotong saldo (POST /orders) menerima header wajib-disarankan:

Idempotency-Key: <string unik per order, mis. UUID>

Kalau request gagal di tengah jalan (timeout jaringan) lalu kamu kirim ulang dengan key yang sama, server mengembalikan order yang sama — tidak membuat order kedua dan tidak memotong saldo dua kali. Key berlaku 24 jam.

Webhook

Daftarkan satu URL HTTPS dari bot (menu API Developer). Saat status order berubah, kami POST ke URL itu:

POST https://servermu.com/telekos-webhook
X-Telekos-Event: otp.received
X-Telekos-Signature: t=1793850000,v1=5f2b...e9  (HMAC-SHA256)

{
  "event": "otp.received",
  "created_at": "2026-11-05T16:05:12Z",
  "data": {
    "id": "TRX-18472993",
    "status": "received",
    "phone": "+6281234567890",
    "otp": "123456",
    "service": "wa",
    "server": 1,
    "country": "ID"
  }
}

Event

Verifikasi tanda tangan

Hitung HMAC-SHA256 dari string "{t}.{raw_body}" memakai webhook secret-mu, bandingkan dengan v1. Tolak kalau t lebih dari 5 menit (anti-replay).

Rate Limit

Saat kena limit, respons 429 disertai header Retry-After: <detik>. Hormati nilai itu sebelum mencoba lagi.

Format & Kode Error

Semua error memakai bentuk yang sama, dengan HTTP status yang sesuai:

{
  "error": {
    "code": "INSUFFICIENT_BALANCE",
    "message": "Saldo tidak cukup untuk harga Rp 5.000",
    "detail": { "price": 5000, "balance": 1200 }
  }
}

GET /me

Info akun pemilik key: saldo, level, status.

Response 200

{
  "account": {
    "id": 8923762632,
    "level": "VIP1",
    "discount_percent": 0,
    "balance": 134309,
    "currency": "IDR",
    "test_mode": false
  }
}

GET /servers

Daftar server beserta status aktif/maintenance.

Response 200

{
  "servers": [
    { "id": 1, "name": "Server 1", "enabled": true,  "maintenance": false },
    { "id": 2, "name": "Server 2", "enabled": true,  "maintenance": false },
    { "id": 3, "name": "Server 3", "enabled": true,  "maintenance": false }
  ]
}

GET /services

Response 200

{
  "services": [
    { "code": "wa", "name": "WhatsApp" },
    { "code": "tg", "name": "Telegram" },
    { "code": "ig", "name": "Instagram+Threads" },
    { "code": "go", "name": "Google / YouTube / Gmail" }
  ]
}

Lihat daftar kode layanan lengkap di bawah.

GET /stock

Cek ketersediaan dan harga untuk akunmu sebelum order.

Response 200

{
  "available": true,
  "price": 5000,
  "currency": "IDR",
  "country": { "iso": "ID", "name": "Indonesia", "dial": "+62" }
}

Kalau stok kosong: { "available": false, "price": null }.

POST /orders

Buat order baru — mengalokasikan nomor dan memotong saldo.

Header

Body

Response 201

{
  "id": "TRX-18472993",
  "status": "waiting",
  "phone": "+6281234567890",
  "server": 1,
  "service": "wa",
  "country": "ID",
  "price": 5000,
  "currency": "IDR",
  "otp": null,
  "created_at": "2026-11-05T16:04:00Z",
  "expires_at": "2026-11-05T16:19:00Z",
  "cancellable_in": 180
}

Error yang mungkin

402 INSUFFICIENT_BALANCE · 422 NO_STOCK · 429 QUOTA_EXCEEDED · 503 SERVER_MAINTENANCE

GET /orders/:id

Cek status & OTP satu order. Inilah endpoint polling-mu.

Response 200 — menunggu

{
  "id": "TRX-18472993",
  "status": "waiting",
  "phone": "+6281234567890",
  "otp": null,
  "price": 5000,
  "refunded": false,
  "expires_at": "2026-11-05T16:19:00Z",
  "cancellable_in": 42
}

Response 200 — OTP masuk

{
  "id": "TRX-18472993",
  "status": "received",
  "phone": "+6281234567890",
  "otp": "123456",
  "otp_received_at": "2026-11-05T16:05:12Z",
  "price": 5000,
  "refunded": false
}

POST /orders/:id/cancel

Batalkan order yang belum menerima OTP. Saldo dikembalikan bila berhasil.

Response 200

{ "id": "TRX-18472993", "status": "cancelled", "refunded": true, "amount": 5000 }

Response 409

{ "error": { "code": "CANCEL_TOO_EARLY",
    "message": "Belum bisa dibatalkan, tunggu 118 detik",
    "detail": { "cancellable_in": 118 } } }

GET /orders

Riwayat order, terbaru dulu.

Response 200

{
  "orders": [ { "id": "TRX-18472993", "status": "received", "...": "..." } ],
  "next_cursor": "eyJvZmZzZXQiOjIwfQ"
}

Daftar Layanan (contoh)

Kode layanan mengikuti katalog hidup — selalu ambil terbaru dari GET /services. Sebagian yang umum:

Test Mode

Key test membuat order simulasi: order dibuat, OTP palsu dikirim setelah beberapa detik, tanpa memanggil penyedia asli dan tanpa memotong saldo nyata. Pakai ini untuk mengembangkan integrasimu tanpa membakar saldo. Key test disediakan lewat admin bot.

FAQ

Kenapa order saya langsung NO_STOCK?

Stok penyedia untuk kombinasi server+layanan+negara itu sedang kosong. Coba server atau negara lain, atau cek GET /stock dulu.

OTP tidak masuk, saldo saya gimana?

Kalau 15 menit lewat tanpa OTP, order jadi expired dan saldo otomatis kembali. Kamu tidak perlu melakukan apa-apa.

Boleh pasang harga sendiri ke pelanggan saya?

Boleh dan memang begitu caranya. Telekos hanya memotong harga dasar (sesuai levelmu) dari saldomu. Markup ke pelangganmu sepenuhnya urusanmu.

Bagaimana cegah saya kena charge dua kali?

Selalu kirim Idempotency-Key yang unik per order. Retry dengan key sama tidak akan membuat order kedua.

Telekos Developer API · v1 (beta) · dukungan: lewat bot @TelekosOtpBot.