Panduan Lengkap API SMSCode untuk Developer — 2026

Kalau kamu developer yang butuh verifikasi SMS secara programatis — untuk QA testing, automation, atau integrasi ke pipeline CI/CD — SMSCode menyediakan REST API yang bisa kamu pakai langsung dari kode. Beli nomor, polling OTP, cancel order: semuanya tersedia via API dengan response JSON yang konsisten.

Artikel ini adalah panduan teknis lengkap: dari setup autentikasi, endpoint yang tersedia, contoh kode, sampai tips praktis untuk production.

TL;DR: SMSCode punya REST API dengan bearer token auth. Tiga endpoint utama: /v1/catalog (lihat nomor tersedia), /v1/orders (beli nomor), dan polling status order untuk ambil OTP. Mulai dari Rp 75 per nomor, gratis daftar, langsung bisa coba.

Kenapa Developer Butuh API Nomor Virtual?

Sebelum masuk ke teknisnya, ini beberapa use case yang paling umum dari developer yang pakai API SMSCode:

QA Testing dan End-to-End Testing. Kalau kamu develop aplikasi yang butuh verifikasi nomor HP (signup flow, 2FA, dll), kamu butuh nomor nyata untuk testing. Pakai nomor pribadimu buat testing production berisiko dan tidak scalable. Dengan API, kamu bisa generate nomor baru untuk setiap test run secara otomatis.

CI/CD Pipeline. Integrasikan verifikasi SMS ke pipeline continuous integration. Setiap kali ada perubahan di flow autentikasi, test otomatis jalan dengan nomor virtual fresh — tanpa intervensi manual.

Automation untuk akun-akun layanan. Kalau kamu perlu mendaftarkan beberapa akun di layanan tertentu sebagai bagian dari setup infrastruktur (monitoring, testing environment, dll), API memungkinkan proses ini diautomasi.

Research dan data collection. Developer yang butuh akun di berbagai platform untuk research atau data scraping (sesuai ToS platform tersebut) bisa automasikan proses pendaftaran.

Layanan SaaS yang integrasikan verifikasi SMS. Kalau kamu build SaaS dan perlu menawarkan fitur “verifikasi nomor” ke pengguna kamu, SMSCode API bisa jadi backend-nya.

Autentikasi — Bearer Token

SMSCode API menggunakan Bearer Token untuk autentikasi. Token ini unik per akun dan tidak boleh di-share atau di-expose ke client-side.

Cara dapat API token:

1. Daftar akun di smscode.gg/auth/signup
2. Login ke dashboard
3. Buka menu “API” atau “Pengaturan Akun”
4. Copy API token kamu

Format header autentikasi:

Authorization: Bearer YOUR_API_TOKEN

Semua endpoint API wajib menyertakan header ini. Request tanpa token atau dengan token invalid akan mendapat response 401 Unauthorized.

Keamanan token:

• Jangan commit token ke repository (gunakan environment variable)
• Jangan expose token di frontend atau client-side code
• Rotasi token kalau dicurigai bocor — hubungi support SMSCode

Base URL dan Format Response

Base URL:

https://api.smscode.gg/v1

Semua endpoint di bawah ini menggunakan base URL tersebut.

Format response sukses:

{
  "success": true,
  "data": { ... }
}

Format response error:

{
  "success": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "Deskripsi error"
  }
}

Format ini konsisten di semua endpoint — mudah untuk error handling di kode kamu.

Endpoint 1 — Catalog: Cek Nomor yang Tersedia

Sebelum beli nomor, kamu perlu tahu layanan apa yang tersedia dan harganya.

GET /v1/catalog

Query parameters (semua opsional):

• country — filter berdasarkan kode negara (ISO 3166-1 alpha-2, misalnya id untuk Indonesia, us untuk Amerika Serikat)
• service — filter berdasarkan nama layanan (misalnya instagram, whatsapp, telegram)
• limit — jumlah hasil per halaman (default: 50)
• offset — offset untuk pagination

Contoh request dengan curl:

curl -X GET "https://api.smscode.gg/v1/catalog?service=instagram&country=us" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Contoh response:

{
  "success": true,
  "data": {
    "items": [
      {
        "id": "prod_abc123",
        "service": "instagram",
        "country": "us",
        "country_name": "United States",
        "price": 150,
        "currency": "IDR",
        "available": true,
        "stock": "high"
      },
      {
        "id": "prod_def456",
        "service": "instagram",
        "country": "gb",
        "country_name": "United Kingdom",
        "price": 120,
        "currency": "IDR",
        "available": true,
        "stock": "medium"
      }
    ],
    "total": 2
  }
}

