Uso, limites e boas práticas

Limite de requisições

As chamadas são limitadas por loja e ambiente, e não apenas por token. Assim, tokens diferentes da mesma loja compartilham a cota. A política pode variar e não há um número fixo de requisições por minuto publicado para todos os clientes.

Quando a cota for excedida, a API responde com 429 Too Many Requests e inclui o cabeçalho Retry-After, em segundos. Aguarde pelo período indicado antes de tentar novamente; não faça novas tentativas em sequência durante esse intervalo.

Paginação

Os endpoints de listagem aceitam:

A resposta tem o formato count, page, page_size e results. count representa o total de registros que correspondem aos filtros, não somente os itens da página. Calcule o total de páginas arredondando count / page_size para cima. Se a página pedida ultrapassar esse total, results será uma lista vazia.

Exemplo:

GET /api/order/list?page=1&page_size=50

Filtros e ordenação

Os filtros variam por endpoint. Entre os disponíveis estão:

• Clientes: search, created_from e created_to. A busca considera nome, documento e telefone; a comparação por nome ignora acentos e maiúsculas/minúsculas.
• Pedidos: status, order_type, created_from e created_to.
• Pedidos de um cliente: os filtros de pedidos e o identificador customer_id.

As datas inicial e final são inclusivas. Informe data e hora no formato ISO, por exemplo 2026-01-31T18:00:00, sem sufixo de fuso; o valor é interpretado no horário local da loja.

Para aplicar mais de um status ou tipo de pedido, repita o parâmetro:

GET /api/order/list?status=pending&status=preparing&order_type=delivery&page=1&page_size=50

A ordenação é definida por endpoint e não é selecionável por parâmetro: clientes são ordenados por nome; pedidos, do mais recente para o mais antigo. Os parâmetros aceitos por cada rota e os valores permitidos para status e order_type estão na Referência da API.

Tempo limite e repetição de chamadas

A API não publica um tempo máximo de resposta. Configure um tempo limite no cliente HTTP de acordo com os requisitos da sua integração e trate falhas de rede sem bloquear indefinidamente o processamento.

Os endpoints de consulta usam GET, não criam nem alteram dados e podem ser repetidos após falhas transitórias. Faça um número limitado de novas tentativas com espera progressiva para respostas 5xx e problemas de conexão, respeitando o Retry-After nas respostas 429. Evite repetir continuamente respostas 4xx: corrija os parâmetros ou a autenticação antes de tentar novamente.

O endpoint POST /api/auth/token/ emite uma nova sessão a cada chamada. Se não receber a resposta, uma nova chamada pode emitir outro token; não existe um cabeçalho Idempotency-Key documentado. As consultas não duplicam operações de negócio porque não alteram pedidos, clientes ou lojas, embora cada tentativa ainda conte para o limite de requisições.

Outros comportamentos

• Os erros usam JSON com detail e code; 422 indica parâmetros inválidos, 401 indica autenticação inválida ou expirada, e 503 indica indisponibilidade do ambiente de dados.
• Valores monetários são decimais em BRL com duas casas.
• Datas e horários de resposta são horários locais sem fuso. Use timezone_offset em /api/store/info/ para interpretá-los.