API Verifikasi SMS — Saldo dan Harga Langsung

Memulai #

Semuanya berupa JSON melalui HTTPS, diautentikasi dengan satu kunci yang Anda buat sendiri. Tidak perlu memasang SDK, tidak perlu menandatangani kontrak, tidak perlu meminta sandbox — kunci dan curl saja sudah cukup.

1 Buat kunci Buka menu akun, lalu Kunci API, lalu Buat kunci. Kunci ini ditampilkan sekali saja: kami hanya menyimpan fingerprint-nya, sehingga tidak bisa dilihat lagi setelahnya.
2 Kirim sebagai bearer token Setiap permintaan menyertakan header Authorization. Tidak ada cara lain untuk masuk — tidak ada kunci di query string, tidak ada cookie, tidak ada session.
3 Baca jawabannya Setiap respons adalah objek JSON dengan bidang ok. Ketika ok bernilai false, bidang error menjelaskan alasannya dalam string yang stabil dan dapat dibaca mesin.

Autentikasi #

Satu kunci per akun. Mengirimkannya dengan cara lain selain header di bawah ini tidak didukung — kunci di query string akan berakhir di log server, riwayat browser, dan header referrer, sehingga ditolak, bukan diterima diam-diam.

request

Authorization: Bearer sk_your_key_here

Kunci dapat berbelanja Kunci ini membaca saldo hari ini, dan kunci yang sama akan digunakan untuk memesan nomor saat fitur pemesanan tersedia. Perlakukan seperti kata sandi: jangan dimasukkan ke source control, jangan muncul di tangkapan layar, ganti daripada dibagikan. Mengganti kunci langsung menutup kunci yang lama.

Konvensi #

Konvensi
Alamat dasar	https://simsms.com/api/v1
Protokol	Hanya HTTPS. HTTP biasa akan dialihkan, dan pengalihan tersebut tidak membawa header Anda.
Format	JSON masuk, JSON keluar. Setiap respons berupa objek, tidak pernah berupa array polos.
Berhasil	HTTP 200 dengan "ok": true.
Gagal	Kode 4xx atau 5xx dengan "ok": false dan string "error" yang stabil.
Uang	Angka dalam dolar AS, tidak pernah berupa string, tidak pernah dalam sen. 0.84 berarti 84 sen.
Bidang asing	Bidang baru dapat ditambahkan ke respons mana pun. Abaikan yang tidak Anda kenali, daripada membuat proses gagal karenanya.

Error #

String error adalah bagian yang menjadi dasar percabangan. Kalimat di sampingnya untuk Anda, bukan untuk kode Anda — kalimat itu bisa diubah redaksinya; stringnya tidak.

Error
HTTP	error	Kapan
401	`missing_key`	Tidak ada header Authorization, atau bukan bearer token.
401	`bad_key`	Kunci tidak dikenali, atau sudah ditutup atau diganti.
400	`unknown_service`	Tidak ada layanan dengan kode tersebut. Kode berasal dari katalog, bukan dari nama tampilan.
404	`no_stock`	Pasangan layanan dan negara tersebut sedang tidak memiliki nomor dalam stok. Ini angka yang berubah secara langsung — bisa kembali tersedia.
404	`unknown_country`	Tidak ada negara dengan kode tersebut pada produk itu. Katalog proxy dan katalog sewa masing-masing memiliki daftarnya sendiri — panggil rute tanpa negara untuk mendapatkannya.
400	`unknown_tech`	Tidak ada generasi jaringan tersebut di negara itu. Hanya Amerika Serikat yang menjual 4g dan 5g.
429	`rate_limited`	Terlalu banyak permintaan. Header Retry-After menyatakan berapa detik harus menunggu.

Batas laju #

600 permintaan per menit, dihitung per akun, bukan per alamat. Kunci dirancang untuk berjalan dari server — satu alamat — sehingga batas per alamat akan menghukum penggunaan normal dan membiarkan kunci yang dicuri berjalan bebas di tempat lain. Melebihi batas ini, Anda akan menerima 429 dan header Retry-After dalam hitungan detik.

Endpoint #

Pembacaan akun dan katalog. Setiap rute mencantumkan setiap parameter yang diterima, setiap bidang yang dikembalikan, dan setiap error yang bisa dijawabnya — tanpa perilaku yang tidak terdokumentasi.

Baca saldo Anda #

