Códigos de país e de moeda em dados: ISO 3166-1 e ISO 4217 sem surpresas

O que é

A ISO 3166-1 atribui a cada país ou território um código de duas letras (CH), um de três letras (CHE) e um número de três dígitos (756). A lista M49 da ONU (citada) publica códigos numéricos de área junto com os códigos ISO alpha-3, e o BCP 47 (RFC 5646, citado) usa os códigos alpha-2 e os dígitos M49 como subtags de região. A RFC 5646 também registra duas armadilhas: a ISO 3166-1 tem códigos "exceptionally reserved" (reservados em caráter excepcional), dos quais UK é apenas um sinônimo do código atribuído GB, e AA, QM a QZ, XA a XZ e ZZ são reservados para uso privado. A ISO 4217 atribui a cada moeda um código de três letras, um código numérico e um expoente da unidade menor (minor unit). A lista atual é publicada em XML pela agência de manutenção SIX (citada): CHF e EUR têm 2 casas na unidade menor, JPY 0, BHD 3, CLF 4; metais preciosos, o código de teste XTS e XXX ("no currency", ou seja, sem moeda) não têm nenhuma; e o arquivo traz uma data de publicação, porque as entradas mudam.

Por que importa

Os códigos parecem estáveis e autoexplicativos, então acabam fixados no código (hard-coded). Mas moedas são redenominadas e substituídas, territórios mudam de status, e um código que presume duas casas decimais arredonda errado valores em iene e dinar. Além disso, o código de país não diz nada confiável sobre o idioma, o fuso horário ou a moeda de uma pessoa ou conta; esses são atributos separados.

Como aplicar

• Armazene o código de país alpha-2 e o código de moeda alpha-3 como texto em maiúsculas, com uma check constraint ou uma chave estrangeira para uma tabela de códigos; não armazene nomes de exibição, traduza-os apenas na camada de apresentação.
• Mantenha as tabelas de códigos como dados, com as colunas valid_from e valid_to e uma versão da fonte, e reimporte periodicamente a partir da lista da agência de manutenção.
• Armazene o expoente da unidade menor junto com cada moeda e use-o para arredondar e para converter entre valores decimais e inteiros em unidade menor; leia-o da lista e nunca presuma 2.
• Use códigos numéricos apenas quando um parceiro exigir; muitas moedas nacionais compartilham o código numérico do seu país (CHF e a Suíça são ambos 756), o que é conveniente em joins, mas ilegível em logs.
• Trate XXX (nenhuma moeda envolvida) e XTS (teste) como estados explícitos na lógica de negócio, não como erros de validação.

Armadilhas

UK não é um código de país atribuído e falhará numa consulta estrita. Códigos em minúsculas ou com capitalização mista quebram joins de igualdade e unique constraints. Códigos de país e códigos de idioma da ISO 639 coincidem na grafia (de é alemão e, em maiúsculas, Alemanha; be é bielorrusso e Bélgica), mas ficam em colunas diferentes. Uma lista de moedas não é a lista do que um provedor de pagamentos aceita; mantenha isso como configuração separada.

Chaves estrangeiras e códigos descontinuados

A tabela para a qual uma chave estrangeira aponta e a tabela que valida novas entradas não têm o mesmo formato. Mantenha uma linha para cada código que já existiu, com status (current, withdrawn), valid_from, valid_to e a versão da fonte; a chave estrangeira das linhas de dados referencia apenas code, de modo que registros históricos em NLG ou AN continuem carregáveis após cada reimportação. Valide novas entradas com uma check constraint ou uma regra da aplicação que admita apenas códigos cujo status seja current na data da transação, e não por meio da chave estrangeira. Assim, as reimportações adicionam e encerram linhas, mas nunca as excluem, e um relatório sobre dados antigos ainda consegue traduzir todos os códigos que encontrar.