Flusso di lavoro API per la validazione email: dalla sandbox alla produzione con FairValid

Flusso di lavoro API per la validazione email: dal test in sandbox ai risultati in produzione

Domanda: sei uno sviluppatore che sta aggiungendo la verifica email al proprio sistema. Quali passaggi ti portano dalla prima chiamata di test a risultati affidabili in produzione?

Risposta breve: inizia con una chiave Test e la sandbox gratuita. Poi passa a una chiave Live con i soli ambiti di cui hai bisogno. Invia ogni richiesta con una chiave di idempotenza. Leggi lo stato del job e scorri le pagine dei risultati. Gestisci separatamente ogni esito e ogni codice di errore. I passaggi seguenti si basano sul riferimento API per i clienti di FairValid.

Passaggio 1: sviluppa prima usando la sandbox

Crea una chiave Test nella pagina delle chiavi API e conservala sul tuo server. Il riferimento usa due variabili d'ambiente, FAIRVALID_API_KEY e FAIRVALID_BASE_URL. Le chiavi Test non effettuano chiamate al provider e non consumano crediti.

Le chiavi Test accettano solo un piccolo insieme di indirizzi riservati sul dominio example.com. Questi indirizzi simulano gli esiti valido, non valido, catch-all, sconosciuto, in attesa e non disponibile. Trovi gli indirizzi esatti nella sezione "Sandbox gratuita" del riferimento API. I job di test restituiscono stati fissi e ripetibili: completato, in attesa, non riuscito o annullato. I job di test in blocco supportano stato, risultati e annullamento.

La sandbox ti mostra questi esiti specifici. Non copre tutti i percorsi che la tua integrazione può seguire, quindi prevedi una gestione separata per i codici di errore descritti nel passaggio 7.

I job di test in blocco sono limitati a 20 nuovi job per workspace all'ora, oppure 100 ogni 30 giorni. Il superamento di uno dei due limiti restituisce HTTP 429. Un nuovo tentativo identico restituisce comunque il job originale.

Passaggio 2: passa a una chiave Live con gli ambiti necessari

Per la produzione, crea una chiave Live con ambito submit. Usa POST /api/v1/jobs per i lotti oppure POST /api/v1/verifications per un singolo indirizzo. Aggiungi l'ambito read se la chiave deve anche leggere lo stato dei job e i risultati. Le chiavi Live possono avere anche un ambito balance. Separatamente, GET /api/v1/balance legge i crediti disponibili e trattenuti del workspace. Il segreto completo viene mostrato una sola volta, quindi conservalo in modo sicuro quando crei la chiave.

I job Live usano la coda di verifica e il saldo crediti del tuo workspace. Restano comunque validi gli ambiti delle chiavi, i limiti delle chiavi, l'accesso al workspace e i limiti di elaborazione.

Passaggio 3: invia un job con una chiave di idempotenza

Un job accetta da 1 a 5.000 indirizzi in JSON, fino a 2 MiB. Invia un'intestazione Idempotency-Key con ogni invio di job e ogni invio live di un singolo indirizzo. La chiave deve essere lunga da 8 a 128 caratteri e può contenere lettere, cifre, punti, due punti, trattini bassi o trattini.

• Un nuovo job restituisce HTTP 202 con un job_id in formato UUID.
• Un nuovo tentativo corrispondente restituisce HTTP 200 con lo stesso job.
• Riutilizzare una chiave di idempotenza con un corpo modificato restituisce HTTP 409 idempotency_conflict.

Se non riesci a capire se una richiesta è andata a buon fine, riprova con la stessa chiave API, la stessa chiave di idempotenza e lo stesso corpo normalizzato. La riesecuzione è limitata alla chiave API, quindi sostituire quella credenziale e inviare di nuovo può creare una seconda esecuzione. Usa una nuova chiave di idempotenza solo quando vuoi davvero una nuova esecuzione, che potrebbe essere addebitata.

Passaggio 4: leggi il job e scorri le pagine dei risultati

Leggi il job con GET /api/v1/jobs/{id}. Il suo stato può essere queued, running, paused, canceling, canceled o completed. Leggi i risultati con GET /api/v1/jobs/{id}/results. Ogni pagina restituisce fino a 50 risultati più un next_cursor firmato. Passa quel valore come parametro di query cursor. In questo modo vengono mantenuti il filtro e la ricerca originali.