GET /api/v1/balance

Apa yang dimiliki akun saat ini, dan berapa banyak kode yang bisa dibeli dengan harga termurah yang ada di katalog saat ini.

Bidang respons

Baca saldo Anda — Bidang respons
Bidang	Tipe	Deskripsi
`ok`	boolean	Selalu true pada 200.
`balance`	number	Dolar yang tersedia, dibulatkan ke sen terdekat.
`currency`	string	Selalu "USD". Selalu ada agar Anda tidak perlu menebaknya.
`codes_at_cheapest`	integer	Berapa banyak kode yang bisa dibeli oleh saldo tersebut dengan harga termurah di katalog. Perkiraan kasar, bukan penawaran resmi — null jika katalog kosong.
`cheapest_code`	number	Harga termurah tersebut, agar Anda bisa menghitung sendiri perkiraan itu terhadap angka lain.

Permintaan

request

curl -s "https://simsms.com/api/v1/balance" \
  -H "Authorization: Bearer $SIMSMS_KEY"

Respons

200 OK

{
  "ok": true,
  "balance": 42.5,
  "currency": "USD",
  "codes_at_cheapest": 425,
  "cheapest_code": 0.1
}

Dapat menjawab missing_key bad_key rate_limited

Harga satu layanan di satu negara #

GET /api/v1/pricing?service={service}&country={country}

Harga langsung dan stok langsung untuk satu pasangan. Kedua angka ini berubah-ubah — harga mengikuti jaringan termurah yang membawa layanan tersebut di negara itu, dan stok adalah yang dilaporkan jaringan saat ini.

Parameter

Harga satu layanan di satu negara — Parameter
Parameter		Deskripsi
`service`	wajib	Kode layanan, misalnya telegram. Huruf kecil, dari katalog.
`country`	opsional	Kode negara, misalnya england. Kosongkan untuk mendapatkan semua negara sekaligus — lihat di bawah.

Bidang respons

Harga satu layanan di satu negara — Bidang respons
Bidang	Tipe	Deskripsi
`ok`	boolean	Selalu true pada 200.
`service`	string	Kode layanan yang Anda minta, dikirim kembali apa adanya.
`country`	string	Kode negara yang Anda minta, dikirim kembali apa adanya.
`price`	number	Dolar untuk satu kode, pada jaringan termurah yang memilikinya.
`stock`	integer	Jumlah nomor yang dilaporkan tersedia saat ini. Ini angka langsung dan terus berubah.

Permintaan

request

curl -s "https://simsms.com/api/v1/pricing?service=telegram&country=england" \
  -H "Authorization: Bearer $SIMSMS_KEY"

Respons

200 OK

{
  "ok": true,
  "service": "telegram",
  "country": "england",
  "price": 0.84,
  "stock": 61213
}

Dapat menjawab missing_key bad_key unknown_service no_stock rate_limited

Harga satu layanan di semua negara #

GET /api/v1/pricing?service={service}

Hilangkan negara, dan Anda akan mendapatkan semua negara yang menyediakan layanan tersebut. Urutannya ditentukan oleh situs sendiri: yang benar-benar mengirim kode lebih dulu, lalu yang termurah di antaranya — bukan harga mentah, yang bisa menempatkan angka dua sen yang tidak pernah benar-benar mengirim kode di posisi teratas.

Parameter

Harga satu layanan di semua negara — Parameter
Parameter		Deskripsi
`service`	wajib	Kode layanan, misalnya telegram.

Bidang respons

Harga satu layanan di semua negara — Bidang respons
Bidang	Tipe	Deskripsi
`ok`	boolean	Selalu true pada 200.
`service`	string	Kode layanan yang Anda minta.
`name`	string	Nama tampilannya, misalnya "Telegram".
`countries`	array	Satu objek per negara, dengan urutan seperti dijelaskan di atas.
`countries[].country`	string	Kode negara, untuk dimasukkan kembali ke panggilan pair.
`countries[].name`	string	Nama Inggrisnya.
`countries[].price`	number	Dolar untuk satu kode.
`countries[].stock`	integer	Nomor yang tersedia saat ini.

Permintaan

request

curl -s "https://simsms.com/api/v1/pricing?service=telegram" \
  -H "Authorization: Bearer $SIMSMS_KEY"

Respons

200 OK

