Permulaan pantas API pembangun

API pembangun SmsGrab memberi perisian anda nombor yang sama seperti apl, melalui REST API berasaskan JSON. Ia produk berbayar dengan harga pembangun tersendiri, dibayar daripada baki SmsGrab biasa, dan dilindungi oleh bayaran balik automatik yang sama.

Siapa yang boleh menggunakannya

• Akaun e-mel dengan alamat yang disahkan. Akaun tetamu tidak boleh mencipta kunci.
• Akaun yang tidak disekat.

1. Cipta kunci API

Buka Akaun > Pembangun di laman web, atau Tetapan > API pembangun dalam apl, dan cipta kunci. Demi keselamatan, anda mengesahkan dengan kata laluan, dan dengan kod pengesahan 2 langkah jika ia dihidupkan. Pilih skop read untuk alat yang hanya membaca, atau read dan purchase untuk membeli nombor.

Kunci bermula dengan sgk_ dan hanya dipaparkan sekali. Simpannya dalam storan rahsia pelayan anda. Lihat Kunci API dan keselamatan.

2. Pengesahan

URL asasnya ialah https://smsgrab.com/api/dev/v1. Hantar kunci sebagai bearer token, atau dalam pengepala X-Api-Key:

GET /api/dev/v1/balance HTTP/1.1
Host: smsgrab.com
Authorization: Bearer sgk_your_key_here

Tempat kunci ialah pada pelayan. Jangan sekali-kali letakkannya dalam laman web, sambungan pelayar atau apl yang anda berikan kepada orang lain.

3. Semak baki dan harga

export SMSGRAB_KEY="sgk_your_key_here"

curl -s https://smsgrab.com/api/dev/v1/balance \
  -H "Authorization: Bearer $SMSGRAB_KEY"

curl -s "https://smsgrab.com/api/dev/v1/prices?service=whatsapp&country=indonesia" \
  -H "Authorization: Bearer $SMSGRAB_KEY"

Wang sentiasa dinyatakan dalam unit terkecil USD, jadi 18 bermaksud 0.18 USD. price_minor ialah harga pembangun anda dan retail_price_minor ialah harga dalam apl.

{ "currency": "USD", "markup_percent": 80,
  "items": [ { "service_id": "whatsapp", "country_id": "indonesia", "price_minor": 18,
               "retail_price_minor": 25, "available_numbers": 30412 } ] }

4. Beli nombor

curl -s -X POST https://smsgrab.com/api/dev/v1/activations \
  -H "Authorization: Bearer $SMSGRAB_KEY" \
  -H "Idempotency-Key: order-7f3c2a" \
  -H "Content-Type: application/json" \
  -d '{"service":"whatsapp","country":"indonesia","max_price_minor":20}'

• service dan country menerima id kami, seperti whatsapp dan indonesia. Negara juga menerima kod ISO seperti ID.
• max_price_minor melindungi anda: jika harga naik, tiada apa-apa ditolak dan anda mendapat 409 PRICE_CHANGED.
• Idempotency-Key menjadikan cubaan semula selamat. Mengulang permintaan dengan kunci yang sama mengembalikan hasil pertama dan bukan membeli dua kali.

Jawapannya ialah 201 Created bersama pengaktifan:

{ "id": "5c1d0c2e-8a41-4f7e-9d7a-2f1d9f1b8c11", "compat_id": 100000123, "status": "WAITING_SMS",
  "service_id": "whatsapp", "country_id": "indonesia", "phone_number": "+6281234567890",
  "price_minor": 18, "currency": "USD",
  "created_at": "2026-09-27T10:05:00.000Z", "expires_at": "2026-09-27T10:25:00.000Z",
  "refunded": false, "refund_minor": 0, "sms": [] }

5. Tunggu SMS

Daripada bertanya berulang kali dalam gelung yang rapat, biarkan API menahan permintaan sehingga 30 saat sehingga ada perubahan:

curl -s "https://smsgrab.com/api/dev/v1/activations/100000123?wait=25" \
  -H "Authorization: Bearer $SMSGRAB_KEY"

Apabila mesej tiba, status bertukar kepada CODE_RECEIVED dan sms mengandungi semua mesej setakat ini:

{ "status": "CODE_RECEIVED",
  "sms": [ { "code": "482913", "text": "Your WhatsApp code is 482-913", "sender": "WhatsApp",
             "received_at": "2026-09-27T10:06:12.004Z" } ] }

Lebih suka tolak daripada tinjau? Sediakan webhook.

6. Selesaikan atau batalkan

curl -s -X POST https://smsgrab.com/api/dev/v1/activations/100000123/finish \
  -H "Authorization: Bearer $SMSGRAB_KEY"

curl -s -X POST https://smsgrab.com/api/dev/v1/activations/100000123/cancel \
  -H "Authorization: Bearer $SMSGRAB_KEY"

• finish selepas anda menggunakan kod. Ia hanya diterima selepas kod tiba.
• cancel semasa masih menunggu kod pertama. Harga penuh dibayar balik.
• Jika anda tidak berbuat apa-apa, nombor tanpa kod tamat tempoh selepas 20 minit dan dibayar balik secara automatik.

Nilai status

Ralat

Setiap ralat mempunyai bentuk yang sama. Bertindak berdasarkan code dan reason, dan abaikan sebab yang belum anda kenali:

{ "code": "NO_NUMBERS_AVAILABLE", "message": "No numbers available for this service and country", "reason": "OUT_OF_STOCK" }

Kes biasa ialah 402 INSUFFICIENT_BALANCE, 409 NO_NUMBERS_AVAILABLE, 409 PRICE_CHANGED, 422 dengan ACTIVATION_LIMIT_REACHED (sehingga 100 nombor boleh menunggu serentak bagi setiap akaun), dan 429 RATE_LIMITED dengan pengepala Retry-After.

Rujukan penuh ada dalam dokumentasi pembangun.