Dinero
El SDK transporta todo valor monetario en unidades menores, como enteros: 1999 es R$ 19,99 (una moneda con 2 decimales). Nunca hay un number con decimales en la API, así que los saldos y límites suman sin error de punto flotante. La moneda del operador (con decimalPlaces) viene de config.get().
Qué se valida en la respuesta
Los campos monetarios que vienen del gateway (en el core y en los paquetes de producto) pasan por una verificación estricta:
- el valor es un entero seguro (hasta
Number.MAX_SAFE_INTEGER), en número o en texto; un valor de 2^53 en adelante nunca llega redondeado; - la moneda es un código ISO de tres letras mayúsculas (
/^[A-Z]{3}$/); decimalPlaceses un entero de 0 a 8.
Un campo fuera de eso rechaza la respuesta completa con VALIDATION_ERROR, incluso en validation: 'warn' (el valor por defecto): aplica también a ítems dentro de listas, mapas y uniones, y para el saldo que llega por realtime. En 'warn' los demás campos siguen siendo tolerantes (un enum nuevo pasa a ser onValidationIssue), pero el dinero erróneo nunca se entrega a la app. Un gateway fuera del contrato aparece como error, no como un saldo incorrecto. Los paquetes de producto reutilizan las mismas verificaciones mediante money, moneyText, currencyCode y decimalPlaces de @getenginex/sdk/extension.
No todo es dinero. Precio, cantidad y porcentaje no se validan como dinero: los precios y las cantidades de Predictions, las tasas en puntos básicos (bps), los puntos de fidelización y el progreso de misiones siguen la validación común. Los agregados y límites del mercado en Predictions (volume_24h, total_volume, min_order_size, max_position) quedan fuera de la verificación estricta por decisión (agregados y límites del mercado, en centavos) y también siguen la validación común.
La moneda vacía ('') se acepta solo donde el gateway la omite por ser cero: en los valores de campaña de bono, en el currency del canje de fidelización y en el settlement_currency de Predictions. En cualquier otro campo monetario, '' rechaza la respuesta. La lista config.currencies es texto libre y no pasa por esta verificación.
Helpers de conversión
Tres helpers convierten desde y hacia lo que el usuario ve y escribe:
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 con el código ISO de la moneda y los decimales de decimalPlaces. Acepta negativos (extracto). Sin locale, se usa el del runtime; en SSR (Next.js, Nuxt), pasa el mismo locale en el servidor y en el browser para no generar diferencias en la hidratación.
toMinorUnits(value, currency)
Convierte el texto de un campo ('12,50', '1.234,56', '1,234.56') o un number en unidades menores. El texto se lee dígito a dígito, sin multiplicar un number, y:
- con más decimales de los que tiene la moneda, redondea hacia arriba en la mitad sobre el valor indicado (
'1.0050'pasa a101); - con
.y,juntos, el último es el separador decimal ('1.234,56'); un único separador que aparece una vez es el decimal ('1.5','12,50'); repetido, es separador de miles ('1.234.567'); - un separador único seguido de exactamente 3 dígitos (
'1.000','1,000','10.500') es ambiguo y lanzaRangeError, excepto en monedas de 3 decimales (ahí es decimal); - rechaza negativos, texto vacío o no numérico,
NaN, infinito y valores por encima del mayor entero seguro, lanzandoRangeError.
Valores como '1.000' se rechazan
En pt-BR 1.000 es mil y en en-US es uno: convertir en silencio podría subvalorar por un factor de 1000. Por eso el SDK lanza en lugar de adivinar. Pasa un number, o una cadena sin ambigüedad: con los dos separadores ('1.000,00') o sin miles ('1000'). Si la app lee un campo de texto, normalízalo (o usa un input numérico) antes de llamar a toMinorUnits.
Un number nunca es ambiguo, pero solo carga lo que JavaScript puede representar.
fromMinorUnits(amountMinor, currency)
Devuelve la unidad principal como number (1999 pasa a 19.99), útil para rellenar un campo de edición. Para mostrar dinero al usuario, usa formatMoney. Como es un number, por encima de ~15 dígitos significativos los decimales dejan de ser representables.
Los tres lanzan RangeError con entrada fuera del contrato (un valor no entero en unidades menores o un decimalPlaces inválido).