REST API SMS Activate App memungkinkan kode Anda membeli nomor pribadi, memicu verifikasi, dan membaca kode SMS untuk aplikasi, akun, dan tes Anda sendiri.
Panduan ini membahas seluruh alurnya: memilih nomor, membelinya dengan aman, membaca kode OTP (one-time password, kata sandi sekali pakai), lalu melepas nomor setelah selesai.
Kapan perlu otomatisasi
Otomatisasi cocok untuk pekerjaan milik Anda sendiri yang berulang. Ada tiga kasus umum:
- Tes end-to-end untuk langkah SMS di aplikasi Anda sendiri: pendaftaran, login, reset kata sandi, dan 2FA (two-factor authentication, autentikasi dua faktor).
- Menjaga 2FA tetap berfungsi untuk akun layanan dan alat internal milik Anda.
- Langkah verifikasi di dalam produk yang Anda jalankan.
Setiap nomor adalah nomor virtual pribadi. Nomor ini adalah nomor seluler atau nomor lokal asli dari rentang nomor operator, tergantung negaranya. Akun Anda memegang nomor tersebut selama masa 28 hari. Nomor yang sama bisa menerima kode berikutnya, jadi verifikasi ulang dan pemulihan akun tetap berfungsi selama masa tersebut.
Ada dua batasan. Nomor bersifat final dan tidak dapat dikembalikan dananya setelah diterbitkan. Platform tempat Anda melakukan verifikasi, bukan kami, yang memutuskan apakah nomor tersebut diterima.
Sebagian besar kode tiba dalam beberapa menit setelah platform mengirimkannya. Kami belum memublikasikan tingkat keberhasilan pengiriman, jadi uji nomor dengan platform tujuan Anda sebelum membangun pipeline di atasnya.
API ini menerima SMS. API ini tidak mengirim SMS.
Sebelum memulai
- Buat akun gratis di halaman pendaftaran.
- Isi saldo akun.
- Buat kunci API pribadi di dasbor akun, pada tab kunci API, atau di bot Telegram.
Kirim kunci tersebut di setiap permintaan, termasuk permintaan katalog:
Kunci ini memakai saldo Anda. Simpan di sisi server, di penyimpanan rahasia atau secret CI. Jangan pernah menaruhnya di kode klien atau meng-commit-nya ke repositori.
Detail referensi:
- Base URL: https://api.sms-activate.app/v1/public
- Nilai uang berupa bilangan bulat dalam sen USD. balanceCents: 2000 berarti $20.00.
- Spesifikasi yang dapat dibaca mesin: file OpenAPI (OpenAPI 3.1).
- Dokumentasi yang dapat dibaca manusia: dokumentasi API.
- Skill siap pakai untuk agen LLM: skill agen.
- Batas: setidaknya 120 permintaan per menit per akun, dan 30 pembelian per menit. Jika melebihinya, jawabannya adalah rate_limited dengan header Retry-After.
Alur verifikasi
- Panggil GET /countries. Endpoint ini mengembalikan ketersediaan serta rentang harga untuk setiap negara.
- Panggil GET /numbers/search?country=US&limit=1 untuk memilih nomor yang tersedia. Setiap hasil memuat phoneNumber dan harga Anda di priceCents.
- Beli nomor dengan POST /numbers dan body {"phone": "<phoneNumber>", "country": "US"}. Tambahkan header Idempotency-Key: <uuid> agar percobaan ulang tidak pernah menagih Anda dua kali. Pembelian yang berhasil mengembalikan 201 dengan number, chargedCents, dan balanceAfterCents. Ada dua kolom opsional: autoRenew (default true) dan note.
- Masukkan nomor tersebut ke alur yang sedang Anda uji, lalu picu pengiriman SMS.
- Baca kodenya. Lakukan polling ke GET /numbers/{id}/sms untuk nomor tersebut, atau ke GET /sms untuk semua nomor, kira-kira setiap 5 sampai 15 detik, dan tetapkan batas waktu. Setiap SMS memiliki id, numberId, from, to, body, dan receivedAt; ambil kodenya dari body. Feed menggunakan paginasi kursor dengan cursor, limit, dan nextCursor.
- Selesaikan. Kirim PATCH /numbers/{id} dengan {"autoRenew": false} untuk menghentikan perpanjangan, atau DELETE /numbers/{id} untuk melepas nomor. Untuk rangkaian tes yang Anda jalankan setiap hari, mempertahankan satu nomor dengan perpanjangan otomatis biasanya lebih sederhana daripada membeli nomor baru di setiap eksekusi.
Contoh dengan curl
Panggilan pertama mencari nomor. Panggilan kedua membelinya. Panggilan ketiga membaca SMS yang masuk.
Ganti +15551234567 dengan nomor yang dikembalikan oleh panggilan pertama. Jika Anda mengulang pembelian setelah terjadi galat jaringan, gunakan kembali nilai Idempotency-Key yang sama, jangan membuat nilai baru.
Contoh dalam Python
Fungsi ini menunggu kode pada satu nomor yang sudah Anda miliki. Fungsi ini memakai pustaka requests dan membaca kunci dari variabel lingkungan.
Jika SMS lama pada nomor yang sama bisa ikut cocok, bandingkan receivedAt dengan waktu saat pengujian Anda memicu pesan, lalu ambil hanya pesan yang lebih baru.
Webhook sebagai pengganti polling
Kirim PATCH /numbers/{id} dengan {"forwardWebhookUrl": "https://your-app.example.com/sms"}, maka setiap SMS dan telepon masuk ke nomor tersebut dikirim ke server Anda begitu tiba. Alamatnya diperiksa lebih dulu: alamat itu harus menjawab POST uji dengan status 2xx.
Setiap permintaan membawa x-vpn-event, x-vpn-timestamp, dan x-vpn-signature. Tanda tangannya adalah HMAC-SHA256 dari v1.<timestamp>.<raw body> dengan rahasia webhook Anda. Verifikasi tanda tangan pada byte mentah, dan tolak timestamp yang selisihnya lebih dari lima menit.
Polling lebih sederhana untuk pengujian yang hanya berjalan sekali. Webhook cocok untuk layanan yang berjalan lama dan memproses kode begitu kode masuk.
Tangani error sebagai jawaban
Setiap error memiliki bentuk yang sama:
Buat percabangan berdasarkan kode error, jangan berdasarkan status HTTP. Satu status bisa mewakili lebih dari satu penolakan, jadi status saja tidak memberi tahu Anda apa yang terjadi. Beberapa penolakan menambahkan objek details, misalnya requiredCents dan availableCents pada insufficient_balance.
Kode yang perlu ditangani:
- insufficient_balance: saldo Anda tidak cukup untuk pembelian. Hentikan proses dan isi ulang saldo.
- no_numbers: saat ini tidak ada nomor yang sesuai. Pilih nomor atau negara lain.
- number_unavailable: nomor sudah terjual atau tidak lagi dijual. Cari lagi.
- validation_failed: body permintaan atau parameternya salah, atau pembelian tidak memiliki Idempotency-Key. Perbaiki input.
- idempotent_replay: permintaan dengan Idempotency-Key ini datang dengan body lain atau masih diproses. Jangan anggap ini sebagai pembelian baru.
- rate_limited: terlalu banyak permintaan. Tunggu selama waktu yang disebutkan header Retry-After.
- priceexceeded dan providerfailure: baca message, tampilkan, lalu hentikan proses. Setelah provider_failure, periksa nomor Anda sebelum membeli lagi.
Tidak satu pun dari error ini adalah gangguan yang boleh dicoba ulang begitu saja. Tampilkan error kepada orang yang menjalankan kode, atau hentikan proses. Simpan reqId di log Anda. Tim dukungan memakainya untuk menemukan permintaan Anda.
Dalam rangkaian pengujian CI
- Jalankan pengujian SMS sebagai job terpisah yang berjalan serial, agar dua pengujian tidak pernah membaca kode yang sama.
- Simpan kunci API sebagai secret CI.
- Cocokkan setiap kode dengan pengujiannya berdasarkan nomor dan waktu pengujian dimulai.
- Tetapkan batas waktu, dan buat pengujian gagal dengan pesan jelas yang menyebut nomor dan langkahnya.
- Gunakan satu nomor yang terus diperpanjang untuk run berulang, alih-alih membeli nomor baru setiap kali.
Video yang berguna
Video pihak ketiga tentang teknik yang dipakai dalam panduan ini. Video ini mengajarkan teknik umum dan tidak membahas layanan kami.
- Python Requests Tutorial: Request Web Pages, Download Images, POST Data, Read JSON, and More (Corey Schafer): mengirim permintaan GET dan POST dari Python dengan header, lalu membaca jawaban JSON.
- Server-Sent Events Crash Course (Hussein Nasser): cara kerja aliran Server-Sent Events dan kapan aliran ini lebih baik daripada polling.
- Polling vs Webhooks | System Design Tradeoffs (SoftwareDude): biaya dan manfaat bertanya secara berkala dibandingkan menerima push.
- Idempotency in APIs Explained | Why It Matters + Code Example (Arkynate): kunci idempotensi dan percobaan ulang yang aman, disertai kode.
- Playwright Tutorial: Re-use state & Re-use Authentication (CommitQuality): login sekali dalam rangkaian pengujian lalu memakai ulang status yang sudah masuk, sehingga langkah SMS hanya berjalan saat benar-benar diperlukan.
Langkah berikutnya
- Baca referensi lengkap di dokumentasi API.
- Muat spesifikasi ke alat Anda dari file OpenAPI.
- Berikan skill agen yang siap pakai kepada agen LLM.
- Cek harga terkini di halaman harga.
- Jika Anda berencana membangun produk di atas API, baca ikhtisar cara menghasilkan uang dengan nomor telepon virtual.