API verifikasi SMS
API verifikasi SMS terdiri dari tiga panggilan: beli nomor, tunggu kodenya, lepaskan nomornya. API ini menjangkau 517 layanan di 225 negara, nomor mulai €0,07, dan aktivasi yang tidak menerima apa pun dikembalikan tanpa tiket dukungan. Kunci punya scope, pembelian bersifat idempoten, dan klien handler_api lama tetap berjalan tanpa perubahan.
API dalam satu blok
Diperbarui 28 Agu 2026- URL dasar
- https://virtualsmsnumbers.com/api/v1
- Autentikasi
- Bearer key, atau X-Api-Key
- Batas laju
- 120/menit, lonjakan 20/detik
- Jendela idempotensi
- 24 jam
- Pengembalian otomatis setelah
- 20 menit
- Aktivasi termurah
- €0,07
- Negara tercakup
- 225
- Format
- JSON, sen, ISO 8601 UTC
Harga dan stok diambil dari kumpulan operator apa adanya saat ini, bukan dari daftar tarif yang diterbitkan.
Alur tiga panggilan
Semua hal lain di referensi bersifat opsional. Ini seluruh jalur verifikasinya, dan tidak berubah sejak 2019.
- 1
POST /activations
Minta sebuah layanan, plus negara kalau Anda peduli negaranya. Responsnya membawa nomor, harga dalam sen, dan stempel waktu kedaluwarsa. Kirim Idempotency-Key supaya permintaan yang diulang tidak membeli nomor kedua, dan max_price_cents kalau pemanggilnya otomatis.
- 2
GET /activations/{id}?wait=180
Long poll. Koneksinya ditahan terbuka sampai pesannya masuk atau waktunya habis, jadi satu permintaan menggantikan perulangan yang seharusnya membuat sembilan puluh. Statusnya kembali sebagai code_received berikut kode terurai di samping teks mentahnya, karena tiap pengirim memformatnya berbeda.
- 3
POST /activations/{id}/complete
Tutup aktivasinya dan lepaskan jalurnya. Kalau tidak ada yang masuk, tidak usah lakukan apa-apa: jendelanya kedaluwarsa sendiri dan saldonya dikreditkan kembali. Membatalkan lebih awal adalah panggilan yang sama dengan nama berbeda.
Contoh yang berjalan
Setel VSN_KEY lalu jalankan. Respons dalam komentar adalah bentuk aslinya, termasuk field yang akan Anda simpan.
# 1. Buy a Telegram number in Portugal
-kw">curl -X POST https://virtualsmsnumbers.com/api/v1/activations \
-H "Authorization: Bearer $VSN_KEY" \
-H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
-d '{"service":"telegram","country":"PT"}'
# {"id":"1043872915","phone_number":"351926114508","status":"waiting",
# "price_cents":11,"expires_at":"2026-08-26T12:41:07Z"}
# 2. Long-poll until the code lands (blocks up to 120 s)
-kw">curl "https://virtualsmsnumbers.com/api/v1/activations/1043872915?wait=120" \
-H "Authorization: Bearer $VSN_KEY"
# {"id":"1043872915","status":"code_received",
# "messages":[{"code":"48219","text":"Telegram code: 48219"}]}
# 3. Release the number
-kw">curl -X POST https://virtualsmsnumbers.com/api/v1/activations/1043872915/complete \
-H "Authorization: Bearer $VSN_KEY"Batas laju
120 permintaan per menit per kunci, dengan lonjakan 20 per detik. Setiap respons membawa X-RateLimit-Limit, X-RateLimit-Remaining, dan X-RateLimit-Reset, dan 429 memberi tahu berapa lama harus menunggu alih-alih membuat Anda menebak.
Batas ini jarang menjadi kendala kalau API dipakai sebagaimana mestinya: satu long poll alih-alih sembilan puluh polling, webhook alih-alih timer, serta daftar negara dan layanan yang di-cache saat start. Kalau Anda benar-benar butuh ruang lebih, mintalah — menaikkan batas lebih mudah bagi kita berdua daripada menelusuri masalah pada sekumpulan kunci.
Idempotensi
Kirim header Idempotency-Key pada POST /activations. Mengulang kunci yang sama dalam 24 jam mengembalikan aktivasi asli sebagaimana keadaannya sekarang, disertai header Idempotent-Replay, alih-alih membeli nomor kedua dan menagih Anda dua kali.
Kuncinya bukan hash dari bodi: payload berbeda dengan kunci yang sudah terpakai tetap mengembalikan aktivasi pertama. Buat satu kunci per pembelian logis — UUID sudah cukup — dan pakai ulang lintas percobaan, jangan lintas pembelian.
Klien handler_api lama
Skrip yang ditulis untuk protokol klasik handler_api.php tetap berjalan. Arahkan ke endpoint kompatibilitas, ganti api_key-nya, dan aksi yang sama mengembalikan token ACCESS_ dan STATUS_ yang sama seperti dulu.
Ini lapisan penerjemah di atas kumpulan nomor yang sama, jadi harga, stok, dan pengembalian dana berperilaku identik di kedua jalur. Kode baru tetap sebaiknya memakai /api/v1: respons JSON-nya membawa stempel waktu, kode galat, dan field harga yang tidak muat dalam format token.
# Existing scripts keep working: same actions, same response tokens.
BASE="https://virtualsmsnumbers.com/stubs/handler_api.php"
-kw">curl "$BASE?api_key=$KEY&action=getNumber&service=tg&country=117"
# ACCESS_NUMBER:1043872915:351926114508
-kw">curl "$BASE?api_key=$KEY&action=getStatus&id=1043872915"
# STATUS_WAIT_CODE
# STATUS_OK:48219
-kw">curl "$BASE?api_key=$KEY&action=setStatus&id=1043872915&status=6"
# ACCESS_ACTIVATION
-kw">curl "$BASE?api_key=$KEY&action=getBalance"
# ACCESS_BALANCE:41.87Agen, MCP, dan penemuan
Ada server MCP yang di-host, dokumen OpenAPI 3.1, dan indeks llms.txt, jadi sebuah agen bisa menemukan tiga tool yang dibutuhkannya tanpa perekat tulisan tangan. Arahkan klien Anda ke endpoint di bawah dan ia akan menemukan beli, tunggu, dan lepas.
Sebelum Anda membiarkan apa pun yang otonom membelanjakan saldo: batasi scope kuncinya ke numbers:read dan numbers:write, setel batas max_price_cents pada setiap pembelian, dan beri kunci tersendiri supaya mencabutnya tidak mematikan integrasi produksi Anda.
{
"mcpServers": {
"virtualsmsnumbers": {
"type": "http",
"url": "https://virtualsmsnumbers.com/api/mcp",
"headers": { "Authorization": "Bearer vsn_live_xxxxxxxxxxxx" }
}
}
}Sebelum produksi
- Setel max_price_cents pada setiap pembelian. Harga bergerak mengikuti kumpulan nomor, dan agen tanpa batas akan dengan senang hati membeli ujung yang mahal.
- Perlakukan pengenal sebagai string buram. Id aktivasi kebetulan sepuluh digit hari ini; itu bukan janji, dan panjangnya pun bukan.
- Bercabanglah pada kode galat, jangan pada pesannya. Kode stabil dalam satu versi; pesan ditulis untuk manusia dan bisa ditulis ulang.
- Berlanggananlah pada sms.received dan verifikasi tanda tangannya — HMAC-SHA256 atas bodi mentah, dengan jendela putar ulang lima menit — alih-alih memolling status yang bisa diberitahukan kepada Anda.
- Lakukan aritmetika pada field sen bertipe bilangan bulat. String terformat di sebelahnya untuk tampilan dan bergantung pada lokal.
Referensi lengkap
Enam endpoint, tabel galat, payload webhook, scope, dan peta token versi lama.
Pertanyaan yang sering diajukan
Median pengiriman di bawah sembilan detik sejak layanan mengirimnya. Long poll ada karena ekornya panjang: aktivasi tetap terbuka selama 20 menit, lalu kedaluwarsa menjadi pengembalian dana kalau tidak ada yang masuk.
Tidak ada yang perlu Anda tangani. Jendelanya tertutup, saldonya dikreditkan kembali otomatis, dan aktivasinya berakhir dalam status expired yang bisa Anda baca dari API.
Ya, dan itu gratis. Kunci membawa scope tetap, daftar izin IP opsional, dan masa berlaku yang dipilih saat pembuatan, jadi kunci staging yang bocor tidak bisa membeli nomor di produksi.
Ada pembungkus tipis tanpa dependensi, tetapi API ini hanya enam endpoint di atas JSON — fetch, requests, atau curl sudah benar-benar cukup untuk alur tiga panggilan.
Dalam satu aktivasi, bisa: pesan tambahan datang di nomor yang sama selama masih terbuka. Lintas sesi Anda butuh sewa, yang memegang jalurnya dari empat jam sampai dua belas bulan.
Tidak. Kumpulan nomor dan harganya sama; hanya penyandian responsnya yang berbeda.