Contoh dengan Python:

import requests

API_TOKEN = "your_api_token_here"
BASE_URL = "https://api.smscode.gg/v1"

headers = {
    "Authorization": f"Bearer {API_TOKEN}"
}

def get_catalog(service=None, country=None):
    params = {}
    if service:
        params["service"] = service
    if country:
        params["country"] = country

    response = requests.get(
        f"{BASE_URL}/catalog",
        headers=headers,
        params=params
    )
    response.raise_for_status()
    return response.json()

# Cari nomor Indonesia untuk Instagram
catalog = get_catalog(service="instagram", country="id")
print(catalog["data"]["items"])

Endpoint 2 — Orders: Beli Nomor Virtual

Setelah tahu product ID dari catalog, kamu bisa buat order untuk mendapatkan nomor virtual.

POST /v1/orders

Request body (JSON):

{
  "product_id": "prod_abc123"
}

Contoh request dengan curl:

curl -X POST "https://api.smscode.gg/v1/orders" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"product_id": "prod_abc123"}'

Contoh response (order berhasil dibuat):

{
  "success": true,
  "data": {
    "order_id": "ord_xyz789",
    "phone_number": "+14155552671",
    "country": "us",
    "service": "instagram",
    "status": "pending",
    "expires_at": "2026-03-15T10:35:00Z",
    "price": 150,
    "currency": "IDR"
  }
}

Contoh dengan Python:

def create_order(product_id):
    payload = {"product_id": product_id}

    response = requests.post(
        f"{BASE_URL}/orders",
        headers={**headers, "Content-Type": "application/json"},
        json=payload
    )
    response.raise_for_status()
    return response.json()

# Beli nomor untuk Instagram US
order = create_order("prod_abc123")
print(f"Nomor: {order['data']['phone_number']}")
print(f"Order ID: {order['data']['order_id']}")

Endpoint 3 — Polling Status Order dan Ambil OTP

Setelah beli nomor dan masukkan ke layanan target, kamu perlu polling status order untuk menunggu OTP masuk.

GET /v1/orders/{order_id}

Contoh request dengan curl:

curl -X GET "https://api.smscode.gg/v1/orders/ord_xyz789" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Contoh response (OTP sudah masuk):

{
  "success": true,
  "data": {
    "order_id": "ord_xyz789",
    "phone_number": "+14155552671",
    "status": "completed",
    "sms_code": "847293",
    "sms_text": "Instagram: Your OTP code is 847293",
    "received_at": "2026-03-15T10:33:45Z",
    "expires_at": "2026-03-15T10:35:00Z"
  }
}

Status order yang mungkin:

• pending — order aktif, menunggu OTP
• completed — OTP berhasil diterima (lihat sms_code)
• cancelled — order dibatalkan (saldo dikembalikan)
• expired — order habis masa aktifnya tanpa OTP masuk (saldo dikembalikan)

Implementasi polling dengan Python:

import time

def poll_for_otp(order_id, timeout_seconds=120, poll_interval=5):
    """
    Poll status order sampai OTP masuk atau timeout.

    Args:
        order_id: ID order yang mau di-poll
        timeout_seconds: Maksimum waktu tunggu (default 120 detik)
        poll_interval: Interval polling dalam detik (default 5 detik)

    Returns:
        SMS code kalau berhasil, None kalau timeout
    """
    start_time = time.time()

    while time.time() - start_time < timeout_seconds:
        response = requests.get(
            f"{BASE_URL}/orders/{order_id}",
            headers=headers
        )
        response.raise_for_status()
        data = response.json()["data"]

        if data["status"] == "completed":
            return data["sms_code"]
        elif data["status"] in ["cancelled", "expired"]:
            return None

        # Masih pending, tunggu sebentar
        time.sleep(poll_interval)

    return None  # Timeout

