Guida rapida all'API per sviluppatori

L'API per sviluppatori di SmsGrab dà al tuo software gli stessi numeri dell'app, tramite un'API REST in JSON. È un prodotto a pagamento con i propri prezzi per sviluppatori, si paga con il normale saldo SmsGrab e prevede 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: 18 significa 0,18 USD. price_minor è il tuo prezzo da sviluppatore, retail_price_minor il prezzo dell'app.

{ "currency": "USD", "markup_percent": 80,
  "items": [ { "service_id": "whatsapp", "country_id": "indonesia", "price_minor": 18,
               "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":20}'

• service e country accettano i nostri identificativi, come whatsapp e indonesia. Per i paesi valgono anche i codici ISO come ID.
• max_price_minor ti protegge: se il prezzo è salito non viene addebitato nulla e ricevi 409 PRICE_CHANGED.
• Idempotency-Key rende 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": 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. 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 dopo 20 minuti e viene rimborsato automaticamente.

Valori di stato

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.