O padrão ISO 3166 é a família de normas que dá nome curto a países e às suas divisões internas, e é o que permite que dois sistemas troquem informação geográfica sem depender do idioma. Quem já viu o mesmo país escrito de três formas diferentes em um mesmo banco de dados conhece o problema que essa norma resolve. Neste texto, explicamos quais códigos existem, como eles se relacionam e como usá-los sem criar inconsistência.
As três formas de escrever um país
O padrão define três representações para cada país:
- O código de duas letras, chamado de alfa-2. É a forma mais usada em troca de dados, em formulários e em sistemas bancários, justamente por ser curta.
- O código de três letras, chamado de alfa-3. Aparece em contextos em que a clareza vale mais do que o espaço, e é mais fácil de associar ao nome do país por um leitor humano.
- O código numérico de três posições. A vantagem é ser independente de alfabeto, o que evita problemas de transcrição quando os dados passam por sistemas com escrita diferente.
As três identificam exatamente o mesmo país. Elas não são versões concorrentes, e sim apelidos diferentes do mesmo objeto.
Por que misturar os três causa problema?
Se um sistema guarda o país em alfa-2 e outro espera alfa-3, a comparação falha sem que ninguém tenha cometido um erro visível. O valor parece plausível dos dois lados, o formulário aceita, e a divergência só aparece quando uma junção entre tabelas devolve vazio ou quando um relatório conta o mesmo país duas vezes.
O cenário clássico é a planilha importada de uma fonte externa. Uma coluna traz códigos de duas letras, a outra traz códigos de três, e a equipe decide “normalizar depois”. Depois nunca chega, e o relatório de vendas por país passa a ter linhas duplicadas que ninguém sabe explicar.
A prevenção é escolher uma forma como canônica na entrada do sistema e converter na borda, quando os dados entram. Converter na saída, para cada tela, é mais caro e mais fácil de esquecer.
ISO 3166 e os códigos de subdivisão não são a mesma coisa
Existe uma parte da norma dedicada às divisões dentro de cada país, e os códigos que ela produz têm um formato combinado: o código do país, um separador e um código local da divisão. Estados, províncias, prefeituras e regiões ganham um identificador estável desse jeito.
É importante não confundir isso com as listas que cada país mantém para uso interno. Órgãos de estatística, serviços postais e administrações tributárias publicam seus próprios códigos de região, e esses códigos costumam ter regras diferentes, comprimentos diferentes e finalidades diferentes. Um código de subdivisão da norma internacional e um código regional de uso interno podem descrever a mesma área sem ter o menor grau de parentesco.
Para software, a diferença importa. Se o formulário precisa de uma lista suspensa de províncias, ela deve vir de uma fonte única e ser identificada como tal. Misturar as duas famílias no mesmo campo produz uma lista com valores duplicados, porque a mesma província aparece duas vezes com grafias de origem distinta.
Quem pode inventar um código de país?
Ninguém. Um código só existe quando consta da lista oficial da norma, e o mesmo vale para as subdivisões: elas são definidas pelo país interessado e publicadas. Criar um código próprio para uma região que não tem um é uma decisão que parece inocente e cobra caro depois, quando os dados precisam ser trocados com terceiros.
O caminho correto, quando falta um código, é usar um valor neutro e explícito, reservado para esse fim pelo próprio sistema, e registrar o motivo. Guardar uma sigla inventada no mesmo campo dos códigos reais destrói a possibilidade de validação automática.
O que fazer com códigos antigos
Os países mudam. Territórios se separam, nomes são alterados e códigos deixam de ser usados. A norma acompanha isso com atualizações, e um sistema que opera por anos vai encontrar registros antigos.
Três abordagens funcionam na prática:
| Situação | Abordagem recomendada |
|---|---|
| Código atual | Tratar como valor normal |
| Código descontinuado | Manter a leitura e converter na importação |
| Código desconhecido | Rejeitar na entrada e registrar para análise |
O ponto importante é não descartar silenciosamente um valor que o sistema não reconhece. Um código desconhecido pode ser um erro de digitação, um código novo ou um dado importado de um sistema legado, e as três situações pedem tratamento diferente.
Usando os códigos no gerador
No gerador de endereços, a escolha do país é o ponto de partida de tudo: a partir dela vêm a divisão administrativa, a cidade, o código postal e o telefone, todos retirados do mesmo registro. Isso garante que um exemplo de endereço do Japão não misture uma divisão de outro país.
Para quem testa integrações que recebem código de país de terceiros, vale gerar exemplos de países que costumam aparecer com grafia diferente e conferir se o sistema aceita a forma canônica escolhida. Países com nome longo ou com caracteres não latinos são os candidatos naturais a esse teste.
Para quem desenvolve: escolher e manter o código
A decisão que mais economiza trabalho é definir, desde o começo, qual representação é a canônica no armazenamento. A recomendação usual é a de duas letras para chaves e índices, porque é curta e amplamente suportada.
Em seguida, vale tratar a lista de países como dado, e não como constante espalhada pelo código. Uma tabela única, versionada e revisada, permite atualizar a lista sem caçar literais em vários arquivos. O rótulo exibido ao usuário também pertence a essa tabela, porque ele precisa acompanhar o idioma da interface e não o idioma dos dados.
Para as subdivisões, a mesma lógica: uma tabela por país, com o código e o rótulo, e uma regra clara sobre o que fazer quando o país não tem subdivisões relevantes para cadastro. Um campo de divisão obrigatório para um país que não usa esse conceito é uma exigência impossível de cumprir.
Por fim, preveja o caso do código desconhecido. Aceitar qualquer par de letras como se fosse um país válido transforma um erro de digitação em dado permanente.
Próximos passos
Se você tem uma base com códigos de país misturados, comece identificando quantas formas aparecem na mesma coluna e escolha uma como canônica antes de qualquer conversão. Se precisa de exemplos para testar, gere endereços no gerador de endereços e confira também como o site organiza a lista de países e suas divisões para montar a sua própria verificação.