Convalidi il formato del codice postale per Paese
I codici postali sono brevi, ma il loro formato cambia notevolmente da un Paese all’altro.
Esegui gratis nel browser
Questa capacità riceve un CAP o ZIP insieme a un codice Paese di due lettere e controlla il valore rispetto alla struttura nazionale standard. Fornisce una risposta deterministica senza rete, geocodifica o banca dati di indirizzi. La usi per individuare lettere fuori posto, cifre mancanti e separatori errati prima che i dati raggiungano pagamento, spedizione, fatturazione o anagrafiche clienti. Un Paese non riconosciuto produce un chiaro errore di input.
Convalidi il formato nel contesto nazionale corretto
Non si può valutare correttamente un codice postale senza conoscerne il Paese. Cinque cifre sono normali negli Stati Uniti, in Francia, Germania e Spagna, ma non bastano per India, Cina o Singapore. Il Canada alterna lettere e numeri, la Polonia richiede un trattino e il Regno Unito adotta diverse strutture alfanumeriche. Questa capacità mantiene separate le regole e seleziona un solo modello mediante il codice Paese di due lettere. Elimina gli spazi esterni innocui e accetta il Paese senza distinzione tra maiuscole e minuscole, ma non riscrive silenziosamente il codice postale. La risposta riporta il Paese normalizzato, il codice ripulito alle estremità, il formato atteso e un valore booleano. L’applicazione può decidere in base al booleano, mentre il modulo può indicare la forma corretta quando il dato non è valido. Se il Paese non è presente nella tabella supportata, la richiesta fallisce esplicitamente invece di classificare come errato qualsiasi valore sconosciuto. Tale distinzione impedisce che una copertura incompleta generi indicazioni fuorvianti sulla qualità dei dati.
Comprenda cosa dimostra il controllo del formato
L’algoritmo verifica la struttura, non l’esistenza o la consegnabilità. Un esito valido significa che caratteri, lunghezza e separatori rispettano il modello rappresentato per quel Paese. Non conferma che l’autorità postale abbia assegnato il codice, che una via appartenga alla zona o che un corriere serva la destinazione. Queste affermazioni richiedono dati esterni aggiornati e spesso un indirizzo completo. Il confine va mantenuto chiaro: la convalida deterministica è veloce, privata e ripetibile, mentre verificare la consegna è un altro servizio. Il validatore conserva gli zeri iniziali perché i codici postali sono identificatori, non numeri. Li invii come stringhe per preservare valori italiani, francesi o di alcune aree statunitensi. Le lettere non distinguono maiuscole e minuscole dove previsto e gli spazi facoltativi sono accettati soltanto nei sistemi in cui sono consueti. La punteggiatura non viene eliminata globalmente, poiché un separatore può essere obbligatorio in un Paese e scorretto altrove. L’etichetta del formato descrive la forma richiesta senza sostenere che ogni combinazione possibile sia realmente assegnata.
Convalidi nel primo punto di ingresso dei dati
Il momento più utile per il controllo è subito dopo la scelta del Paese e l’inserimento del codice postale. Un checkout può chiamare la capacità prima di creare l’ordine, una registrazione può segnalare un probabile refuso prima di salvare il profilo e un’importazione può provare ogni riga prima di unirla all’anagrafica clienti. Nei moduli interattivi mantenga visibile il valore originale e usi il formato restituito come guida, senza sostituire il testo all’improvviso. Nei processi in serie registri il booleano e il Paese accanto alla riga, così da separare valori malformati da Paesi non supportati. La funzione è deterministica e non usa rete, casualità, orologio o stato mutabile: lo stesso input produce sempre la medesima risposta. L’automazione API costa $0.002 per richiesta completata e ogni codice è un elemento misurabile. Consideri un risultato falso come richiesta di correzione, non come prova di frode o di indirizzo inesistente. Un errore di Paese sconosciuto segnala una scelta di configurazione o copertura da affrontare esplicitamente.
Casi d'uso
Riscontro durante il checkout
Controlli il codice dopo la scelta del Paese e mostri il formato nazionale prima di creare l’etichetta di spedizione.
Qualità delle importazioni CRM
Segnali i codici malformati mantenendo separati i Paesi non supportati dai normali valori non validi.
Moduli per più Paesi
Applichi le regole corrette per lettere, cifre, lunghezza e separatori senza gestire un’espressione regolare in ogni applicazione.
Domande frequenti
Un risultato valido dimostra che l’indirizzo esiste?
No. Dimostra soltanto che il codice rispetta la struttura del Paese; non ne conferma assegnazione o consegnabilità.
Cosa accade con un Paese non riconosciuto?
La richiesta restituisce un errore di input non valido. La mancanza di copertura non diventa mai un falso risultato fuorviante.
È opportuno inviare i codici postali come numeri?
No. Li invii come testo per conservare zeri iniziali, lettere, spazi e segni obbligatori.
Sono accettate le lettere minuscole?
Sì, nei sistemi alfabetici. Anche il Paese ignora la distinzione e viene restituito in maiuscolo.
Quanto costa la convalida?
Ogni richiesta API completata correttamente costa $0.002. Gli input errati vengono segnalati come errori.
Per sviluppatori — accesso via API
Tutto quello che vedi in questa pagina è disponibile anche via API. Questa sezione è per i team che vogliono integrarlo nei propri sistemi; chi non ne ha bisogno può semplicemente usare lo strumento qui sopra.
Endpoint
Autenticazione con Bearer token: un POST mette in coda l'attività e il risultato arriva via webhook o link firmato.
Chiamala dal tuo stack
curl -X POST https://api.kit.forhosting.com/data/postal-code-validate \
-H "Authorization: Bearer $KIT_KEY" \
-H "Content-Type: application/json" \
-d '{"postal_code":"94105","country_code":"US"}'const res = await fetch("https://api.kit.forhosting.com/data/postal-code-validate", {
method: "POST",
headers: {
"Authorization": `Bearer ${process.env.KIT_KEY}`,
"Content-Type": "application/json"
},
body: JSON.stringify({
"postal_code": "94105",
"country_code": "US"
})
});
const { task_id } = await res.json();import os, requests
res = requests.post(
"https://api.kit.forhosting.com/data/postal-code-validate",
headers={"Authorization": f"Bearer {os.environ['KIT_KEY']}"},
json={
"postal_code": "94105",
"country_code": "US"
},
)
task_id = res.json()["task_id"]<?php
$res = file_get_contents("https://api.kit.forhosting.com/data/postal-code-validate", false, stream_context_create([
"http" => [
"method" => "POST",
"header" => "Authorization: Bearer " . getenv("KIT_KEY") . "\r\nContent-Type: application/json",
"content" => '{"postal_code":"94105","country_code":"US"}',
],
]));
$task = json_decode($res, true);body := bytes.NewBufferString(`{"postal_code":"94105","country_code":"US"}`)
req, _ := http.NewRequest("POST", "https://api.kit.forhosting.com/data/postal-code-validate", body)
req.Header.Set("Authorization", "Bearer "+os.Getenv("KIT_KEY"))
req.Header.Set("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)Esempio di richiesta
{
"postal_code": "94105",
"country_code": "US"
}Esempio di risposta
{
"task_id": "tsk_a1b2c3d4e5f6a1b2c3d4e5f6",
"type": "data.postal_code_validate",
"status": "queued",
"_links": {
"result": "/tasks/tsk_…/result"
}
}L'API è asincrona: ricevi subito un task_id e puoi fare polling fino a 1 richiesta al secondo.
Prezzi
Prezzo pubblicato, senza token né crediti. Se l'attività fallisce, non paghi.
Limiti
max_mb | 25 |
Errori
| HTTP | Codice | Significato |
|---|---|---|
401 | unauthorized | Chiave API mancante o non valida: controlla l'header Authorization. |
402 | insufficient_balance | Credito esaurito: ricarica per continuare a eseguire attività. |
404 | unknown_type | Tipo di attività sconosciuto: controlla il campo type della richiesta. |
429 | rate_limited | Troppe richieste in poco tempo: rallenta e riprova tra qualche secondo. |