Limites e códigos HTTP
Os códigos que a API devolve
Só estes cinco. Todos, menos o 200 do download de imagem, vêm com o envelope Resultado em JSON.
| Código | Quando | O que fazer |
|---|---|---|
200 | Atendido. Inclui sucesso com aviso, como o reenvio de um pedido já recebido: sucesso: true e a lista mensagens preenchida. | Ler dados. Se mensagens vier preenchida, registrar o aviso. |
400 | Requisição inválida: corpo que não é JSON, campo com tipo errado, parâmetro fora do aceito, campo obrigatório ausente, totais que não fecham, código que não existe no ERP. A causa vem em mensagens, uma linha por problema. | Corrigir e reenviar. Reenviar igual dá o mesmo 400. |
401 | Credencial ausente, inválida, inativa, expirada ou fora do IP permitido. Sempre a mesma mensagem. | Conferir os dois cabeçalhos e a credencial no ERP. Não repetir em laço. |
429 | Cota da credencial esgotada em uma das janelas. | Esperar o que o cabeçalho Retry-After diz, em segundos, e repetir. |
500 | Falha interna. O detalhe fica no log da API. | Repetir depois de alguns segundos. Se persistir, informar data, hora e endpoint ao suporte. |
Não existe 404: consulta que não encontra nada devolve 200 com a página vazia, e pedido inexistente
na listagem devolve 200 com itens: [].
Cota de requisições
A cota é por credencial, não por IP: várias lojas atrás do mesmo endereço não dividem a cota entre si. São duas janelas fixas, e a requisição precisa caber nas duas:
| Janela | Limite |
|---|---|
| Por minuto | 100 requisições |
| Por hora | 10.000 requisições |
Excedida qualquer uma, a resposta é:
HTTP/1.1 429 Too Many Requests
Retry-After: 37
Content-Type: application/json
{ "sucesso": false, "mensagens": ["Limite de requisições excedido para esta integração."] }
Requisição recusada por cota não conta como atendida e não aparece no monitoramento da filial.
Uma página de 200 itens custa uma requisição, igual a uma página de 10. Use o maior tamanhoPagina
que o endpoint aceitar. Para o catálogo, use alteradoApartirDe em /produtos em vez de reler a base
inteira; veja Sincronizar o catálogo.
Tamanho de página
| Endpoints | Máximo por página |
|---|---|
/clientes, /estoque, /pedidos, /produtos | 100 |
| Todos os demais | 200 |
Os quatro primeiros devolvem coleções aninhadas em cada item, como endereços, cores ou itens do pedido,
e por isso têm teto menor. Pedir mais do que o máximo não é erro: a API reduz ao máximo e informa o
valor usado em tamanhoPagina na resposta.
Tamanho do corpo e tempo
- O corpo de um pedido não tem limite próprio além do do servidor web. Um pedido com centenas de itens é aceito; o que muda é o tempo de gravação.
- Não há tempo limite específico por requisição além do padrão do servidor. Se o seu cliente HTTP
encerrar a chamada de pedido por tempo, reenvie com a mesma
chavePedidoEcommerce: a resposta será o protocolo do pedido já gravado, sem duplicar. Veja Enviar um pedido.
Versionamento
A versão vai na URL: /api/v1/.... Chamada sem versão não é atendida. As versões suportadas são
anunciadas no cabeçalho api-supported-versions das respostas que chegam a um endpoint; 401 e 429
são decididos antes e não o trazem.
Uma versão nova só nasce por mudança incompatível. Campo novo em resposta, endpoint novo e filtro novo entram na v1 sem mudar a versão: trate campos desconhecidos como ignoráveis.