Verifica indirizzi

L’endpoint POST /api/v1/integrations/addresses/check-address interroga il corriere collegato alla tua company e restituisce un esito normalizzato, indipendente dal formato interno di ogni corriere. La risposta include sempre status, code, message, carrierCode, carrierName, verificationType, countryScope e suggestions.

Flusso consigliato

Ottieni il corriere

Recupera carrierCompanyId da GET /api/v1/integrations/carriers.

Verifica l'indirizzo

Invia l’indirizzo con POST /api/v1/integrations/addresses/check-address.

Valuta l'esito

Leggi code insieme a status e, se presenti, valuta gli elementi in suggestions.

status e code non sono ridondanti: status raggruppa l’esito per logiche di blocco UI, mentre code indica il motivo preciso (es. correzione suggerita vs indirizzo non trovato).

Codici esito

Codice normalizzato dell’esito della verifica. Usalo per la logica applicativa; status resta la sintesi per UI e blocchi.

Codice	`status` tipico	Significato
`ADDRESS_VALID`	`success`	Indirizzo verificato con successo. Eventuali `suggestions` contengono la versione normalizzata restituita dal corriere.
`ADDRESS_NORMALIZED`	`warning`	Il corriere propone una correzione (via, CAP, comune, …). Valuta `suggestions` e scegli se applicarla o mantenere l’indirizzo originale.
`ADDRESS_NOT_FOUND`	`warning` o `error`	Indirizzo non presente nello stradario o nel servizio di validazione del corriere. `suggestions` è vuoto.
`ADDRESS_INVALID`	`error`	Indirizzo rifiutato: formato errato, area non servita o dati incoerenti secondo il corriere.
`VERIFICATION_SKIPPED_FOREIGN`	`skipped`	Verifica non eseguita perché il corriere opera solo in Italia e il paese richiesto non è `IT`. Non blocca la spedizione.
`VERIFICATION_SKIPPED_UNSUPPORTED`	`unsupported`	Il corriere non espone un’API di verifica indirizzo. `verificationType` è `none`.
`VERIFICATION_ERROR`	`error`	Errore tecnico durante la chiamata (configurazione mancante, risposta non valida, eccezione).
`CARRIER_UNAVAILABLE`	`skipped`	Servizio del corriere temporaneamente non raggiungibile (timeout, errore di rete). La verifica non è stata eseguita.

Azioni suggerite in integrazione

`code`	Azione suggerita
`ADDRESS_VALID`	Procedi con l’indirizzo (eventualmente quello in `suggestions[0]` se normalizzato).
`ADDRESS_NORMALIZED`	Mostra i suggerimenti all’utente o applica automaticamente la prima proposta.
`ADDRESS_NOT_FOUND`, `ADDRESS_INVALID`	Chiedi correzione manuale dell’indirizzo prima della spedizione.
`VERIFICATION_SKIPPED_FOREIGN`	Procedi: verifica stradario non applicabile all’estero per quel corriere.
`VERIFICATION_SKIPPED_UNSUPPORTED`	Procedi senza verifica automatica.
`VERIFICATION_ERROR`	Ritenta o segnala errore; non assumere che l’indirizzo sia valido o invalido.
`CARRIER_UNAVAILABLE`	Ritenta più tardi; in assenza di verifica non bloccare per questo motivo.

Tipi di verifica

Metadato informativo: indica quale metodo il corriere usa (o avrebbe usato) per la verifica. L’esito operativo resta in code.

Valore	Corrieri	Descrizione
`street_registry`	GLS	Verifica tramite stradario (via, CAP, comune, provincia) per indirizzi in Italia.
`routing`	BRT	Verifica tramite motore di instradamento: capacità di recapito e suggerimenti di correzione.
`postal_validation`	FedEx, DHL Express	Validazione postale internazionale (normalizzazione CAP, città, paese).
`transit_time`	Poste Delivery Business	Stima del tempo di transito sul CAP; la via non viene validata.
`none`	Corrieri senza API / skip	Nessuna verifica applicabile.

Campo `countryScope`

Valore	Significato
`domestic_it`	Verifica pensata per spedizioni in Italia (GLS, BRT, Poste).
`international`	Validazione postale senza vincolo domestico (FedEx, DHL).
`any`	Corriere senza verifica o risposta di skip/unsupported.

Esempio di risposta

{
  "status": "warning",
  "code": "ADDRESS_NORMALIZED",
  "message": "Indirizzo corretto da BRT. Seleziona il suggerimento o mantieni l'originale.",
  "carrierCode": "BRT",
  "carrierName": "BRT",
  "verificationType": "routing",
  "countryScope": "domestic_it",
  "suggestions": [
    {
      "streetLine1": "Via Roma 1",
      "city": "Torino",
      "zip": "10121",
      "province": "TO",
      "country": "IT"
    }
  ]
}

Riferimento OpenAPI

Gli enum CheckAddressCode e CheckAddressVerificationType nello schema OpenAPI elencano i valori ammessi. Il significato di ogni valore è documentato in questa pagina.

Introduzione

Health

Marketplaces

Carriers

Indirizzi

Spedizioni

Depositi

Webhook

Verifica indirizzi

Flusso consigliato

Codici esito

Azioni suggerite in integrazione

Tipi di verifica

Campo `countryScope`

Esempio di risposta

Riferimento OpenAPI

​Flusso consigliato

​Codici esito

​Azioni suggerite in integrazione

​Tipi di verifica

​Campo countryScope

​Esempio di risposta

​Riferimento OpenAPI

Flusso consigliato

Codici esito

Azioni suggerite in integrazione

Tipi di verifica

Campo `countryScope`

Esempio di risposta

Riferimento OpenAPI