{
  "ok": true,
  "service": "telegram",
  "name": "Telegram",
  "countries": [
    { "country": "england", "name": "United Kingdom", "price": 0.84, "stock": 61213 },
    { "country": "poland",  "name": "Poland",         "price": 0.91, "stock": 22140 }
  ]
}

Dapat menjawab missing_key bad_key unknown_service rate_limited

Harga proxy seluler #

GET /api/v1/proxy-pricing?country={country}&tech={tech}

Tanpa negara, Anda mendapatkan empat negara tempat kami menjalankan modem, beserta jumlah operator dan harga awalnya. Dengan satu negara, semua operator di sana beserta harga tiap jangka waktu. Jangka waktu dalam hari: 1, 7, 30, 365.

Parameter

Harga proxy seluler — Parameter
Parameter		Deskripsi
`country`	opsional	Kode negara, misalnya us. Kosongkan untuk menampilkan daftar negara.
`tech`	opsional	Generasi jaringan, 4g atau 5g. Hanya Amerika Serikat yang menjual keduanya; di tempat lain, bidang ini diabaikan dan rentang tunggal yang dikembalikan.

Bidang respons

Harga proxy seluler — Bidang respons
Bidang	Tipe	Deskripsi
`ok`	boolean	Selalu true pada 200.
`country`	string	Negara yang Anda minta.
`tech`	string	Generasi yang benar-benar diberi harga, setelah nilai default diterapkan.
`techs`	array	Semua generasi yang dijual di negara tersebut.
`terms`	array	Jangka waktu yang ditawarkan, dalam hari.
`carriers`	array	Satu objek per operator.
`carriers[].carrier`	string	Kode operator, untuk dimasukkan ke dalam pesanan.
`carriers[].name`	string	Nama tampilannya, misalnya "T-Mobile".
`carriers[].prices`	object	Dolar per jangka waktu, dengan kunci berupa jumlah hari.

Permintaan

request

curl -s "https://simsms.com/api/v1/proxy-pricing?country=us" \
  -H "Authorization: Bearer $SIMSMS_KEY"

Respons

200 OK

{
  "ok": true,
  "country": "us",
  "tech": "4g",
  "techs": ["4g", "5g"],
  "terms": [1, 7, 30, 365],
  "carriers": [
    { "carrier": "us-t-mobile", "name": "T-Mobile", "prices": { "1": 8.67, "7": 52, "30": 130, "365": 1300 } },
    { "carrier": "us-verizon",  "name": "Verizon",  "prices": { "1": 8.67, "7": 52, "30": 130, "365": 1300 } }
  ]
}

Dapat menjawab missing_key bad_key unknown_country unknown_tech rate_limited

Harga sewa nomor #

GET /api/v1/rental-pricing?country={country}&days={days}

Tanpa negara, Anda mendapatkan semua negara tempat nomor dapat disewa, beserta harga awalnya. Dengan satu negara, semua operator di sana dan biaya untuk masa sewa yang Anda minta.

Parameter

Harga sewa nomor — Parameter
Parameter		Deskripsi
`country`	opsional	Kode negara, misalnya fr. Kosongkan untuk menampilkan daftar negara.
`days`	opsional	Masa sewa dalam hari: 7, 14, atau 30. Nilai lainnya akan menggunakan yang terpendek.

Bidang respons

Harga sewa nomor — Bidang respons
Bidang	Tipe	Deskripsi
`ok`	boolean	Selalu true pada 200.
`country`	string	Negara yang Anda minta.
`days`	integer	Masa sewa yang benar-benar diberi harga.
`terms`	array	Semua masa sewa yang ditawarkan, dalam hari.
`operators`	array	Satu objek per operator, termurah lebih dulu.
`operators[].operator`	string	Kode operator, untuk dimasukkan ke dalam pesanan.
`operators[].name`	string	Nama tampilannya.
`operators[].type`	string	physical, virtual, atau premium.
`operators[].price`	number	Dolar untuk seluruh masa sewa.

Permintaan

request

curl -s "https://simsms.com/api/v1/rental-pricing?country=fr&days=30" \
  -H "Authorization: Bearer $SIMSMS_KEY"

Respons

200 OK

{
  "ok": true,
  "country": "fr",
  "days": 30,
  "terms": [7, 14, 30],
  "operators": [
    { "operator": "fr-lycamobile", "name": "Lycamobile", "type": "virtual",  "price": 14.32 },
    { "operator": "fr-orange",     "name": "Orange",     "type": "physical", "price": 20.76 }
  ]
}

