O formato de endereço por país é uma daquelas coisas que só se percebe errada quando o produto já está no ar em vários mercados. O que funciona para um endereço britânico não funciona para um japonês, e o que os dois têm em comum não cobre metade da América Latina. A dificuldade não está em conhecer um formato, e sim em desenhar um modelo de dados que aceite todos ao mesmo tempo sem virar uma colcha de retalhos de condições especiais. Neste texto, comparamos as grandes famílias de estrutura, mostramos onde a obrigatoriedade de cada campo muda, discutimos o compromisso das linhas genéricas e propomos um caminho para manter o conjunto atualizado.
Quais são as grandes famílias de ordem dos campos?
Existem duas direções predominantes e uma terceira que combina as duas. Na primeira, o endereço é escrito do menor para o maior: número e via, depois bairro ou cidade, depois região e por fim país. É o padrão da maior parte das tradições de língua inglesa, e é o que a maioria dos formulários ocidentais assume como natural.
Na segunda, a ordem é inversa, do maior para o menor: província ou prefeitura, depois cidade ou distrito, depois bairro e só então o número e a via. É o padrão do Japão, e aparece em outras tradições do leste asiático. Um formulário que usa a primeira ordem e recebe um endereço japonês escrito na segunda vai guardar os dados na hierarquia errada, e o erro é invisível porque todos os campos ficam preenchidos.
A terceira família tem camadas administrativas em número maior do que o esperado. Em vários países da América Latina um endereço tem bairro, município, departamento e, por vezes, uma divisão intermediária, e a quantidade de níveis não cabe em um modelo de cidade e estado. O mesmo acontece em partes da Europa, onde a comuna, o distrito e a região coexistem com nomes que o formulário não previu.
O que muda na ordem turca e nas camadas intermediárias?
A Turquia fica em uma posição intermediária. O endereço é composto por província, distrito, bairro, via e números, e a ordem escrita no correio não é a ordem em que os campos são preenchidos por quem mora lá. Um formulário que impõe a ordem ocidental recebe os dados fora de sequência, e o valor do bairro acaba no campo da cidade.
O ponto geral, que vale para todos os países, é que o modelo de dados e a ordem de exibição são decisões separadas. O modelo guarda cada nível em um campo próprio, com o nome e o significado daquele nível naquela jurisdição. A exibição usa a ordem local. Misturar as duas coisas é o que produz a perda de informação, porque um campo chamado cidade que na verdade recebe um distrito não pode ser corrigido depois sem migração.
Quem trabalha com vários mercados ao mesmo tempo costuma manter um campo rotulado para cada nível, e uma tabela que diz quais níveis existem em cada país e qual deles é obrigatório. O texto sobre formato internacional de endereço trata desse arranjo, e o resumo sobre cenários de endereço transfronteiriço cobre os casos em que o cadastro tem endereços em países diferentes.
Como variam os códigos postais?
Os códigos postais são a fonte mais comum de suposição errada. Há países com cinco dígitos puramente numéricos, países com sequências alfanuméricas que misturam letras e números em posições fixas, países com quatro dígitos, países com códigos de seis dígitos e países que simplesmente não usam código postal.
Há também os que usam o código como parte da localização administrativa, com significado vinculado à região, e os que usam o código apenas como rota de entrega, sem vínculo administrativo. Para a validação, isso muda tudo: exigir um código com comprimento fixo é errado em quase todos os mercados, e aceitar qualquer sequência é aceitar erro de digitação.
O caminho que funciona é tratar o código postal como campo de texto, com uma regra de formato definida por país e uma marcação clara de obrigatoriedade. Zero à esquerda é um caso clássico: vários países têm códigos que começam por zero, e um sistema que guarda o campo como número perde o dígito. O resumo sobre formatos de código postal por país reúne as variações mais relevantes.
Quais campos existem em um país e não existem em outro?
Divisão administrativa é o exemplo mais claro. Em alguns países o nível intermediário é obrigatório e tem lista fechada; em outros o campo nem existe. Um formulário que o torna obrigatório para todos os países bloqueia o cliente que mora em um lugar onde aquele nível não é usado, e a mensagem de erro não faz sentido no contexto dele.
Bairro é o segundo caso. Em algumas tradições ele é parte essencial do endereço, em outras é referência opcional e em outras nem aparece. Complemento de unidade é outro: essencial em prédios de apartamentos, irrelevante em casas, obrigatório em alguns mercados e dispensável em outros.
Há ainda o campo de município, que em alguns países é a menor unidade administrativa com governo próprio e em outros é apenas uma subdivisão interna. Um modelo que trata cidade e município como sinônimos perde informação em qualquer mercado onde os dois coexistam.
A consequência para teste é direta: a obrigatoriedade precisa ser avaliada por país, e não fixada no código. Um caso de teste que troca o país e verifica se a obrigatoriedade foi recalculada é o que mais encontra defeito nesse tipo de formulário.
As linhas genéricas resolvem ou apenas adiam o problema?
Muitos sistemas adotam o modelo de linhas genéricas: endereço linha um, linha dois, linha três, mais cidade, região, código postal e país. A vantagem é óbvia, porque o formulário funciona em qualquer mercado sem regra específica, e o dado é armazenado exatamente como o usuário escreveu.
O custo também é conhecido. Sem estrutura, não há como validar o que quer que seja, não há como ordenar nem filtrar por região, e a normalização posterior vira um problema separado. Relatórios por estado ou por província deixam de existir, e a impressão de etiqueta passa a depender do que o usuário digitou.
A posição mais comum em produtos maduros é um modelo híbrido. O sistema guarda as linhas genéricas como o usuário escreveu, para não perder informação nem forçar o encaixe errado, e mantém em paralelo um conjunto de campos estruturados por país, preenchidos quando o mercado tem lista fechada de divisões. Assim o endereço é exibido fielmente e continua consultável.
Vale ter clareza de que essa é uma solução de compromisso e de que ela tem custo de manutenção. Duas representações do mesmo endereço podem divergir, e alguém precisa decidir qual delas é a fonte da verdade. A decisão importa mais do que a escolha em si.
Como desenhar um modelo testável para vários países?
O primeiro passo é separar o que é comum do que é específico. Comum a todos: destinatário, país, alguma forma de localizar o imóvel. Específico de cada país: quais níveis administrativos existem, quais são obrigatórios, qual é o formato do código postal e qual é a ordem de exibição.
O segundo passo é colocar o específico em dados, não em código. Cada país tem uma definição, e o formulário se monta a partir dela. Um país novo passa a ser uma entrada na configuração, e não uma alteração em vários arquivos.
O terceiro é testar as transições. Trocar o país deve mostrar e esconder os campos certos, reavaliar obrigatoriedade e preservar o que continua válido. Apagar tudo é hostil com quem trocou por engano, e manter obrigatório um campo oculto é o pior resultado possível.
O quarto é cobrir as variações de dado. Inclua um endereço com nome de via muito longo, um com acentuação, um com caracteres não latinos, um com código postal alfanumérico e um sem código postal. O gerador de endereços desta página produz amostras nesse formato, e a lista de verificação do formulário de endereço internacional organiza os casos em uma sequência executável. Se o seu produto tem uma página por país, convém revisar também o conjunto de países disponíveis antes de fixar as regras.
Como manter o conjunto de dados atualizado?
Regra de endereço muda. País altera código postal, região é criada ou extinta, formato de identificação é reformulado. Um conjunto fixo envelhece sem avisar, e nada no repositório indica que está desatualizado.
O hábito que funciona é registrar a origem de cada regra. Cada definição de país deve apontar para a fonte que a estabelece, tipicamente a autoridade postal ou estatística daquele país, e a revisão periódica consulta essa fonte em vez de confiar na memória de quem escreveu o código. Vale também anotar a data da última revisão de cada entrada.
Convém ainda manter um teste que detecte divergência entre o conjunto de dados e o comportamento esperado, para que uma alteração acidental apareça em revisão em vez de em produção. O resumo sobre atualidade e fontes dos dados de país trata desse processo, e o panorama sobre escolher países para dados de teste ajuda a decidir a ordem em que os mercados entram.
Limites de uso
Os endereços e identificadores mencionados servem para exercitar software. Os registros produzidos por geradores são dados sintéticos: o formato é o do país escolhido, mas nenhum deles corresponde a um imóvel, a uma pessoa ou a uma conta real. Eles não devem ser usados para entrega, para cadastro em serviços, para simular verificação de identidade ou para qualquer finalidade que exija um dado verdadeiro.
O uso pretendido é verificar se o seu formulário aceita o formato de cada mercado, se a obrigatoriedade dos campos é calculada por país, se a troca de país se comporta como o esperado e se a exibição sobrevive a nomes longos e a caracteres que o seu código não previu. Comparar formatos é o começo; o que sustenta o produto é transformar a comparação em configuração e a configuração em teste.