# Contoh penggunaan lengkap
def verify_instagram_account():
    # 1. Cek catalog
    catalog = get_catalog(service="instagram", country="us")
    if not catalog["data"]["items"]:
        raise Exception("Tidak ada nomor tersedia")

    product_id = catalog["data"]["items"][0]["id"]

    # 2. Buat order
    order = create_order(product_id)
    order_id = order["data"]["order_id"]
    phone_number = order["data"]["phone_number"]

    print(f"Gunakan nomor ini di Instagram: {phone_number}")

    # 3. [Di sini: masukkan nomor ke Instagram via Selenium/Playwright]
    # submit_number_to_instagram(phone_number)

    # 4. Poll untuk OTP
    otp = poll_for_otp(order_id)

    if otp:
        print(f"OTP berhasil diterima: {otp}")
        return otp
    else:
        print("OTP tidak masuk dalam batas waktu")
        return None

Endpoint 4 — Cancel Order

Kalau kamu sudah tidak butuh nomor tersebut (misalnya layanan target sedang down atau kamu mau coba nomor lain), kamu bisa cancel order untuk mendapatkan saldo kembali.

DELETE /v1/orders/{order_id}

curl -X DELETE "https://api.smscode.gg/v1/orders/ord_xyz789" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Order hanya bisa di-cancel kalau masih dalam status pending dan belum menerima OTP.

Endpoint 5 — Cek Saldo

Monitoring saldo akun penting untuk automation — pastikan ada cukup saldo sebelum buat order.

GET /v1/balance

curl -X GET "https://api.smscode.gg/v1/balance" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Response:

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

Saldo dalam satuan Rupiah. Integrasikan ke monitoring script kamu untuk alerting kalau saldo di bawah threshold tertentu.

Rate Limits

SMSCode API memiliki rate limit untuk mencegah abuse:

Endpoint	Limit
GET /v1/catalog	60 request/menit
POST /v1/orders	20 order/menit
GET /v1/orders/{id}	120 request/menit
DELETE /v1/orders/{id}	20 request/menit
GET /v1/balance	60 request/menit

Kalau kamu melebihi rate limit, API akan return 429 Too Many Requests dengan header Retry-After yang menunjukkan berapa detik harus menunggu sebelum request berikutnya.

Best practice untuk polling: Jangan polling terlalu agresif — interval 5 detik sudah cukup untuk sebagian besar use case. OTP biasanya masuk dalam 30-120 detik setelah nomor dimasukkan ke layanan target.

Error Handling yang Baik

Implementasi production harus handle error dengan benar. Berikut error codes yang umum:

HTTP Status	Error Code	Keterangan
400	INVALID_REQUEST	Parameter request tidak valid
401	UNAUTHORIZED	Token tidak valid atau tidak ada
402	INSUFFICIENT_BALANCE	Saldo tidak cukup
404	NOT_FOUND	Order atau product tidak ditemukan
409	ALREADY_CANCELLED	Order sudah di-cancel
429	RATE_LIMITED	Melebihi rate limit
500	SERVER_ERROR	Error di sisi server

def safe_api_call(func, *args, **kwargs):
    """Wrapper untuk handle error API dengan baik."""
    try:
        return func(*args, **kwargs)
    except requests.exceptions.HTTPError as e:
        response = e.response
        if response.status_code == 402:
            print("Saldo tidak cukup. Top up dulu di smscode.gg")
        elif response.status_code == 429:
            retry_after = int(response.headers.get("Retry-After", 60))
            print(f"Rate limited. Tunggu {retry_after} detik")
            time.sleep(retry_after)
        elif response.status_code == 500:
            print("Server error. Coba lagi dalam beberapa saat")
        else:
            error_data = response.json()
            print(f"API error: {error_data['error']['message']}")
        raise

Contoh Integrasi Lengkap: Pytest + SMSCode

Berikut contoh lengkap bagaimana mengintegrasikan SMSCode ke test suite Python pakai pytest:

# tests/conftest.py
import pytest
import requests
import time

SMSCODE_TOKEN = os.environ["SMSCODE_API_TOKEN"]
SMSCODE_BASE = "https://api.smscode.gg/v1"

@pytest.fixture
def sms_number():
    """Fixture yang menyediakan nomor virtual dan OTP untuk test."""
    headers = {"Authorization": f"Bearer {SMSCODE_TOKEN}"}

    # Cek catalog
    catalog = requests.get(
        f"{SMSCODE_BASE}/catalog",
        headers=headers,
        params={"service": "your_service_name", "country": "id"}
    ).json()

    product_id = catalog["data"]["items"][0]["id"]

    # Buat order
    order = requests.post(
        f"{SMSCODE_BASE}/orders",
        headers=headers,
        json={"product_id": product_id}
    ).json()

    order_id = order["data"]["order_id"]
    phone = order["data"]["phone_number"]

    yield phone  # Kasih nomor ke test

    # Polling OTP setelah yield (test sudah submit nomor ke layanan)
    # Implementasi polling ada di test itu sendiri

