Dinheiro
O SDK trafega todo valor monetário em unidades menores, como inteiros: 1999 é R$ 19,99 (moeda com 2 casas). Nunca há number com casas decimais na API, então saldos e limites somam sem erro de ponto flutuante. A moeda do operador (com decimalPlaces) vem de config.get().
O que é validado na resposta
Os campos monetários que vêm do gateway (no core e nos pacotes de produto) passam por uma checagem estrita:
- o valor é um inteiro seguro (até
Number.MAX_SAFE_INTEGER), em número ou em texto; um valor de 2^53 em diante nunca chega arredondado; - a moeda é um código ISO de três letras maiúsculas (
/^[A-Z]{3}$/); decimalPlacesé um inteiro de 0 a 8.
Um campo fora disso rejeita a resposta inteira com VALIDATION_ERROR, mesmo em validation: 'warn' (o padrão): vale também para itens dentro de listas, mapas e uniões, e para o saldo que chega pelo realtime. Em 'warn' os demais campos continuam tolerantes (um enum novo vira onValidationIssue), mas dinheiro errado nunca é entregue ao app. Um gateway fora do contrato aparece como erro, não como saldo errado. Pacotes de produto reusam as mesmas checagens por money, moneyText, currencyCode e decimalPlaces de @getenginex/sdk/extension.
Nem tudo é dinheiro. Preço, quantidade e percentual não são validados como dinheiro: os preços e as quantidades do Predictions, as taxas em pontos-base (bps), pontos de fidelidade e o progresso de missões seguem a validação comum. Os agregados e limites do mercado no Predictions (volume_24h, total_volume, min_order_size, max_position) ficam fora da checagem estrita por decisão (agregados e limites do mercado, em centavos) e também seguem a validação comum.
A moeda vazia ('') é aceita só onde o gateway a omite por ser zero: nos valores de campanha de bônus, no currency do resgate de fidelidade e no settlement_currency do Predictions. Em qualquer outro campo monetário, '' rejeita a resposta. A lista config.currencies é texto livre e não passa por essa checagem.
Helpers de conversão
Três helpers convertem de e para o que o usuário vê e digita:
import { formatMoney, fromMinorUnits, toMinorUnits } from '@getenginex/sdk'
const { currency } = await enginex.config.get() // { code: 'BRL', symbol: 'R$', decimalPlaces: 2, ... }
formatMoney(123456, currency, 'pt-BR') // 'R$ 1.234,56'
toMinorUnits('1.234,56', currency) // 123456
toMinorUnits(19.99, currency) // 1999 (19.99 * 100 would give 1998.9999999999998)
fromMinorUnits(1999, currency) // 19.99formatMoney(amountMinor, currency, locale?)
Usa Intl.NumberFormat com o código ISO da moeda e as casas de decimalPlaces. Aceita negativos (extrato). Sem locale, vale o do runtime; em SSR (Next.js, Nuxt), passe o mesmo locale no servidor e no browser para não gerar diferença na hidratação.
toMinorUnits(value, currency)
Converte o texto de um campo ('12,50', '1.234,56', '1,234.56') ou um number em unidades menores. O texto é lido dígito a dígito, sem multiplicar number, e:
- com mais casas do que a moeda tem, arredonda meio para cima sobre o valor informado (
'1.0050'vira101); - com
.e,juntos, o último é o separador decimal ('1.234,56'); um único separador que aparece uma vez é o decimal ('1.5','12,50'); repetido, é separador de milhar ('1.234.567'); - um separador único seguido de exatamente 3 dígitos (
'1.000','1,000','10.500') é ambíguo e lançaRangeError, exceto em moeda de 3 casas (aí é decimal); - rejeita negativos, texto vazio ou não numérico,
NaN, infinito e valores acima do maior inteiro seguro, lançandoRangeError.
Valores como '1.000' são recusados
Em pt-BR 1.000 é mil e em en-US é um: converter em silêncio poderia subvalorizar em 1000 vezes. Por isso o SDK lança em vez de adivinhar. Passe um number, ou uma string sem ambiguidade: com os dois separadores ('1.000,00') ou sem milhar ('1000'). Se o app lê um campo de texto, normalize-o (ou use um input numérico) antes de chamar toMinorUnits.
Um number nunca é ambíguo, mas só carrega o que o JavaScript consegue representar.
fromMinorUnits(amountMinor, currency)
Devolve a unidade principal como number (1999 vira 19.99), útil para preencher um campo de edição. Para mostrar dinheiro ao usuário, use formatMoney. Como é um number, acima de ~15 dígitos significativos as casas decimais deixam de ser representáveis.
Todos os três lançam RangeError com entrada fora do contrato (valor não inteiro em unidades menores ou decimalPlaces inválido).