Convenções

Estas convenções valem para todas as áreas do guia rápido da API legada. Quando uma operação foge da regra, a página dela avisa.

Requisições e respostas

Todas as rotas trocam JSON. Há três regras práticas:

• Mande Content-Type: application/json e um corpo JSON válido.
• Use UTF-8. Acentos e símbolos (ç, ã, R$) passam sem escape.
• Os métodos seguem o padrão REST: GET lê, POST cria ou executa uma ação, PUT atualiza, DELETE remove ou cancela. Esta API usa PUT para atualizar.

Cabeçalhos aceitos

Paginação

As listas devolvem uma página de cada vez. Os parâmetros são page (começa em 1) e items_per_page (padrão 10). A lista vem sob o nome do recurso (products, users, orders) e os totais em params.

{
  "products": [ { "product_id": "c3f92551-9dda-4fc7-b518-353d1c4e4035", "product": "Notebook Slim Rosa 02373" } ],
  "params": { "page": 1, "items_per_page": 10, "total_items": 4985 }
}

Para varrer tudo, incremente page até que page * items_per_page passe de total_items.

Tamanho de página fora do limite

O tamanho máximo recomendado é 100. Um valor acima do limite não é cortado em 100: a plataforma o ignora e usa o padrão da rota (10 ou 20, conforme a rota). Um items_per_page=500 não devolve 500 itens. Valores zero, negativos ou não numéricos também são ignorados. Confira o params.items_per_page da resposta para saber o que valeu.

Filtros e busca

Os filtros são parâmetros de consulta, combinados com E lógico. Cada operação lista os seus. Exemplos reais:

Valores de preço nos filtros são strings decimais ("49.90"). Um UUID malformado num filtro pode responder 500 em algumas rotas; valide antes de enviar.

Ordenação

Nas listas de produtos, sort_by escolhe o campo (product, price, list_price, timestamp, amount, position...) e sort_order a direção (asc ou desc). Um campo desconhecido cai na ordenação padrão, normalmente do mais novo para o mais antigo. As listas de pedidos vêm do mais recente ao mais antigo.

Datas e fusos

As datas são Unix timestamp em segundos, como 1791751836. Os campos usuais são timestamp e updated_timestamp. Nos filtros, time_from e time_to recebem Unix; em pedidos, só o dia conta (o horário é descartado), e period oferece atalhos como today e this_month.

Os horários são sempre UTC; converta para o fuso da loja (normalmente America/Sao_Paulo, UTC-3) para exibir.

Dinheiro

O dinheiro é uma string decimal com ponto: R$ 49,90 é "49.90". A moeda vem no campo currency (BRL).

Para somar, converter e comparar, converta a string para um tipo decimal exato (ou para centavos inteiros) no seu sistema e nunca use float. Percentuais e quantidades têm o tipo descrito na página de cada campo.

Identificadores

Os ids de uma loja não valem em outra (Endereço e ambientes). Um id malformado numa rota de consulta responde 404 ou 500, conforme a rota; valide antes de enviar.

Status em letra

Muitos recursos guardam o status como uma letra. A letra não é a inicial do nome (no pedido, O é pendente e C é entregue), e cada recurso tem o seu conjunto: categorias usam A (ativa), D (desativada), H (oculta) e T (lixeira); usuários usam A, D e P (pendente); pedidos têm um cadastro que cada loja pode alterar. A tabela dos pedidos está em Pedidos. Veja o glossário.

Erros comuns

• Tratar o preço como número: "115.00" é texto; converta para decimal exato.
• Pedir items_per_page=500 esperando 500 itens: você recebe o padrão.
• Comparar datas como texto: elas são Unix, em segundos.
• Usar order_number como chave em vez do order_id.
• Assumir a letra do status sem ler o cadastro da loja.

Veja também