Conceptos clave

Dinero e importes

Todo importe en la API es un entero en las unidades menores de la moneda. Sin decimales flotantes, sin sorpresas de redondeo.

Todo valor monetario en la Developer API es un entero en las unidades menores de la moneda: centavos en el caso de USD. No hay decimales ni importes de punto flotante en ninguna parte de la API.

450  =  $4.50      (USD, 2 minor-unit digits)

Esto es deliberado: representar el dinero con enteros evita los errores de redondeo de la aritmética de punto flotante, de modo que el total que usted lee es exactamente el total que se cobró al cliente.

En los pedidos

En el recurso de pedido, todos los importes son enteros en centavos de USD, y totals.currency indica la moneda:

"totals": {
  "currency": "USD",
  "subtotal": 525,
  "tax": 42,
  "surcharge": 0,
  "tip": 0,
  "delivery_fee": 0,
  "delivery_tip": 0,
  "total": 567
}

Los artículos del pedido siguen la misma regla: base_price (por unidad, antes de modificadores), tax y el cambio de price de cada modificador son todos centavos enteros.

En los menús

Cuando publica un menú, los precios son un objeto amount que une el entero con su moneda:

{ "amount": { "amountMinor": 450, "currency": "USD" } }

amountMinor es el entero en la unidad más pequeña de la moneda, y currency es el código ISO‑4217 en mayúsculas (USD). Para USD son centavos: envíe centavos enteros y listo.

Como referencia, los dígitos de la unidad menor varían según la moneda; el modelo está preparado para manejarlo cuando llegue el soporte multimoneda:

Moneda	Dígitos de unidad menor	`amountMinor` para 5 unidades
USD	2	`500` ($5.00)
JPY	0	`5` (¥5)
KWD	3	`5000` (KD 5.000)

Redondeo

Como todos los importes son enteros, no hay redondeo en tránsito: el número que usted lee es exacto. El redondeo solo ocurre cuando Maple deriva un importe nuevo, como un descuento porcentual o una línea de impuesto. El valor predeterminado es el redondeo bancario (redondear la mitad al par), que evita el sesgo hacia arriba de redondear siempre .5 hacia arriba.

Puede cambiarlo por moneda mediante el modo de redondeo del perfil de la moneda, pero el redondeo al par es el valor predeterminado: asúmalo cuando concilie los totales de su lado.

Formato para mostrar

Para mostrar un importe, divídalo entre 10 elevado a los dígitos de unidad menor de la moneda:

function format(amountMinor: number, currency: string, digits = 2): string {
  return new Intl.NumberFormat('en-US', { style: 'currency', currency }).format(amountMinor / 10 ** digits);
}

format(567, 'USD'); // "$5.67"

No fije la división entre 100 en el código si maneja monedas con otro exponente: obténgalo de la moneda.