Validador de Código ISO 4217 (Moeda)

ISO 4217: o padrao internacional de codigos de moeda

A ISO 4217 e o padrao internacional que atribui codigos de tres letras e tres digitos a cada moeda reconhecida por bancos centrais, incluindo metais preciosos, moedas supranacionais e unidades historicas. 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 uniao 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 codigo alfabetico de tres 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 codigo numerico de tres digitos (986 BRL, 840 USD, 978 EUR, 392 JPY), usado em EDI, mensagens SWIFT e sistemas bancarios que preferem identificadores numericos.

A unidade menor: casas decimais variam por moeda

Um detalhe critico publicado pela ISO 4217 e o numero 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) nao 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 expoem helpers de minor unit por moeda — use. Em Java, java.util.Currency.getDefaultFractionDigits() devolve o valor certo.

Codigos historicos e descontinuados

A ISO 4217 mantem lista ativa e lista historica. Codigos que voce ainda ve em sistemas legados:

• DEM marco alemao — substituido pelo EUR em 2002.
• FRF franco frances — substituido 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 apos hiperinflacao.

Criptomoedas e o prefixo X-

A ISO 4217 reserva codigos iniciados em X para unidades supranacionais e nao-paises: XAU (ouro), XAG (prata), XPT (platina), XDR (direitos especiais de saque do FMI), XOF / XAF (francos CFA). Bitcoin nao 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. estao totalmente fora da ISO 4217 — nao 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 codigo ISO, nunca o simbolo

O simbolo $ 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 codigo ISO 4217 no banco e deixe o Intl renderizar o simbolo de acordo com o locale do usuario.

Real brasileiro (BRL): historia curta

O BRL (numerico 986, "Real") foi introduzido em 1 de julho de 1994 pelo Plano Real, o plano de estabilizacao que encerrou decadas de hiperinflacao. Substituiu o CRZ (Cruzeiro) em paridade construida pela URV (Unidade Real de Valor). Predecessores incluem CRB (Cruzeiro novo), CRZ e unidades anteriores que perderam zeros sucessivos nos anos 1980. A convencao brasileira usa virgula 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.
• Especifico do Brasil: PTAX do Banco Central expoe cotacoes do BRL contra as principais moedas.

FAQ

O Bitcoin tem codigo ISO 4217?

Nao. O Bitcoin nao e reconhecido como moeda soberana pela ISO 4217. O codigo XBT foi proposto e algumas exchanges adotaram, mas nao e padronizado. A maioria dos sistemas de trading ainda usa o BTC, fora da ISO.

Quantos decimais o iene japones tem?

Zero. O JPY nao tem subunidade, entao 1 JPY e o menor valor possivel. 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 padrao.

Quando um codigo de moeda muda?

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

Posso exibir so o simbolo de cifrao?

Em contexto multimoeda, nao. $ pode significar USD, CAD, AUD, MXN e muitos outros. Armazene sempre o codigo ISO 4217 e deixe o Intl.NumberFormat renderizar o simbolo correto para o locale do usuario.