Dapat menjawab missing_key bad_key unknown_country rate_limited

Contoh lengkap #

Program lengkap yang bisa langsung dijalankan, bukan potongan satu baris — termasuk dua hal yang selalu terlewat dalam potongan kode: menangani bentuk error, dan mundur (backoff) saat menerima 429.

Shell #

Mencari negara termurah untuk sebuah layanan, lalu memeriksa apakah saldo mencukupi.

cheapest.sh

#!/usr/bin/env bash
set -euo pipefail
: "${SIMSMS_KEY:?export your key first}"
API="https://simsms.com/api/v1"

auth=(-H "Authorization: Bearer $SIMSMS_KEY")

# The catalogue is already ordered: the first country is the one to take.
best=$(curl -sf "${API}/pricing?service=telegram" "${auth[@]}" \
        | jq -r ".countries[0] | \"\(.country) \(.price)\"")
country=${best% *}
price=${best#* }

balance=$(curl -sf "${API}/balance" "${auth[@]}" | jq -r .balance)

# ⚠️ Compare as numbers, not as strings: "9.5" > "10" is true in a string sort.
if awk "BEGIN{exit !($balance >= $price)}"; then
  echo "ok: $country at \$$price, balance \$$balance"
else
  echo "top up first: need \$$price, have \$$balance" >&2
  exit 1
fi

JavaScript #

Hal yang sama dalam Node, dengan bentuk error yang ditangani dengan benar.

pricing.mjs

const API = "https://simsms.com/api/v1";
const key = process.env.SIMSMS_KEY;

async function call(path) {
  const r = await fetch(API + path, {
    headers: { Authorization: `Bearer ${key}` },
  });
  const body = await r.json();
  // A non-2xx always carries { ok:false, error }. Branch on `error`, never on
  // the sentence — the string is stable, the wording is not.
  if (!r.ok || !body.ok) {
    if (body.error === "rate_limited") {
      const wait = Number(r.headers.get("Retry-After") || 60);
      await new Promise((s) => setTimeout(s, wait * 1000));
      return call(path);
    }
    throw new Error(body.error ?? `http_${r.status}`);
  }
  return body;
}

const { countries } = await call("/pricing?service=telegram");
const { balance }   = await call("/balance");

const best = countries[0];
console.log(`${best.name}: $${best.price} (${best.stock} in stock)`);
console.log(balance >= best.price ? "balance covers it" : "top up first");

Python #

Dan dalam Python, dengan retry yang sama pada 429.

pricing.py

import os, time, requests

API = "https://simsms.com/api/v1"
S = requests.Session()
S.headers["Authorization"] = f"Bearer {os.environ['SIMSMS_KEY']}"

def call(path):
    r = S.get(API + path, timeout=20)
    body = r.json()
    if not r.ok or not body.get("ok"):
        if body.get("error") == "rate_limited":
            time.sleep(int(r.headers.get("Retry-After", 60)))
            return call(path)
        raise RuntimeError(body.get("error", f"http_{r.status_code}"))
    return body

countries = call("/pricing?service=telegram")["countries"]
balance   = call("/balance")["balance"]

best = countries[0]
print(f"{best['name']}: ${best['price']} ({best['stock']} in stock)")
print("balance covers it" if balance >= best["price"] else "top up first")

Roadmap #

Saat ini API mencakup pembacaan akun dan katalog. Fitur pemesanan menyusul, dan akan berada di alamat dasar yang sama serta memakai kunci yang sama — apa pun yang Anda bangun sekarang tidak perlu ditulis ulang.

Memesan nomor	Rencana Direncanakan. Saat ini pemesanan dilakukan melalui situs.
Polling kode	Rencana Direncanakan, bersamaan dengan pemesanan.
Melepas nomor	Rencana Direncanakan, bersamaan dengan pemesanan.
Sewa melalui API	Rencana Direncanakan.
Webhooks	Rencana Direncanakan, begitu ada event pesanan yang perlu dikirim.

Halaman ini akan terus berkembang seiring itu: bagian-bagian di bawah tetap berada di tempatnya, dan bagian baru ditambahkan di bawah Endpoints.

Log perubahan #

2026-08-22Versi publik pertama: kunci API, GET /balance, GET /pricing.