# Migrare Verify da un altro provider

Usa questa guida per spostare i codici di verifica monouso (OTP) per telefono ed email da un altro provider di verifica a Bird Verify. Il passaggio è contenuto, perché la superficie è contenuta: due chiamate sostituiscono qualsiasi coppia create-and-check del tuo provider attuale, e Bird gestisce il codice, il messaggio e il canale di consegna dietro di esse.

Una differenza strutturale definisce la forma del lavoro. Bird non ha un oggetto service per applicazione né un ID di verifica da tracciare. Una verifica è identificata dal destinatario, quindi entrambe le chiamate ricevono lo stesso `to`, e lo stato che la tua integrazione deve mantenere si riduce a zero.

Checklist di migrazione:

1. [Mappa le chiamate create e check](#1-mappa-le-chiamate-create-e-check)
2. [Configura canali, paesi e mittente](#2-configura-canali-paesi-e-mittente)
3. [Porta il ciclo di vita della verifica](#3-porta-il-ciclo-di-vita-della-verifica)
4. [Cambia i webhook](#4-cambia-i-webhook)
5. [Passa in produzione una durata di codice alla volta](#5-passare-in-produzione-una-durata-di-codice-alla-volta)

I passaggi 1 e 3 dipendono dal provider che stai abbandonando. La tua [guida al provider](#migrazione-da-un-provider-specifico) contiene la mappatura campo per campo e la traduzione degli stati.

## 1. Mappa le chiamate create e check

[`POST /v1/verify/verifications`](/docs/api/reference/create-verification) invia un codice di verifica. La richiesta minima è un destinatario:

```bash
curl -X POST https://us1.platform.bird.com/v1/verify/verifications \
  -H "Authorization: Bearer $BIRD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"to": {"phone_number": "+15551234567"}}'
```

[`POST /v1/verify/verifications/check`](/docs/api/reference/create-verification-check) invia ciò che l'utente ha digitato, identificato dallo stesso destinatario più il codice. I payload completi sono in [Invio delle verifiche](/docs/guides/verify/sending-verifications).

Quattro differenze da gestire durante il porting:

- **Il destinatario è la chiave.** I provider che restituiscono un SID o un ID di verifica se lo aspettano nella chiamata check. Bird fa il match sull'insieme di indirizzi, e la corrispondenza deve essere esatta: una verifica creata con email e numero di telefono non viene trovata con uno solo dei due. La colonna che contiene l'ID di verifica del provider può essere eliminata.
- **Un codice errato restituisce `200`.** La risposta contiene `success: false`, un `reason` tra `incorrect_code`, `expired` o `attempts_exhausted`, e `attempts_remaining`. Riserva il percorso di errore ai fallimenti della richiesta. Quando una verifica raggiunge uno stato finale, i check successivi restituiscono `404` anziché `success: false`.
- **Bird genera il codice e non lo restituisce mai.** Non esiste un parametro per un codice personalizzato, quindi un'integrazione che forniva il proprio codice di verifica, o lo leggeva dalla risposta per inviarlo autonomamente, non ha un equivalente qui.
- **Entrambi gli endpoint accettano `Idempotency-Key`.** Un replay dopo un timeout restituisce la risposta originale senza inviare un altro codice né consumare un tentativo.

Le opzioni per richiesta sono volutamente poche: `options.code_length` e `options.channels`, che riordina o restringe i canali per una singola richiesta. Tutto il resto è configurazione dello spazio di lavoro, non un campo sull'invio.

## 2. Configura canali, paesi e mittente

Bird consegna i codici tramite email, SMS, WhatsApp e Telegram. Per un destinatario telefonico, la maggior parte dei paesi prova prima WhatsApp con SMS come fallback, e la consegna passa al canale successivo nel piano quando un invio fallisce. Imposta l'ordine, o disattiva un canale, per paese nella pagina [**Countries**](https://bird.com/dashboard/w/verify/countries); disabilita i paesi che non servi, perché una destinazione inutilizzata è esposizione al pumping SMS anziché copertura.

Due lacune da verificare rispetto al flusso attuale prima di fissare una data:

- **Non esiste un canale a chiamata vocale né un'autenticazione silenziosa di rete.** Un flusso che ricorre a una telefonata per gli utenti che non possono ricevere SMS richiede una soluzione diversa qui.
- **Scegli il mittente prima del cutover.** Email, SMS e WhatsApp usano per impostazione predefinita Bird Verify e possono usare Authifly in alternativa. Puoi anche utilizzare il tuo dominio email verificato, un Sender ID SMS esistente o un numero WhatsApp collegato con un template di autenticazione approvato. Telegram usa il proprio account di notifica verificato. Se vuoi mantenere un mittente SMS che i tuoi utenti già riconoscono, verifica che sia supportato e registrato in ogni paese di destinazione. [Mittenti e branding](/docs/guides/verify/senders) illustra le opzioni e il comportamento di fallback.

Se usi un tuo numero WhatsApp, seleziona un template di autenticazione approvato esistente nella configurazione di Verify. Bird controlla il testo delle email e dei messaggi SMS. Non puoi passare un ID template o un corpo del messaggio personalizzato in una singola richiesta di verifica.

## 3. Porta il ciclo di vita della verifica

Una verifica resta `pending` fino alla risoluzione: `verified` quando un codice corretto arriva in tempo, `failed` con motivo `attempts_exhausted` o `undeliverable`, oppure `expired` con motivo `ttl_elapsed`. Mappa gli stati terminali del tuo provider su questi tre e tratta `reason` come un enum aperto.

I tempi che modellano la tua UI sono impostazioni dello spazio di lavoro nella pagina [**Configure**](https://bird.com/dashboard/w/verify/configure): durata di validità del codice, numero di tentativi di check consentiti e durata del cooldown per il reinvio. Impostali in modo che corrispondano all'esperienza attuale dei tuoi utenti, anziché riscrivere i testi della UI. La lunghezza del codice è l'unico valore impostabile anche per singola richiesta. I valori predefiniti e gli intervalli sono in [Impostazioni di verifica](/docs/guides/verify/sending-verifications#verification-settings).

Due comportamenti di solito sostituiscono codice che hai già:

- **Il reinvio è di nuovo la chiamata create.** Chiama create con lo stesso destinatario: dentro il cooldown restituisce la verifica attiva senza inviare, e dopo il cooldown parte un nuovo codice. Ogni codice inviato per una verifica attiva resta valido fino alla risoluzione della verifica, quindi un utente che inserisce il primo dopo l'arrivo del secondo non viene penalizzato.
- **"I didn't get a code" ha un proprio endpoint.** [`POST /v1/verify/verifications/next-channel`](/docs/api/reference/create-verification-next-channel) passa al canale successivo nel piano e invia immediatamente, ignorando il cooldown di reinvio ma mantenendo la scadenza, il budget di tentativi e la verifica. Collegalo al pulsante anziché ripetere i reinvii su un canale che non consegna.

Sopra le tue impostazioni ci sono guardrail della piattaforma che non configuri: un limite orario di invio per indirizzo e un limite di check per destinatario, entrambi restituiti con un `429` e un `Retry-After`. Se il tuo provider attuale ti permetteva di alzare i limiti per endpoint e lo hai fatto, confronta il tuo picco con i valori in [Guardrail anti-abuso](/docs/guides/verify/sending-verifications#abuse-guardrails) prima del passaggio.

## 4. Cambia i webhook

Verify emette eventi su due assi. Gli eventi di sessione, `verify.verification.created`, `verify.verification.verified` e `verify.verification.failed`, seguono la verifica stessa. Gli eventi di tentativo, `verify.attempt.sent`, `verify.attempt.delivered` e `verify.attempt.undelivered`, seguono ogni singolo invio di codice di verifica: un reinvio o un failover di canale aggiunge tentativi alla stessa sessione. Sottoscrivi un endpoint ai tipi che vuoi con [`POST /v1/webhooks`](/docs/api/reference/create-webhook); i payload sono in [Eventi di Verify](/docs/guides/verify/events).

Sottoscrivi gli eventi di sessione necessari alla tua integrazione. `verify.verification.failed` copre il vicolo cieco della consegna: si attiva con `reason: "undeliverable"` quando il piano è esaurito e i fallimenti registrati indicano che nessun codice di verifica è stato inviato, e il suo `last_attempt_reason` riporta l'errore sull'ultimo canale tentato. Una verifica che scade o esaurisce i tentativi di check non emette alcun evento di sessione: prendi questi due esiti dalla risposta del check.

Questi eventi servono per analytics, alerting e strumenti di supporto. La decisione di autenticazione viene dalla chiamata di check, che risponde in modo sincrono, e un flusso di login non dovrebbe mai attendere un webhook per far entrare un utente. La consegna è at-least-once e non ordinata, firmata secondo [Standard Webhooks](https://www.standardwebhooks.com): deduplica sull'header `webhook-id` come per qualsiasi altro evento Bird.

## 5. Passare in produzione una durata di codice alla volta

Verify non ha destinatari simulati: quello che vale la pena testare è l'arrivo del codice. Esegui l'integrazione con un numero di telefono e una casella email che controlli, su ogni canale abilitato, prima di toccare la produzione.

Il passaggio in produzione ha una regola facile da dimenticare. **Un codice emesso dal vecchio provider non può essere verificato da Bird, e viceversa.** Quindi commuta alla chiamata di create e, per la durata di un codice, instrada ogni check al provider che ha emesso quella verifica. In pratica:

1. Registra quale provider ha creato ogni verifica in corso.
2. Inizia a inviare una quota di nuove verifiche tramite Bird e verifica quelle con Bird.
3. Continua a verificare le verifiche più vecchie con il vecchio provider fino alla scadenza dell'ultima, che richiede una finestra di validità del codice più un margine.
4. Aumenta la quota di Bird quando i tassi di conversione della prima coorte sono soddisfacenti, poi dismetti il vecchio percorso.

Monitora la conversione, non solo la consegna. La pagina [**Verifications**](https://bird.com/dashboard/w/verify/verifications) e le metriche di Verify mostrano invii, consegne e quante verifiche hanno raggiunto `verified`: è il dato che ti dice se un ordine di canale o una nuova identità mittente ti sta costando registrazioni.

## Migrazione da un provider specifico

- [Twilio Verify](/docs/guides/verify/migrate/twilio): i Service diventano impostazioni dello spazio di lavoro, `VerificationCheck` diventa un check identificato dal destinatario, traduzione di canali e stati
- [Prelude](/docs/guides/verify/migrate/prelude): una struttura create-and-check quasi identica, con segnali di routing e verifica silenziosa come parti non portabili

## Passi successivi

- [Invio delle verifiche](/docs/guides/verify/sending-verifications): contratto completo di request e response, stati e limiti
- [Configurazione per paese](/docs/guides/verify/countries): ordine dei canali e disponibilità per paese
- [Mittenti e branding](/docs/guides/verify/senders): aspetto di ogni messaggio e mittente email brandizzato
- [Eventi di Verify](/docs/guides/verify/events): payload degli eventi di sessione e di tentativo

## Related resources

- [Verify phone numbers at signup](/learn/series/verify-phone-numbers-at-signup) (video)
- [What does OTP mean? One-time passwords explained](/explained/verify/what-does-otp-mean) (answer)
- [Customer verification](/verify-api) (product)
- [Build your first integration](/learn/paths/integration) (course)

[Get an implementation brief](/learn/workspace?topic=verify)