Guida rapida all'API per sviluppatori
Acquista numeri e leggi i codici dal tuo software. Crea una chiave, controlla i prezzi, acquista un numero, attendi l'SMS e concludi, passo dopo passo.
In questa pagina
L'API per sviluppatori di SmsGrab dà al tuo software gli stessi numeri dell'app, tramite un'API REST in JSON. Paghi gli stessi prezzi dell'app, meno il tuo sconto a volume, con il normale saldo SmsGrab e gli stessi rimborsi automatici.
Chi può usarla
- Un account con email e indirizzo confermato. Gli account ospite non possono creare chiavi.
- Un account senza restrizioni.
1. Crea una chiave API
Apri Account > Sviluppatori sul sito, oppure Impostazioni > API per sviluppatori nell'app, e crea una chiave. Per sicurezza confermi con la password e, se attiva, con il codice della verifica in due passaggi. Scegli l'ambito read per strumenti di sola lettura, oppure read e purchase per acquistare numeri.
La chiave inizia con sgk_ e viene mostrata una sola volta. Conservala nell'archivio dei segreti del tuo server. Vedi Chiavi API e sicurezza.
2. Autenticati
L'URL di base è https://smsgrab.com/api/dev/v1. Invia la chiave come token Bearer o nell'intestazione X-Api-Key:
GET /api/dev/v1/balance HTTP/1.1
Host: smsgrab.com
Authorization: Bearer sgk_your_key_here
Le chiavi stanno sui server. Non inserirle mai in un sito, in un'estensione del browser o in un'app distribuita ad altre persone.
3. Controlla saldo e prezzi
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"
Gli importi sono sempre espressi in unità minori di USD: 24 significa 0,24 USD. price_minor è il tuo prezzo con lo sconto a volume incluso, retail_price_minor il prezzo di listino dell'app.
{ "currency": "USD", "discount_percent": 5,
"items": [ { "service_id": "whatsapp", "country_id": "indonesia", "price_minor": 24,
"retail_price_minor": 25, "available_numbers": 30412 } ] }
4. Acquista un numero
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":24}'
serviceecountryaccettano i nostri identificativi, comewhatsappeindonesia. Per i paesi valgono anche i codici ISO comeID.max_price_minorti protegge: se il prezzo è salito non viene addebitato nulla e ricevi409 PRICE_CHANGED.Idempotency-Keyrende sicuri i nuovi tentativi. Ripetere la richiesta con la stessa chiave restituisce il primo risultato invece di acquistare due volte.
La risposta è 201 Created con l'attivazione:
{ "id": "5c1d0c2e-8a41-4f7e-9d7a-2f1d9f1b8c11", "compat_id": 100000123, "status": "WAITING_SMS",
"service_id": "whatsapp", "country_id": "indonesia", "phone_number": "+6281234567890",
"price_minor": 24, "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. Attendi l'SMS
Invece di interrogare l'API in un ciclo stretto, lascia che trattenga la richiesta finché qualcosa cambia, per un massimo di 30 secondi:
curl -s "https://smsgrab.com/api/dev/v1/activations/100000123?wait=25" \
-H "Authorization: Bearer $SMSGRAB_KEY"
Quando arriva un messaggio, status diventa CODE_RECEIVED e sms contiene tutti i messaggi ricevuti:
{ "status": "CODE_RECEIVED",
"sms": [ { "code": "482913", "text": "Your WhatsApp code is 482-913", "sender": "WhatsApp",
"received_at": "2026-09-27T10:06:12.004Z" } ] }
Preferisci ricevere notifiche invece di interrogare? Configura i webhook.
6. Concludi o annulla
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 dopo aver usato il codice. È accettato solo dopo l'arrivo di un codice.
- cancel mentre aspetti ancora il primo codice. Il prezzo intero viene rimborsato.
- Se non fai nulla, un numero senza codice scade all'ora indicata in
expires_ate viene rimborsato automaticamente. La durata dipende dal servizio e dal paese, quindi leggi sempreexpires_atinvece di presumere un tempo fisso.
Valori di stato
| Stato | Significato |
|---|---|
WAITING_SMS |
Acquistato, in attesa del primo messaggio |
CODE_RECEIVED |
È arrivato almeno un messaggio |
COMPLETED |
Concluso da te, oppure tempo scaduto dopo un codice |
CANCELLED |
Annullato prima di un codice, rimborsato |
EXPIRED |
Nessun codice entro expires_at, rimborsato |
Errori
Tutti gli errori hanno la stessa forma. Agisci in base a code e reason, e ignora i motivi che ancora non conosci:
{ "code": "NO_NUMBERS_AVAILABLE", "message": "No numbers available for this service and country", "reason": "OUT_OF_STOCK" }
I casi più comuni sono 402 INSUFFICIENT_BALANCE, 409 NO_NUMBERS_AVAILABLE, 409 PRICE_CHANGED, 422 con ACTIVATION_LIMIT_REACHED (al massimo 100 numeri possono attendere contemporaneamente per account) e 429 RATE_LIMITED con un'intestazione Retry-After.
Il riferimento completo è nella documentazione per sviluppatori.
Questo articolo ti è stato utile?
Grazie! Siamo felici che ti sia stato utile.