Domande · Indirizzi

Esiste un'API per normalizzare gli indirizzi italiani?

Cosa fa la chiamata

L'endpoint di verifica contatto sistema l'indirizzo secondo la forma di recapito corretta, il nominativo e, se lo mandi, il codice fiscale: lo ripulisce, completa il carattere di controllo se manca solo quello, e lo confronta con cognome, nome e data di nascita per dirti se torna. Legge via, civico, CAP, comune e provincia insieme, non un campo alla volta, e dichiara ogni correzione.

Un contatto alla volta nel corpo della richiesta, oppure una lista nel campo elementi, fino a cinquecento per chiamata. Ogni chiamata richiede un token, che generi dalla tua area personale una volta registrato, e lo passi nell'header Authorization: Bearer. Il token si può far scadere a una data scelta da te, o lasciarlo valido finché non lo revochi.

Come torna il risultato

La risposta ha due forme dello stesso indirizzo: una leggibile con gli accenti, l'altra nella forma richiesta per la stampa delle etichette, dove gli accenti diventano apostrofi e tutto è in maiuscolo. Ti servono entrambe per motivi diversi: la prima per mostrare l'indirizzo a un operatore o dentro un'interfaccia, la seconda per la stampa vera e propria.

Insieme trovi un esito a parole chiave — corretto, modificato con il dettaglio di cosa è cambiato campo per campo, oppure da controllare quando l'indirizzo non si riesce a ricostruire con certezza, con il motivo scritto in chiaro: via non trovata nel comune, dati insufficienti, civico mancante. Niente è mai corretto in silenzio: se cambiamo qualcosa te lo diciamo, e se non siamo sicuri lo diciamo altrettanto chiaramente invece di indovinare.

Singolo indirizzo o lavori in blocco

Sotto le cinquecento richieste hai la risposta subito, nella stessa chiamata: è il caso tipico di un form di registrazione o di un checkout, dove l'indirizzo va verificato nel momento in cui l'utente lo scrive. Per liste più grandi, fino a centomila indirizzi in una volta, aggiungi "asincrono": true: la richiesta torna subito un codice di lavoro e l'elaborazione entra in coda, la stessa che gestisce i lavori in blocco caricati dal sito. Rileggi il risultato con una GET sullo stesso endpoint passando il codice, in JSON o, se ti serve il file da scaricare, in CSV.

Questo secondo caso è quello di chi ha già un'anagrafica intera da sistemare e vuole farlo dal proprio sistema invece che caricare un file dal sito: stesso motore, stessa coda, un solo lavoro anche per centomila righe.

Autocomplete per i tuoi form

Se stai costruendo un form di indirizzo, /api/v1/suggerisci ti dà l'autocomplete mentre l'utente digita: via, comune e civico proposti a mano a mano, con il campo già verificato alla selezione invece di doverlo controllare dopo con una chiamata separata. Va usato da un server tuo, che fa da proxy verso l'endpoint: il token non deve mai comparire nel browser dell'utente finale.

Quando ha senso integrarla

Ha senso quando l'indirizzo entra in anagrafica più e più volte, non una tantum: un form di registrazione, un checkout ecommerce, un CRM alimentato da più canali. Verificarlo lì, nel momento in cui entra, evita di accumulare indirizzi scorretti che poi vanno ripuliti in blocco prima di ogni spedizione. Se invece hai già una lista da sistemare una volta sola, è più semplice caricarla come file Excel o CSV dal sito: stesso motore, senza scrivere una riga di codice.

Errori, limiti e documentazione completa

Ogni risposta ha un codice HTTP coerente con quello che è successo: 401 se il token manca o non è valido, 413 se il lotto supera il limite, 429 se hai superato il numero di richieste al minuto consentito, 402 se il credito non è sufficiente a coprire la chiamata. Un indirizzo che non si riesce a normalizzare non è un errore dell'API: la risposta arriva comunque, con l'esito che spiega perché.

Nella pagina API trovi tutti gli endpoint — indirizzo, deduplica, codice fiscale, email, telefono, sito, arricchimento del nominativo — con i parametri, gli esempi curl e i codici di errore per esteso. Se lavori con uno strumento che importa specifiche, c'è anche openapi.json.

Una chiamata minima

La risposta completa porta anche la forma per la stampa, il dettaglio di ogni campo cambiato e i dati così come li hai mandati, per confronto.