I filtri sono all, valid, invalid, catch_all, unknown, still_checking e not_checked. Per interrompere un job, POST /api/v1/jobs/{id}/cancel richiede l'annullamento, ma il lavoro già in corso potrebbe comunque concludersi.

Il riferimento descrive anche un evento di completamento firmato e rimanda alla gestione dei webhook.

Passaggio 5: tratta ogni esito come uno stato a sé

La guida ai risultati spiega il significato di ciascun risultato:

• Valido: una verifica positiva utilizzabile. Non garantisce mai la consegna in casella.
• Non valido: l'indirizzo non ha superato la verifica.
• Catch-all: il dominio potrebbe accettare molti indirizzi, quindi una conclusione a livello di casella potrebbe essere meno certa. Leggi il dettaglio prima di usarlo.
• Sconosciuto: la verifica non è riuscita a restituire una risposta affidabile.
• Verifica in corso: non c'è ancora una risposta definitiva.

La guida descrive gli errori tecnici e gli elementi non elaborati separatamente da Sconosciuto, e l'API offre unknown, still_checking e not_checked come filtri distinti. Mantieni questi stati in campi o stati separati nei tuoi dati, invece di unirli in Sconosciuto.

Passaggio 6: comprendi i crediti trattenuti prima di riconciliare

Il riferimento API indica che i crediti del workspace vengono riservati man mano che le verifiche vengono ammesse all'elaborazione. I risultati seguono poi le stesse regole di addebito e restituzione della dashboard. La pagina prezzi di FairValid spiega che una trattenuta di crediti riserva spazio per una verifica in corso e che il risultato finale determina l'addebito:

• Valido o non valido: 1 credito per ogni risultato completato.
• Sconosciuto o catch-all: alla fine non viene detratto alcun credito di verifica. I crediti trattenuti vengono svincolati o restituiti.
• Verifica in corso: nessun addebito definitivo per ora. Una trattenuta non è un addebito completato.
• Errori tecnici e lavoro non elaborato: alla fine non viene detratto alcun credito di verifica. Le riserve vengono svincolate o restituite.

Se controlli il saldo mentre un job è in corso, ricorda che i crediti trattenuti non sono ancora addebiti definitivi. Riconcilia dopo che i risultati sono definitivi. Ogni account include 300 crediti gratuiti al mese. Vengono usati per primi e non si accumulano nei mesi successivi. I crediti acquistati non utilizzati restano disponibili finché l'account rimane aperto.

Passaggio 7: gestisci gli errori in base alla causa, non con un'unica regola di ripetizione

• 401: la chiave manca, è stata revocata o non ha l'ambito necessario. Correggi la credenziale o i suoi ambiti.
• 402 key_cap_reached: la nuova richiesta supererebbe il limite complessivo della chiave e non è stato creato alcun job né alcuna trattenuta. Il limite conta i crediti già addebitati più quelli riservati per le identità univoche accettate. Trattandosi di un limite complessivo, non si ricarica nel tempo e attendere non lo azzera. Chiedi a qualcuno con accesso di rivedere l'impostazione del limite di quella chiave. Un limite non può aggiungere crediti al workspace.
• 422: indirizzi non validi o limiti dell'elenco. Correggi l'input.
• 503 live_verification_unavailable: durante una pausa operativa, un nuovo invio live può restituire questo errore senza trattenere crediti. Riprova più tardi con la stessa chiave di idempotenza. Un 503 dopo un invio dall'esito incerto non dimostra che non sia stato creato alcun job, quindi riutilizza la chiave originale.

Ogni errore include un codice, un messaggio e un ID richiesta. Registra tutti e tre per averli a disposizione se contatti l'assistenza.

Un ordine di lavoro sensato

1. Sviluppa l'integrazione usando la sandbox e verifica che ogni esito simulato finisca dove ti aspetti.
2. Aggiungi una gestione esplicita per i codici di errore indicati sopra.
3. Crea una chiave Live con gli ambiti più ristretti necessari e un limite adeguato al tuo budget.
4. Inizia con un piccolo job live. Confronta i risultati e lo stato dei crediti con la dashboard, poi aumenta i volumi.

Se vuoi provare questo flusso di lavoro, la sandbox gratuita ti permette di testare gli esiti simulati senza consumare crediti. Il riferimento API contiene i dettagli esatti delle richieste.