Automatizzare la verifica SMS con l'API: guida per sviluppatori

Con l'API REST di SMS Activate App il tuo codice compra un numero privato, avvia una verifica e legge il codice SMS, per app, account e test tuoi.

Questa guida copre l'intero flusso: scegliere un numero, acquistarlo in sicurezza, leggere il codice OTP (one-time password, password monouso) e rilasciare il numero quando hai finito.

Quando automatizzare

L'automazione è adatta ad attività tue e ripetute. Tre casi frequenti:

  • Test end-to-end dei passaggi SMS nella tua app: registrazione, accesso, reimpostazione della password e 2FA (autenticazione a due fattori).
  • Mantenere attiva la 2FA per i tuoi account di servizio e i tuoi strumenti interni.
  • Un passaggio di verifica dentro un prodotto che gestisci tu.

Ogni numero è un numero virtuale privato. È un vero numero mobile o locale preso dalla numerazione di un operatore, a seconda del paese. Il tuo account lo tiene per un periodo di 28 giorni. Lo stesso numero può ricevere anche i codici successivi, quindi la nuova verifica e il recupero dell'account continuano a funzionare per tutto il periodo.

Valgono due limiti. Una volta emesso, il numero è definitivo e non rimborsabile. È la piattaforma su cui ti verifichi, non noi, a decidere se accettare un numero.

La maggior parte dei codici arriva entro pochi minuti dall'invio da parte della piattaforma. Non pubblichiamo ancora un tasso di consegna, quindi prova un numero con la piattaforma di destinazione prima di costruirci sopra una pipeline.

L'API riceve SMS. Non li invia.

Prima di iniziare

  • Crea un account gratuito nella pagina di registrazione.
  • Ricarica il saldo dell'account.
  • Crea una chiave API personale nella dashboard dell'account, nella scheda delle chiavi API, oppure nel bot di Telegram.

Invia la chiave con ogni richiesta, catalogo compreso:

La chiave spende il tuo saldo. Tienila lato server, in un archivio di segreti o in un secret della CI. Non inserirla mai nel codice client e non farne mai il commit in un repository.

Dettagli di riferimento:

  • URL di base: https://api.sms-activate.app/v1/public
  • Gli importi sono centesimi di dollaro USA, espressi come numeri interi. balanceCents: 2000 significa 20,00 $.
  • Specifica leggibile dalle macchine: il file OpenAPI (OpenAPI 3.1).
  • Documentazione leggibile dalle persone: la documentazione dell'API.
  • Una skill pronta per gli agenti LLM: la skill per agenti.
  • Limiti: almeno 120 richieste al minuto per account e 30 acquisti al minuto. Oltre questi valori la risposta è rate_limited, con un header Retry-After.

Il flusso di verifica

  • Chiama GET /countries. Restituisce la disponibilità e la fascia di prezzo per ogni paese.
  • Chiama GET /numbers/search?country=US&limit=1 per scegliere un numero disponibile. Ogni risultato contiene phoneNumber e il tuo prezzo in priceCents.
  • Acquista il numero con POST /numbers e il body {"phone": "<phoneNumber>", "country": "US"}. Aggiungi un header Idempotency-Key: <uuid>, così un nuovo tentativo non ti addebita mai due volte. Un acquisto riuscito restituisce 201 con number, chargedCents e balanceAfterCents. Ci sono due campi facoltativi: autoRenew (predefinito true) e note.
  • Inserisci il numero nel flusso che stai testando e fai partire l'SMS.
  • Leggi il codice. Interroga GET /numbers/{id}/sms per quel numero, oppure GET /sms per tutti, circa ogni 5-15 secondi, e imposta un timeout. Ogni SMS ha id, numberId, from, to, body e receivedAt; estrai il codice da body. I feed sono paginati con cursore tramite cursor, limit e nextCursor.
  • Concludi. Invia PATCH /numbers/{id} con {"autoRenew": false} per fermare il rinnovo, oppure DELETE /numbers/{id} per rilasciare il numero. Per una suite di test che esegui ogni giorno, tenere un numero in rinnovo di solito è più semplice che comprarne uno nuovo a ogni esecuzione.

