Lendo uma resposta JSON

Uma resposta JSON pode trazer, ao mesmo tempo, uma lista vazia, um campo ausente e uma mensagem de resultado. Ler só uma dessas partes leva a conclusões sem evidência, como a de que o fornecedor falhou ou a de que um distribuidor foi desabilitado.

As peças do formato

O JSON organiza os dados com poucos elementos:

• Objeto: um conjunto de pares de nome e valor, entre chaves, como {"distribuidor": 26, "preco": 10.50}.
• Lista: uma sequência de valores, entre colchetes, como [10.50, 9.90].
• Texto: um valor entre aspas, como "OK" ou "0012".
• Número: um valor sem aspas, como 12 ou 10.50, sempre com o ponto como separador decimal.
• Valores lógicos: true e false.
• Nulo: o valor null, que informa a ausência de valor de forma explícita.

Um objeto pode conter listas, e uma lista pode conter objetos, em vários níveis. O nome de cada campo e o significado de cada valor vêm do contrato da API, e não do formato.

Valores parecidos podem ter significados diferentes. O texto "0012" preserva os zeros à esquerda, e o número 12 não. O número 50.00 e o texto "50,00" também não são equivalentes, porque o segundo é um texto que o programa precisa converter. Códigos de barras, documentos e outros códigos com zeros à esquerda costumam ir como texto, conforme o layout.

Vazio, nulo e ausente

Três situações parecem iguais numa leitura rápida e são diferentes:

• Lista vazia: [] informa que a lista não tem elementos naquela resposta.
• Valor nulo: null informa, de forma explícita, que o campo não tem valor.
• Campo ausente: o campo nem aparece no objeto.

O contrato explica o que cada situação representa, como a falta de dados, um resultado parcial ou um erro. Uma lista vazia não comprova, sozinha, que a consulta foi bem-sucedida. Antes de interpretar os itens, convém localizar o código de situação HTTP, a mensagem de resultado e os campos de erro. Uma cópia formatada, com recuos, facilita a leitura de uma resposta longa, e o original fica preservado para comparação.

A resposta da cotação

Na plataforma de cotação, a consulta das condições de um produto pelo código de barras devolve uma resposta com estes campos:

• resultado: a indicação do processamento, em que o valor "OK" confirma uma consulta processada sem erro;
• loja: o identificador da loja que fez a consulta;
• itens: a lista dos produtos encontrados, cada um com o código de barras, a descrição e a lista condicoes;
• condicoes: as ofertas do produto, cada uma com o código do distribuidor, o preço, o desconto, o prazo e o preço líquido;
• pedido_minimo: o valor mínimo de pedido de cada distribuidor;
• distribuidores: os distribuidores presentes na resposta, cada um com o código, o nome e a indicação envio_liberado.

Uma condição com "distribuidor": 26 se relaciona ao distribuidor de código 26 na lista distribuidores. Nos logs, o código liga a oferta ao distribuidor, mesmo quando o nome não aparece.

Quando o resultado confirma o processamento e o contrato define que a lista itens vazia representa a falta de ofertas, a conclusão é que nenhuma condição voltou para aquela consulta. Sem essas duas confirmações, a lista vazia não separa a falta de ofertas de uma falha.

O alcance de cada consulta

Cada consulta responde a uma pergunta. A consulta geral da loja pode listar os distribuidores cadastrados ou habilitados, e a consulta de um produto lista só as condições daquele produto. Os filtros, a paginação e a definição de habilitação de cada consulta estão no contrato.

Oito distribuidores habilitados na consulta geral e dois na lista distribuidores da consulta de um produto não mostram que os outros seis foram desabilitados. Esses distribuidores podem não ter oferta para o produto, estar fora de um filtro ou não ter respondido naquele processamento.

Um JSON válido também pode trazer só uma página, um resultado parcial ou dados que o programa que lê não espera. Quando o contrato prevê, a resposta informa o total de registros, a próxima página e os filtros aplicados. Páginas obtidas em momentos diferentes não formam, juntas, uma fotografia única dos dados, porque os registros podem mudar entre uma consulta e outra.

Os preços pedem atenção à unidade, à moeda, às casas decimais e à regra de arredondamento. O formato JSON não define essas regras comerciais, que também vêm do contrato.