Usare l'API di verifica SMS con Claude Code: guida alla configurazione

Claude Code integra la verifica SMS nel tuo progetto: dagli la skill dell'API di SMS Activate App e tieni la chiave API in una variabile d'ambiente.

Claude Code può integrare la verifica SMS nel tuo progetto al posto tuo: dagli la skill dell'API di SMS Activate App, tieni la chiave API in una variabile d'ambiente e controlla ogni passaggio che spende denaro.

Con questa guida completi la configurazione in circa dieci minuti. Funziona allo stesso modo con Codex, Cursor o qualsiasi agente di programmazione che legga file ed esegua comandi.

Cosa può fare l'agente con l'API

Con una chiave, un agente di programmazione può fare tutto ciò che fa il tuo codice:

  • Cercare i numeri disponibili in tempo reale in un paese e vedere il tuo prezzo.
  • Acquistare un numero privato per un periodo di 28 giorni, con una Idempotency-Key perché un nuovo tentativo non addebiti mai due volte.
  • Leggere gli SMS che arrivano sul numero e le chiamate: da novembre 2026 una breve chiamata arriva con il suo testo e il codice letto a voce.
  • Rilasciare un numero o disattivarne il rinnovo.
  • Configurare un webhook, così i codici raggiungono il tuo server senza polling.

Compiti tipici da delegare: un test end-to-end del tuo flusso di registrazione, una funzione di supporto che attende un codice in CI, oppure un ricevitore di webhook con verifica della firma.

Passaggio 1: crea una chiave e tienila fuori dal codice

  • Crea un account nella pagina di registrazione e ricarica il saldo.
  • Crea una chiave API personale nella scheda delle chiavi API del tuo account, oppure nel bot di Telegram.
  • Metti la chiave nella shell o nel gestore dei segreti del progetto, mai in un file che l'agente può committare:

La chiave spende il tuo saldo. Claude Code legge la variabile quando esegue un comando e non ha bisogno di vedere il valore nella chat. Se la chiave finisce in un file, in un commit o in un log, revocala nell'account e creane una nuova.

Passaggio 2: dai la skill a Claude Code

Il sito pubblica un file skill pronto per gli agenti di programmazione all'indirizzo /api-skill.md. Indica l'URL di base, le route, i limiti e gli errori da gestire. Salvalo come skill del progetto:

Claude Code carica una skill quando un compito corrisponde alla sua descrizione, per esempio «attendi il codice SMS nel mio test di registrazione». Fai il commit del file della skill se il tuo team deve condividerlo: non contiene alcuna chiave.

Il tuo agente non supporta le skill? Apri la documentazione dell'API e premi il pulsante che copia il prompt per l'agente. Contiene le stesse regole in un unico blocco di testo che puoi incollare in qualsiasi chat.

Passaggio 3: stabilisci le regole di casa

Aggiungi alcune righe al CLAUDE.md del tuo progetto, così ogni sessione le segue:

La seconda regola è la più importante. Un acquisto è definitivo e non rimborsabile una volta emesso il numero, quindi una persona dovrebbe vedere ogni acquisto prima che avvenga. Claude Code chiede il permesso prima di eseguire un comando: mantieni questa richiesta attiva per i comandi che chiamano la route di acquisto.

Passaggio 4: assegna un compito

Chiedi il risultato, non le singole chiamate all'API. Per esempio:

Aggiungi una fixture pytest che noleggi un numero USA tramite l'API di SMS Activate App, attenda fino a cinque minuti un SMS su quel numero e restituisca il codice. Riusa tra un'esecuzione e l'altra un solo numero che si rinnova, invece di comprarne uno nuovo ogni volta.

Un buon risultato si presenta così:

  • Cerca con GET /v1/public/numbers/search?country=US e ti mostra il numero e il suo prezzo prima di acquistare.
  • Acquista con POST /v1/public/numbers e una Idempotency-Key.
  • Interroga GET /v1/public/numbers/{id}/sms ogni 5-15 secondi con un timeout, oppure configura un webhook.
  • Gestisce insufficientbalance, numberunavailable e rate_limited come risposte, non come crash.

Se inventa una route che non è nella skill, indicagli il file OpenAPI e chiedigli di verificare.

Passaggio 5: controlla prima del merge

Prima di fare il merge di ciò che ha scritto l'agente, verifica quattro cose:

  • Nessuna chiave nel diff, nell'output dei test o nei log di CI.
  • Ogni acquisto invia una Idempotency-Key e un nuovo tentativo la riutilizza.
  • Ogni attesa ha un timeout e un messaggio di errore chiaro che nomina il numero.
  • Il test non acquista un nuovo numero a ogni esecuzione quando basterebbe un solo numero con rinnovo.

Costi da conoscere

Ogni numero è noleggiato per 28 giorni al prezzo mostrato dalla ricerca e si rinnova scalando dal saldo finché il rinnovo automatico è attivo. Da novembre 2026 anche le chiamate in entrata (al minuto) e gli SMS su un numero vengono addebitati sul saldo, a un prezzo per paese che l'API restituisce come usagePricing. Controlla i prezzi per conoscere i valori attuali prima di lasciare che un agente esegua una suite a intervalli regolari.

Quando non usarla

L'API riceve SMS e chiamate, ma non ne invia. Usala per le tue app, i tuoi account e i tuoi test. La piattaforma con cui verifichi, non noi, decide se accetta un numero: prima di costruirci sopra una pipeline, controlla il numero con il servizio di destinazione. Qui trovi come controllare un numero prima di noleggiarlo.

Passi successivi