Esta versão (v0.7) ainda não foi publicada no npm.
Pular para o conteúdo

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:

ts
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.99

formatMoney(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' vira 101);
  • 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ça RangeError, 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çando RangeError.

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).