# tests/test_signup.py
def test_signup_with_sms(sms_number):
    # Gunakan nomor untuk signup di aplikasi kamu
    result = your_app.signup(phone=sms_number)
    assert result.success

    # Ambil OTP dari API
    otp = poll_for_otp(result.order_id)
    assert otp is not None

    # Verifikasi OTP
    verified = your_app.verify_otp(otp)
    assert verified

Tips Keamanan untuk Production

Gunakan environment variable untuk token.

# .env (jangan commit ke git!)
SMSCODE_API_TOKEN=your_token_here

import os
API_TOKEN = os.environ["SMSCODE_API_TOKEN"]

Tambahkan SMSCODE_API_TOKEN ke .gitignore atau gunakan secrets manager. Kalau pakai GitHub Actions, simpan token di GitHub Secrets. Kalau pakai AWS, pakai AWS Secrets Manager atau Parameter Store.

Implement circuit breaker. Kalau SMSCode API sedang down atau lambat, kamu tidak mau test suite atau automation kamu terus retry tanpa henti. Implement circuit breaker pattern — setelah N kali gagal, berhenti dan alert.

Log semua order untuk audit. Simpan log order ID, nomor yang didapat, layanan yang diverifikasi, dan hasilnya. Berguna untuk debugging dan monitoring penggunaan saldo.

Use Case: Automation QA Testing dengan Playwright

# Contoh integrasi SMSCode + Playwright untuk E2E test
from playwright.sync_api import sync_playwright
import requests

def test_signup_flow():
    with sync_playwright() as p:
        browser = p.chromium.launch()
        page = browser.new_page()

        # Ambil nomor virtual
        order = create_order(product_id="prod_instagram_us")
        phone = order["data"]["phone_number"]
        order_id = order["data"]["order_id"]

        # Buka halaman signup
        page.goto("https://your-app.com/signup")
        page.fill("#phone-input", phone)
        page.click("#send-otp-button")

        # Tunggu OTP
        otp = poll_for_otp(order_id, timeout_seconds=60)
        assert otp is not None, "OTP tidak masuk"

        # Masukkan OTP
        page.fill("#otp-input", otp)
        page.click("#verify-button")

        # Verifikasi berhasil
        assert page.url == "https://your-app.com/dashboard"

        browser.close()

FAQ

Apakah API SMSCode tersedia 24/7?

Ya, API SMSCode beroperasi 24/7. Ketersediaan nomor tergantung pada stok dari provider — beberapa layanan atau negara mungkin kehabisan stok di waktu-waktu tertentu. Selalu cek catalog sebelum buat order dan handle kasus available: false.

Bagaimana cara top up saldo via API?

Top up saldo tidak tersedia via API — harus dilakukan manual melalui dashboard di smscode.gg. Untuk automation, monitor saldo via endpoint /v1/balance dan set alerting kalau saldo di bawah threshold.

Apakah ada SDK resmi untuk bahasa pemrograman tertentu?

Saat ini SMSCode belum menyediakan SDK resmi — API-nya adalah REST standar yang bisa diakses dari bahasa apapun. Contoh kode Python dan curl di artikel ini sudah cukup sebagai starting point. Komunitas mungkin sudah ada yang buat wrapper library di GitHub.

Berapa lama data order tersimpan?

Data order tersimpan di sistem SMSCode untuk keperluan audit dan dispute. Kamu bisa akses riwayat order via dashboard. Untuk keperluan audit internal kamu sendiri, simpan log order ID dan hasilnya di database atau log system kamu sendiri.

Bagaimana cara handle kalau OTP tidak masuk?

Kalau polling sampai timeout tanpa OTP: (1) cancel order via DELETE /v1/orders/{id} untuk dapatkan saldo kembali, (2) buat order baru dengan product yang sama atau negara berbeda, (3) ulangi proses. Saldo dari order yang cancelled atau expired otomatis dikembalikan.

---

Siap mulai integrasi? Daftar gratis di SMSCode, top up saldo minimal Rp 10.000, dan langsung test API dengan contoh-contoh di atas. Cek halaman pricing untuk lihat harga per layanan dan negara, atau baca panduan mengenal SMSCode untuk gambaran umum layanan. Kalau butuh jumlah order skala besar, hubungi tim SMSCode untuk enterprise pricing.