Convenções

Estas convenções valem para todas as áreas do guia rápido. 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. Um JSON quebrado responde 400 ({"error":"invalid request body","detail":"..."}).
• 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 e PATCH alteram, DELETE remove ou cancela.

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 per_page. A resposta traz a lista sob o nome do recurso (products, users, orders) e os totais no mesmo nível.

{
  "products": [ { "id": "c3f92551-9dda-4fc7-b518-353d1c4e4035", "name": "Notebook Slim Rosa 02373" } ],
  "total": 4985,
  "page": 1,
  "per_page": 20,
  "total_pages": 249
}

Para varrer tudo, incremente page até passar de total_pages.

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 (20). Um per_page=500 devolve 20 itens, não 500. Valores zero, negativos ou não numéricos também são ignorados. Confira o 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 e total nos filtros estão em centavos. Um UUID inválido em customer_id ou vendor_id pode responder 500 em algumas rotas; valide antes de enviar.

Ordenação

sort_by escolhe o campo e sort_dir a direção (asc ou desc). Os campos aceitos variam por recurso (pedidos aceitam created_at, total, order_number, status, customer_name e customer_email; produtos aceitam, por exemplo, price). Um campo desconhecido cai na ordenação padrão, normalmente do mais novo para o mais antigo.

Datas e fusos

As datas são strings RFC 3339 em UTC, como 2026-10-11T20:50:36.891371777Z. Os campos usuais são created_at, updated_at e expires_at. Nos filtros, date_from e date_to aceitam YYYY-MM-DD ou RFC 3339.

Datas sem hora, como 2026-10-01, valem o dia inteiro. Os horários da API são sempre UTC; o fuso padrão de um usuário novo é America/Sao_Paulo (UTC-3), então converta para exibir. Uma data inválida em um filtro pode responder 500 com a descrição do problema em detail.

Dinheiro

O dinheiro é sempre um inteiro em centavos: R$ 49,90 é 4990. A moeda vem no campo currency (BRL).

Muitos objetos trazem também o valor como texto: total (12000) e total_str ("120.00"). Para somar, converter e comparar, trabalhe sempre com os inteiros. Percentuais e quantidades fracionárias 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 costuma responder 404.

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 API devolve também o texto (status_text). A tabela dos pedidos está em Status de pedido. Veja o glossário.

Erros comuns

• Somar price como se fosse reais: 11500 é R$ 115,00.
• Pedir per_page=500 esperando 500 itens: você recebe 20.
• Comparar datas como texto sem converter o fuso: a API devolve UTC.
• Usar display_id ou order_number como chave em vez do UUID.
• Assumir a letra do status sem ler o cadastro da loja.

Veja também