API y automatización
Diferencias decimales en una API: cómo investigarlas sin alterar el contrato
Un ejemplo de seguimiento de un valor y dos casos documentados ayudan a localizar diferencias de precisión sin asumir una causa ni cambiar el contrato.
Qué muestran los casos documentados
Una diferencia visible en un valor decimal no basta para concluir que JSON la causó ni para saber en qué punto apareció. Las fuentes disponibles describen dos situaciones específicas: son antecedentes útiles para orientar una investigación, pero no establecen una regla general para todas las API.
Esri registró una discrepancia de precisión después del separador decimal entre resultados de una consulta de ArcGIS REST API presentados en formatos HTML y JSON. El alcance está descrito en el [registro de Esri, BUG-000117969](https://support.esri.com/es-es/bug/the-query-results-in-the-rest-api-in-html-and-json-form-bug-000117969). El registro permite afirmar que se observó esa diferencia en ese caso, no determinar aquí su causa ni extrapolarla a otros servicios.
IBM documenta cómo evitar errores de aritmética decimal en Db2 for z/OS. El fragmento disponible menciona la posibilidad de un error de división en sentencias SQL estáticas y la regla DEC31. Consulta el [artículo de IBM sobre errores de aritmética decimal](https://www.ibm.com/docs/es/db2-for-zos/13.0.0?topic=statement-avoiding-decimal-arithmetic-errors) para verificar el contexto. No es una explicación general de la representación de decimales en JSON.
Por tanto, separa tres cosas al investigar: la diferencia observada, el punto del recorrido donde la detectas y la explicación que todavía necesitas comprobar. Esa distinción evita convertir un síntoma concreto en una conclusión sobre todo el sistema.
- Esri documenta una discrepancia entre dos formatos de respuesta en un caso concreto.
- IBM trata un problema específico de aritmética decimal en Db2 for z/OS.
- Ninguno de esos antecedentes define un formato numérico universal para otras API.
Ejemplo: sigue el mismo campo de principio a fin
El siguiente ejemplo es una plantilla de diagnóstico, no un resultado publicado ni una recomendación de formato. Supón que pruebas un campo llamado `importe` y registras como entrada `123.4500`. Durante una ejecución observas `123.4500` en la solicitud, `123.45` en un punto de procesamiento y `123.45` en la respuesta. El ejemplo solo muestra cómo anotar una diferencia textual; no permite concluir si cambió el valor interpretado, si hubo redondeo o qué componente produjo la observación.
Haz el seguimiento con el caso real que te preocupa. Anota el nombre del campo y copia lo que observas en cada límite al que tengas acceso: el dato preparado por quien llama a la API, la solicitud efectivamente enviada, el dato recibido por el servicio si puedes observarlo, cualquier valor intermedio que resulte pertinente y la respuesta recibida. Si solo tienes acceso a la solicitud y a la respuesta, registra esos dos extremos y deja claro que no observaste las etapas internas.
Para que el ejemplo sea reproducible, conserva junto a la muestra los pasos que la producen: qué operación se ejecutó, con qué entrada y qué respuesta se obtuvo. Si comparas dos ejecuciones, modifica una sola condición relevante cada vez y registra cuál fue. No cambies simultáneamente el valor, la operación y la representación, porque entonces será más difícil saber qué diferencia estás comparando.
Compara las muestras capturadas, no solo una pantalla o un informe que pueda presentar los datos de otra manera. Si la diferencia aparece únicamente en una vista, anótalo como tal y trata de obtener también la solicitud o respuesta correspondiente. Registra el primer punto en que puedes observarla; ese es un hallazgo práctico, no una prueba automática de la causa interna.
- Campo: `importe`. Entrada observada: `123.4500`.
- Procesamiento: registra el valor observado, o indica que esa etapa no es visible.
- Salida: copia la respuesta recibida y señala si la diferencia ya estaba presente antes.
- Etiqueta el caso como ilustrativo si usas valores inventados para preparar una prueba.
Cómo preparar una comprobación útil
Antes de ejecutar la prueba, concreta qué quieres averiguar. Por ejemplo: «¿En qué punto de este recorrido aparece por primera vez la diferencia entre el valor que envío y el que recibo?». Es una pregunta más verificable que «¿por qué JSON cambia los decimales?», que presupone una causa todavía no demostrada.
Usa una muestra pequeña que reproduzca el caso y conserva la misma entrada durante las comparaciones. Identifica el endpoint y la operación afectados, y anota si la respuesta se obtuvo en la misma ejecución o en una prueba distinta. Si el problema solo aparece con cierta operación, registra esa condición en vez de presentarla como un comportamiento general.
Después, compara cada observación con la anterior: solicitud preparada frente a solicitud enviada; solicitud enviada frente a respuesta recibida; y, cuando sea posible, datos de entrada y salida de la etapa que se investiga. Si no tienes acceso a una etapa, no la completes con una suposición. Escribe «no observado» y continúa con los límites que sí puedes comprobar.
Una repetición con los mismos pasos puede ayudar a documentar si vuelves a observar la discrepancia bajo esas condiciones. Si el resultado cambia, consígnalo también. Ninguno de los dos resultados identifica por sí solo una causa: sirven para describir el caso y formular la siguiente comprobación.
- Define una pregunta concreta antes de ejecutar la prueba.
- Mantén fija la muestra y registra cualquier condición que cambies.
- Distingue datos observados, etapas no accesibles e hipótesis pendientes.
- Guarda los pasos suficientes para que otra persona pueda repetir el caso.
Interpreta los hallazgos sin modificar el contrato
Una prueba de este tipo puede mostrar que dos observaciones difieren y acotar dónde se detecta la diferencia. No establece por sí sola el comportamiento interno que la produjo. Entre las cosas que podrías investigar están una diferencia en la muestra enviada, en un procesamiento observado o en la forma en que se presenta el resultado; trátalas como posibilidades que requieren comprobación, no como explicaciones confirmadas.
No conviertas el campo a cadena, no cambies su escala y no redondees como arreglo preventivo sin confirmar el contrato aplicable. La evidencia disponible no respalda una recomendación general entre números, cadenas o unidades menores, ni define una regla universal de escala o redondeo. Un cambio de representación podría cambiar cómo se interpreta el campo según el contrato; primero averigua qué admite y qué significa.
Si la documentación del endpoint no aclara la representación o el resultado esperado, formula esa pregunta al responsable del servicio con el caso reproducible. Pide una respuesta específica para el campo, la operación y el endpoint implicados. Una definición concreta permite decidir qué comparar; la ausencia de una definición no autoriza a inferir una regla para otros servicios.
- Trata el primer punto donde ves la diferencia como un límite de observación, no como causa confirmada.
- Consulta el contrato antes de cambiar el tipo, la escala o el redondeo.
- Plantea al proveedor la pregunta pendiente de forma específica y reproducible.
Comparte el caso y sus límites
Al pedir ayuda, comparte una muestra mínima que demuestre la diferencia y los pasos necesarios para reproducirla. Indica qué valor esperabas, qué observaste y en qué etapas pudiste medirlo. Si una etapa no era visible, dilo expresamente. Así quien revise el caso puede distinguir el dato de entrada, el resultado y las preguntas que aún no tienen respuesta.
Antes de guardar o compartir trazas, elimina credenciales y datos personales o sensibles que no sean necesarios para el diagnóstico. Limita quién puede acceder a las muestras y durante cuánto tiempo se conservan, de acuerdo con las necesidades de la investigación.
Finalmente, mantén la conclusión en proporción a la prueba: puedes informar de una diferencia reproducible en una integración concreta y describir dónde la detectaste. No generalices ese resultado a valores, operaciones o servicios que no probaste. Los antecedentes de Esri y Db2 sirven para consultar casos documentados, no para sustituir la definición del comportamiento esperado de tu API.
- Incluye la muestra mínima, los pasos y la respuesta observada.
- Separa resultados reproducibles de hipótesis pendientes.
- Redacta información sensible y restringe el acceso a las trazas.
Preguntas frecuentes
¿Una diferencia decimal en la respuesta demuestra que JSON la causó?
No. Esri documenta una discrepancia de precisión entre resultados HTML y JSON en un caso de ArcGIS REST API, pero ese antecedente no establece una causa universal para otras API.
¿Debo enviar siempre los decimales como cadenas?
No hay evidencia aquí para recomendar un formato general. Confirma en el contrato del endpoint qué representación se admite y cómo debe interpretarse el campo.
¿Qué permite concluir el ejemplo de seguimiento?
Permite registrar observaciones en distintas etapas y señalar dónde detectaste por primera vez una diferencia. Por sí solo no demuestra la causa interna.
¿Qué información conviene enviar al proveedor?
Una muestra mínima redactada, los pasos para reproducirla, la diferencia observada y las etapas que pudiste inspeccionar. Indica también qué comportamiento esperado necesitas aclarar.
Fuentes y lecturas
Documentación consultada para elaborar este artículo.
- Cómo evitar errores de aritmética decimal - Db2 — IBM
- BUG-000117969 for ArcGIS GIS Server — Esri Support
Explora Apification
Artículos relacionados
API y automatización
Webhooks o polling para detectar cambios en archivos: cómo elegir
Compara notificaciones y consultas periódicas para elegir una estrategia de detección de cambios que se ajuste a la latencia, el volumen y la capacidad de recuperación que necesitas.
API y automatización
Webhooks fuera de orden: cómo evitar que un evento antiguo revierta el estado de un archivo
La hora de recepción no demuestra qué cambio ocurrió primero. Aprende a revisar el contrato del webhook y a reconciliar el estado del archivo con criterios verificables.
API y automatización
Cómo identificar archivos en una API sin depender de nombres o rutas que pueden cambiar
Diseña referencias menos dependientes de renombrados y movimientos: revisa el contrato OpenAPI, guarda correspondencias y prueba los casos que pueden romper la sincronización.