API e automatização
Diferenças decimais em uma API: como investigá-las sem alterar o contrato
Um exemplo de acompanhamento de um valor e dois casos documentados ajudam a localizar diferenças de precisão sem presumir uma causa nem alterar o contrato.
O que mostram os casos documentados
Uma diferença visível em um valor decimal não basta para concluir que o JSON a causou nem para saber em que ponto ela surgiu. As fontes disponíveis descrevem duas situações específicas: são referências úteis para orientar uma investigação, mas não estabelecem uma regra geral para todas as APIs.
A Esri registrou uma discrepância de precisão após o separador decimal entre resultados de uma consulta à ArcGIS REST API apresentados nos formatos HTML e JSON. O escopo está descrito no registro da Esri, [BUG-000117969](https://support.esri.com/es-es/bug/the-query-results-in-the-rest-api-in-html-and-json-form-bug-000117969). O registro permite afirmar que essa diferença foi observada naquele caso, mas não determinar aqui sua causa nem extrapolá-la para outros serviços.
A IBM documenta como evitar erros de aritmética decimal no Db2 for z/OS. O trecho disponível menciona a possibilidade de um erro de divisão em instruções SQL estáticas e a regra DEC31. Consulte o [artigo da IBM sobre erros de aritmética decimal](https://www.ibm.com/docs/es/db2-for-zos/13.0.0?topic=statement-avoiding-decimal-arithmetic-errors) para verificar o contexto. Não se trata de uma explicação geral sobre a representação de decimais em JSON.
Portanto, ao investigar, separe três coisas: a diferença observada, o ponto do percurso em que você a detecta e a explicação que ainda precisa verificar. Essa distinção evita transformar um sintoma específico em uma conclusão sobre todo o sistema.
- A Esri documenta uma discrepância entre dois formatos de resposta em um caso específico.
- A IBM aborda um problema específico de aritmética decimal no Db2 for z/OS.
- Nenhum desses antecedentes define um formato numérico universal para outras APIs.
Exemplo: acompanhe o mesmo campo do início ao fim
O exemplo a seguir é um modelo de diagnóstico, não um resultado publicado nem uma recomendação de formato. Suponha que você esteja testando um campo cujo identificador literal é `valor_decimal` e registre como entrada `123.4500`. Durante uma execução, você observa `123.4500` na solicitação, `123.45` em um ponto do processamento e `123.45` na resposta. O exemplo mostra apenas como anotar uma diferença textual; não permite concluir se o valor interpretado mudou, se houve arredondamento ou qual componente produziu a observação.
Faça o acompanhamento usando o caso real que preocupa você. Anote o nome do campo e copie o que observa em cada limite ao qual tem acesso: o dado preparado por quem chama a API, a solicitação efetivamente enviada, o dado recebido pelo serviço, se você puder observá-lo, qualquer valor intermediário pertinente e a resposta recebida. Se só tiver acesso à solicitação e à resposta, registre esses dois extremos e deixe claro que não observou as etapas internas.
Para que o exemplo possa ser reproduzido, mantenha junto da amostra as etapas que a produzem: qual operação foi executada, com qual entrada e qual resposta foi obtida. Se comparar duas execuções, altere uma única condição relevante de cada vez e registre qual foi. Não mude simultaneamente o valor, a operação e a representação; assim, fica mais difícil saber qual diferença você está comparando.
Compare as amostras capturadas, não apenas uma tela ou um relatório que possa apresentar os dados de outra maneira. Se a diferença aparecer somente em uma visualização, anote isso e tente obter também a solicitação ou a resposta correspondente. Registre o primeiro ponto em que consegue observá-la; essa é uma constatação prática, não uma prova automática da causa interna.
- Campo: `valor_decimal`. Entrada observada: `123.4500`.
- Processamento: registre o valor observado ou indique que essa etapa não está visível.
- Saída: copie a resposta recebida e indique se a diferença já estava presente antes.
- Identifique o caso como ilustrativo se usar valores inventados para preparar um teste.
Como preparar uma verificação útil
Antes de executar o teste, defina o que você quer descobrir. Por exemplo: “Em que ponto deste percurso a diferença entre o valor que envio e o que recebo aparece pela primeira vez?”. Essa pergunta pode ser verificada com mais facilidade do que “Por que o JSON muda os decimais?”, que pressupõe uma causa ainda não demonstrada.
Use uma amostra pequena que reproduza o caso e mantenha a mesma entrada durante as comparações. Identifique o endpoint e a operação afetados e anote se a resposta foi obtida na mesma execução ou em um teste diferente. Se o problema aparecer apenas em determinada operação, registre essa condição em vez de apresentá-la como um comportamento geral.
Depois, compare cada observação com a anterior: solicitação preparada em relação à solicitação enviada; solicitação enviada em relação à resposta recebida; e, quando possível, dados de entrada e saída da etapa investigada. Se você não tiver acesso a uma etapa, não a preencha com uma suposição. Escreva “não observado” e continue com os limites que consegue verificar.
Repetir o teste seguindo as mesmas etapas pode ajudar a documentar se você volta a observar a discrepância nessas condições. Se o resultado mudar, registre isso também. Nenhum dos resultados identifica, por si só, uma causa: eles ajudam a descrever o caso e a formular a próxima verificação.
- Defina uma pergunta específica antes de executar o teste.
- Mantenha a amostra fixa e registre qualquer condição que alterar.
- Diferencie dados observados, etapas inacessíveis e hipóteses pendentes.
- Guarde etapas suficientes para que outra pessoa consiga reproduzir o caso.
Interprete os resultados sem modificar o contrato
Um teste desse tipo pode mostrar que duas observações são diferentes e delimitar onde a diferença é detectada. Por si só, ele não determina o comportamento interno que a produziu. Entre os aspectos que você pode investigar estão uma diferença na amostra enviada, em um processamento observado ou na forma como o resultado é apresentado; trate-os como possibilidades que precisam ser verificadas, não como explicações confirmadas.
Não converta o campo em uma string, não altere sua escala nem arredonde como medida preventiva sem confirmar o contrato aplicável. As evidências disponíveis não sustentam uma recomendação geral entre números, strings ou unidades menores, nem definem uma regra universal de escala ou arredondamento. Uma mudança na representação pode alterar a interpretação do campo conforme o contrato; primeiro descubra o que ele aceita e o que significa.
Se a documentação do endpoint não esclarecer a representação ou o resultado esperado, faça essa pergunta ao responsável pelo serviço e apresente o caso reproduzível. Peça uma resposta específica para o campo, a operação e o endpoint envolvidos. Uma definição concreta permite decidir o que comparar; a ausência de uma definição não autoriza inferir uma regra para outros serviços.
- Trate o primeiro ponto em que vê a diferença como um limite de observação, não como causa confirmada.
- Consulte o contrato antes de alterar o tipo, a escala ou o arredondamento.
- Apresente ao provedor a pergunta pendente de forma específica e reproduzível.
Compartilhe o caso e seus limites
Ao pedir ajuda, compartilhe uma amostra mínima que demonstre a diferença e as etapas necessárias para reproduzi-la. Informe qual valor esperava, o que observou e em quais etapas conseguiu medi-lo. Se uma etapa não estava visível, diga isso expressamente. Assim, quem analisar o caso poderá distinguir o dado de entrada, o resultado e as perguntas que ainda não têm resposta.
Antes de armazenar ou compartilhar registros ou logs, remova credenciais e dados pessoais ou sensíveis que não sejam necessários para o diagnóstico. Limite quem pode acessar as amostras e por quanto tempo elas serão mantidas, de acordo com as necessidades da investigação.
Por fim, mantenha a conclusão proporcional ao teste: você pode relatar uma diferença reproduzível em uma integração específica e descrever onde a detectou. Não generalize esse resultado para valores, operações ou serviços que não testou. Os antecedentes da Esri e do Db2 servem para consultar casos documentados, não para substituir a definição do comportamento esperado da sua API.
- Inclua a amostra mínima, as etapas e a resposta observada.
- Separe resultados reproduzíveis de hipóteses pendentes.
- Remova informações sensíveis e restrinja o acesso aos registros.
Perguntas frequentes
Uma diferença decimal na resposta prova que o JSON a causou?
Não. A Esri documenta uma discrepância de precisão entre resultados em HTML e JSON em um caso da ArcGIS REST API, mas esse antecedente não estabelece uma causa universal para outras APIs.
Devo sempre enviar os decimais como strings?
Não há evidências aqui que sustentem uma recomendação geral de formato. Confirme no contrato do endpoint qual representação é aceita e como o campo deve ser interpretado.
O que o exemplo de acompanhamento permite concluir?
Ele permite registrar observações em diferentes etapas e apontar onde você detectou uma diferença pela primeira vez. Por si só, não demonstra a causa interna.
Que informações convém enviar ao provedor?
Uma amostra mínima com dados sensíveis removidos, as etapas para reproduzi-la, a diferença observada e as etapas que você conseguiu inspecionar. Informe também qual comportamento esperado precisa ser esclarecido.
Fontes e leituras
Documentação consultada para preparar este artigo.
- Cómo evitar errores de aritmética decimal - Db2 — IBM
- BUG-000117969 for ArcGIS GIS Server — Esri Support
Explore Apification
Artigos relacionados
API e automatização
Webhooks ou polling para detectar alterações em arquivos: como escolher
Compare notificações e consultas periódicas para escolher uma estratégia de detecção de alterações adequada à latência, ao volume e à capacidade de recuperação de que você precisa.
API e automatização
Webhooks fora de ordem: como evitar que um evento antigo reverta o estado de um ficheiro
A hora de receção não prova qual alteração ocorreu primeiro. Saiba como rever o contrato do webhook e reconciliar o estado do ficheiro com critérios verificáveis.
API e automatização
Como identificar arquivos em uma API sem depender de nomes ou caminhos que podem mudar
Projete referências menos dependentes de renomeações e mudanças de local: consulte o contrato OpenAPI, mantenha correspondências e teste os casos que podem interromper a sincronização.