Esempio con curl

La prima chiamata trova un numero. La seconda lo acquista. La terza legge gli SMS in arrivo.

Sostituisci +15551234567 con un numero restituito dalla prima chiamata. Se ripeti l'acquisto dopo un errore di rete, riusa lo stesso valore di Idempotency-Key invece di generarne uno nuovo.

Esempio in Python

Questa funzione attende un codice su un numero che possiedi già. Usa la libreria requests e legge la chiave dalle variabili d'ambiente.

Se sullo stesso numero ci sono SMS precedenti che potrebbero corrispondere, confronta receivedAt con il momento in cui il tuo test ha fatto partire il messaggio e prendi solo un SMS più recente.

Un webhook invece del polling

Invia PATCH /numbers/{id} con {"forwardWebhookUrl": "https://your-app.example.com/sms"} e ogni SMS e ogni chiamata su quel numero vengono inviati al tuo server appena arrivano. Prima l'indirizzo viene verificato: deve rispondere a un POST di prova con uno stato 2xx.

Ogni richiesta contiene x-vpn-event, x-vpn-timestamp e x-vpn-signature. La firma è HMAC-SHA256 di v1.<timestamp>.<raw body> con il tuo segreto del webhook. Verificala sui byte grezzi e rifiuta un timestamp che si discosti di più di cinque minuti.

Per un test che gira una volta sola il polling è più semplice. Un webhook è adatto a un servizio sempre attivo che gestisce i codici man mano che arrivano.

Gestisci gli errori come risposte

Ogni errore ha la stessa forma:

Decidi in base al codice error, mai in base allo stato HTTP. Uno stesso stato può indicare più di un rifiuto, quindi lo stato da solo non ti dice cosa è successo. Alcuni rifiuti aggiungono un oggetto details, per esempio requiredCents e availableCents su insufficient_balance.

Codici da gestire:

  • insufficient_balance: il tuo saldo non copre l'acquisto. Fermati e ricarica.
  • no_numbers: al momento non c'è un numero corrispondente disponibile. Scegli un altro numero o un altro paese.
  • number_unavailable: il numero è stato venduto o non è più in vendita. Cerca di nuovo.
  • validation_failed: il corpo della richiesta o i parametri sono errati, oppure l'acquisto non ha una Idempotency-Key. Correggi l'input.
  • idempotent_replay: una richiesta con questa Idempotency-Key è arrivata con un altro corpo o è ancora in elaborazione. Non trattarla come un nuovo acquisto.
  • rate_limited: troppe richieste. Aspetta il tempo indicato dall'header Retry-After.
  • priceexceeded e providerfailure: leggi message, mostralo e interrompi l'esecuzione. Dopo provider_failure, controlla i tuoi numeri prima di comprare di nuovo.

Nessuno di questi è un difetto da riprovare alla cieca. Mostra l'errore a chi esegue il codice, oppure interrompi l'esecuzione. Conserva il reqId nei tuoi log. Il supporto lo usa per trovare la tua richiesta.

In una suite di test CI

  • Esegui i test SMS in un job separato e seriale, così due test non leggono mai lo stesso codice.
  • Salva la chiave API come secret della CI.
  • Associa ogni codice al suo test in base al numero e all'ora di avvio del test.
  • Imposta un timeout e fai fallire il test con un messaggio chiaro che indichi il numero e il passaggio.
  • Per le esecuzioni ripetute tieni un numero con rinnovo, invece di comprarne uno nuovo ogni volta.

Video utili

Video di terze parti sulle tecniche usate in questa guida. Insegnano tecniche generali e non trattano il nostro servizio.

Prossimi passi