Validador de Código ISO 4217 (Moeda)

ISO 4217: o padrão internacional de códigos de moeda

A ISO 4217 e o padrão internacional que atribui códigos de três letras e três dígitos a cada moeda reconhecida por bancos centrais, incluindo metais preciosos, moedas supranacionais e unidades históricas. E mantida pela SIX Interbank Clearing em nome da ISO e atualizada sempre que um pais emite uma nova moeda, redenominar uma existente ou entrar em uma união monetaria como a zona do euro. Todo gateway de pagamento, feed de FX e ERP contabil se apoia na ISO 4217.

O formato espelha a ISO 3166-1: um código alfabetico de três letras (ex.: BRL, USD, EUR, JPY, GBP, CNY), em que as duas primeiras letras geralmente coincidem com a alpha-2 ISO 3166-1 do pais, mais um código numérico de três dígitos (986 BRL, 840 USD, 978 EUR, 392 JPY), usado em EDI, mensagens SWIFT e sistemas bancarios que preferem identificadores numéricos.

A unidade menor: casas decimais variam por moeda

Um detalhe crítico publicado pela ISO 4217 e o número de casas decimais (minor units) de cada moeda:

• 2 decimais (o normal): USD, EUR, BRL, GBP, CAD. 1,00 BRL = 100 centavos.
• 0 decimais: JPY (iene japones) não tem subunidade. 1 JPY = menor valor. KRW, CLP e VND seguem a mesma regra.
• 3 decimais: BHD (dinar bareinita, 1000 fils), KWD (dinar kuwaitiano), OMR (rial omanense), TND (dinar tunisiano). 1 BHD = 1000 fils.
• 4 decimais (raro): CLF (Unidad de Fomento, unidade indexada chilena).

Cravar "100 centavos" em todo lugar e o bug mais comum em cobranca internacional. Stripe, Adyen e Mercado Pago expõem helpers de minor unit por moeda — use. Em Java, java.util.Currency.getDefaultFractionDigits() devolve o valor certo.

Códigos históricos e descontinuados

A ISO 4217 mantém lista ativa e lista histórica. Códigos que você ainda ve em sistemas legados:

• DEM marco alemão — substituído pelo EUR em 2002.
• FRF franco frances — substituído pelo EUR em 2002.
• ITL lira italiana — substituida pelo EUR em 2002.
• SUR rublo sovietico — extinto com a URSS em 1991.
• TRL lira turca antiga — substituida por TRY em 2005 (seis zeros cortados).
• CRZ cruzeiro brasileiro — sucedido pelo BRL em 1994 (Plano Real).
• ZWD, ZWN, ZWR, ZWL — dolares zimbabuanos sucessivos, cada um uma redenominacao após hiperinflacao.

Criptomoedas e o prefixo X-

A ISO 4217 reserva códigos iniciados em X para unidades supranacionais e não-paises: XAU (ouro), XAG (prata), XPT (platina), XDR (direitos especiais de saque do FMI), XOF / XAF (francos CFA). Bitcoin não consta em ISO 4217. Uma proposta informal de XBT circulou e Kraken, Bitstamp e alguns feeds Bloomberg adotaram, mas BTC segue como ticker de mercado. Ethereum, USDT, USDC etc. estão totalmente fora da ISO 4217 — não assuma que uma biblioteca de FX vai reconhece-los.

Formatando moeda com Intl.NumberFormat

Navegadores modernos e o Node embutem a API ECMAScript Intl que ja entende ISO 4217:

new Intl.NumberFormat('pt-BR', { style: 'currency', currency: 'BRL' })
  .format(1234.56) // "R$ 1.234,56"
new Intl.NumberFormat('en-US', { style: 'currency', currency: 'USD' })
  .format(1234.56) // "$1,234.56"
new Intl.NumberFormat('ja-JP', { style: 'currency', currency: 'JPY' })
  .format(1234.56) // "¥1,235" (sem decimais)
new Intl.NumberFormat('ar-BH', { style: 'currency', currency: 'BHD' })
  .format(1234.567) // "BHD 1,234.567" (3 decimais)

Por que armazenar sempre o código ISO, nunca o símbolo

O símbolo $ e ambiguo: pode ser USD, CAD, AUD, NZD, SGD, HKD, MXN, ARS e dezenas de outros. kr serve para SEK, NOK, DKK e ISK. £ cobre GBP, EGP, SYP e outros. Persista sempre o código ISO 4217 no banco e deixe o Intl renderizar o símbolo de acordo com o locale do usuário.

Real brasileiro (BRL): história curta

O BRL (numérico 986, "Real") foi introduzido em 1 de julho de 1994 pelo Plano Real, o plano de estabilizacao que encerrou décadas de hiperinflacao. Substituiu o CRZ (Cruzeiro) em paridade construída pela URV (Unidade Real de Valor). Predecessores incluem CRB (Cruzeiro novo), CRZ e unidades anteriores que perderam zeros sucessivos nos anos 1980. A convenção brasileira usa vírgula como decimal e ponto como milhar: R$ 1.234,56.

Bibliotecas e provedores de cotacao

• JavaScript: currency-codes, iso-4217, dinero.js.
• Python: pycountry, money, iso4217.
• Java: java.util.Currency.
• Dados FX: Open Exchange Rates, Fixer.io, currencylayer, ExchangeRate-API — todos chaveados em ISO 4217.
• Específico do Brasil: PTAX do Banco Central expõe cotacoes do BRL contra as principais moedas.

FAQ

O Bitcoin tem código ISO 4217?

Não. O Bitcoin não e reconhecido como moeda soberana pela ISO 4217. O código XBT foi proposto e algumas exchanges adotaram, mas não e padronizado. A maioria dos sistemas de trading ainda usa o BTC, fora da ISO.

Quantos decimais o iene japones tem?

Zero. O JPY não tem subunidade, então 1 JPY e o menor valor possível. Armazenar valores em iene com decimais e bug frequente em sistemas multimoeda. Won coreano (KRW), dong vietnamita (VND) e peso chileno (CLP) seguem o mesmo padrão.

Quando um código de moeda muda?

Mais comumente em redenominacoes por hiperinflacao (lira turca TRL -> TRY, cruzeiro CRZ -> BRL, ciclos zimbabuanos), unioes monetarias (doze códigos da zona do euro foram aposentados em 2002) ou mudanças politicas (a dissolucao da URSS extinguiu o SUR).

Posso exibir so o símbolo de cifrao?

Em contexto multimoeda, não. $ pode significar USD, CAD, AUD, MXN e muitos outros. Armazene sempre o código ISO 4217 e deixe o Intl.NumberFormat renderizar o símbolo correto para o locale do usuário.