El importe de una multa en la API: enteros en centavos y por qué

El importe de un acta que viaja como 96540.75 depende de que ese decimal atraviese intacto la base, el serializador, el parser de cada cliente y la planilla que alguien exporta al final. Casi siempre lo logra. El costo está en las veces que no: el desvío se esconde en el último centavo y aparece al conciliar.

La alternativa es no transportar fracciones: enviar 9654075, un entero en la unidad menor, y dejar la coma para el momento de mostrar el importe del acta. La decisión es razonable, pero no se sostiene sola: un entero sin escala declarada es tan ambiguo como un decimal sin moneda.

Un entero solo no dice cuánto vale

9654075 no significa nada hasta que el contrato aclare en qué unidad está expresado. ISO 4217 ayuda a medias: identifica cada moneda con un código y su lista publicada trae, junto al código, la unidad menor que le corresponde. Que esa columna exista es la señal de que el dato no es uniforme, y ningún cliente debería tener que deducirlo.

Por eso un importe entero necesita viajar con tres datos separados:

• el valor entero, expresado en la unidad menor acordada;
• el código de moneda, ARS en nuestro caso;
• la escala, para que 9654075 se lea como 96.540,75 y no como otra cifra.

El nombre del campo hace la otra mitad del trabajo. Un monto a secas invita al error simétrico: alguien lo divide por cien suponiendo centavos cuando venían pesos. montoMenor o amountMinor cuesta menos que la corrección posterior.

Qué resuelve el entero y qué queda igual

Resuelve el residuo del transporte. RFC 8259 permite números con fracción, pero aclara que las implementaciones pueden fijar límites de rango y precisión; muchos parsers llevan esos números a coma flotante binaria, donde ciertos decimales corrientes no tienen representación exacta. Un entero no tiene fracción y atraviesa esa conversión sin deformarse. Cuál de las estrategias conviene en cada caso —entero, cadena decimal o tipo nativo— es una comparación que hicimos aparte.

No resuelve el redondeo. Toda división sigue dejando resto: prorratear un total entre varias actas, aplicar un recargo, calcular una quita. El entero no elimina esa decisión, la vuelve visible. El contrato tiene que decir en qué punto se redondea, con qué regla y adónde va el resto, en vez de que cada cliente lo pierda por su cuenta.

Tampoco resuelve la ausencia: un acta que todavía no tiene importe no vale cero, y esa distinción se define en el contrato de presencia.

El techo del entero JSON

Los enteros grandes tienen un límite. RFC 8259 observa que la interoperabilidad de los números depende de lo que acepte cada implementación, y acota el terreno seguro: con aritmética de doble precisión, los enteros comprendidos entre −9.007.199.254.740.991 y 9.007.199.254.740.991 son los que todas interpretan con el mismo valor. El importe de un acta queda lejísimos de ese techo; la deuda acumulada de una flota en una unidad muy chica, no necesariamente.

Conviene fijar un máximo explícito en el esquema y probarlo, en vez de descubrirlo cuando el total anual de multas de una flota vuelva redondeado. Si la escala elegida hace plausible el desborde, el valor se transporta como cadena de dígitos, con el criterio que aplicamos a los identificadores que no son cantidades.

Lo que el esquema puede exigir y lo que no

JSON Schema permite acotar el campo con precisión: tipo entero, un mínimo, un máximo y, cuando la unidad transportada es más fina que la que informa la jurisdicción, un múltiplo obligatorio. Un esquema así rechaza en la puerta un 96540.75 mal migrado, en vez de aceptarlo y truncarlo en silencio.

Con un matiz: en esa especificación el tipo entero corresponde a cualquier número con parte fraccionaria nula, así que 9654075.0 también valida. El esquema restringe el valor, no la forma en que se escribió, y la serialización sin coma decimal termina siendo una convención que se acuerda y se prueba.

Esa prueba conviene simétrica: un campo entero validado de un solo lado termina aceptando cadenas, nulos o decimales según qué biblioteca lo toque primero.

Migrar sin romper clientes

Convertir un campo que ya existe es la parte peligrosa. Si monto pasaba pesos y de golpe pasa centavos, todo cliente que no se enteró muestra multas cien veces mayores. Nada falla; sólo el número es falso.

La migración prudente agrega un campo nuevo con nombre y escala explícitos, mantiene el anterior durante un período anunciado y recién entonces lo deprecia. Mientras conviven, los dos deben derivar del mismo valor interno.

Qué verificar antes de cerrar el contrato

Antes de fijar el tipo, probá tres cosas. Hacé un ida y vuelta del campo en cada lenguaje que soportes y compará el resultado con el original. Armá un prorrateo entre actas con resto de división y confirmá que las partes vuelven a sumar el total. Y mandá un valor pegado al máximo declarado, a ver si el esquema o el cliente lo redondean.

Un entero en centavos no es un truco de precisión. Es la decisión de que la escala, la moneda y el redondeo sean parte del contrato y no una suposición que cada cliente resuelve como puede.

Preguntas frecuentes

¿Un entero en centavos elimina los errores de redondeo?

No. Elimina el residuo binario del transporte y del almacenamiento, pero cualquier división sigue dejando resto, sea un prorrateo, un recargo o un descuento. Lo que cambia es que el entero obliga a decidir de manera explícita dónde se redondea y qué pasa con ese resto, en vez de dejarlo librado a la biblioteca de cada cliente.

¿Se puede asumir que la unidad menor son siempre dos decimales?

No conviene. El peso argentino se maneja con dos decimales, pero la lista que publica la agencia de mantenimiento de ISO 4217 trae una columna de unidad menor junto a cada código de moneda, precisamente porque no es un valor único para todas. Si el contrato deja la escala implícita, un cliente nuevo puede leer la cifra corrida de lugar.

¿El entero puede viajar como número JSON sin riesgo?

Dentro del rango que las implementaciones aceptan, sí. RFC 8259 advierte que pueden fijar límites de rango y precisión, y señala que los enteros de hasta 9.007.199.254.740.991 en valor absoluto son los que todas interpretan con el mismo valor. Para un importe individual sobra; para un acumulado en una unidad muy chica conviene revisar el techo antes de fijar el tipo.

¿Conviene migrar de decimal a entero reusando el mismo campo?

No sin versión. Un cliente que ya lee ese campo como pesos empezaría a mostrar una cifra cien veces mayor sin que falle nada. La migración prudente agrega un campo nuevo con nombre y escala explícitos, convive con el anterior durante un período anunciado y recién después lo deprecia.

Notas relacionadas