Grupos e limites
Cada rota pertence a um grupo, e cada grupo tem sua própria cota por janela de tempo.
Como a cota é contada
Os limites são aplicados por estabelecimento (empresaId da credencial) e por ambiente. Sandbox e produção têm os mesmos limites. Ao exceder, a API responde 429 Too Many Requests com o header Retry-After, em segundos.
Grupos são independentes: esgotar um não afeta os outros. Rotas do mesmo grupo somam na mesma cota.
Pesado — 15 requisições por minuto
Consultas mais custosas: lista de pedidos e dados dos merchants.
| Página | Rota |
|---|---|
| Listar merchants | GET/v1/store/merchants |
| Detalhe do merchant | GET/v1/store/merchants/{merchantId} |
| Listar pedidos | GET/v1/orders |
Relatórios — 15 requisições por minuto
As cinco rotas de resumo dividem uma única cota.
| Página | Rota |
|---|---|
| Resumo de pedidos | GET/v1/orders/summary |
| Resumo agrupado | GET/v1/orders/summary/grouped |
| Vendas por setor | GET/v1/orders/summary/sectors |
| Vendas por produto | GET/v1/orders/summary/products |
| Vendas por opção | GET/v1/orders/summary/options |
Polling — 15 requisições a cada 5 minutos
Cota própria; o intervalo recomendado é de 30 segundos.
| Página | Rota |
|---|---|
| Polling de pedidos | GET/v1/orders/polling |
Catálogo — 100 requisições a cada 3 minutos
Cupons, avaliações, formas de pagamento e canais do restaurante.
| Página | Rota |
|---|---|
| Canal delivery | GET/v1/store/merchants/{merchantId}/delivery |
| Horários do delivery | GET/v1/store/merchants/{merchantId}/delivery/opening-hours |
| Recebimentos do delivery | GET/v1/store/merchants/{merchantId}/delivery/payment-methods |
| Pagamento online | GET/v1/store/merchants/{merchantId}/delivery/online-payments |
| Área de entrega | GET/v1/store/merchants/{merchantId}/delivery/delivery-area |
| Canal presencial | GET/v1/store/merchants/{merchantId}/local |
| Horários do presencial | GET/v1/store/merchants/{merchantId}/local/opening-hours |
| Formas de pagamento | GET/v1/store/payment-methods |
| Listar cupons | GET/v1/store/coupons |
| Detalhe do cupom | GET/v1/store/coupons/{couponId} |
| Criar cupom | POST/v1/store/coupons |
| Atualizar cupom | PATCH/v1/store/coupons/{couponId} |
| Listar avaliações | GET/v1/store/reviews |
Demais — 300 requisições a cada 3 minutos
Clientes, catálogo de produtos, detalhe e escrita de pedidos.
| Página | Rota |
|---|---|
| Detalhe do pedido | GET/v1/orders/{orderId} |
| Criar pedido | POST/v1/orders |
| Atualizar status de entrega | PATCH/v1/orders/{orderId}/delivery-status |
| Cancelar pedido | POST/v1/orders/{orderId}/cancel |
| Listar clientes | GET/v1/customers |
| Detalhe do cliente | GET/v1/customers/{customerId} |
| Listar categorias | GET/v1/stock/categories |
| Detalhe da categoria | GET/v1/stock/categories/{categoryId} |
| Criar categoria | POST/v1/stock/categories |
| Atualizar categoria | PATCH/v1/stock/categories/{categoryId} |
| Listar insumos | GET/v1/stock/supplies |
| Detalhe do insumo | GET/v1/stock/supplies/{supplyId} |
| Criar insumo | POST/v1/stock/supplies |
| Editar insumos em lote | PATCH/v1/stock/supplies |
| Listar itens | GET/v1/stock/items |
| Atualizar em lote | PATCH/v1/stock/items |
| Listar movimentações | GET/v1/stock/movements |
| Listar setores | GET/v1/catalog/sectors |
| Detalhe do setor | GET/v1/catalog/sectors/{sectorId} |
| Criar setor | POST/v1/catalog/sectors |
| Atualizar setores em lote | PATCH/v1/catalog/sectors |
| Excluir setor | DELETE/v1/catalog/sectors/{sectorId} |
| Listar produtos | GET/v1/catalog/products |
| Detalhe do produto | GET/v1/catalog/products/{productId} |
| Criar produto | POST/v1/catalog/products |
| Atualizar produtos em lote | PATCH/v1/catalog/products |
| Excluir produto | DELETE/v1/catalog/products/{productId} |
| Listar complementos | GET/v1/catalog/complements |
| Detalhe do complemento | GET/v1/catalog/complements/{complementId} |
| Criar complemento | POST/v1/catalog/complements |
| Atualizar complementos em lote | PATCH/v1/catalog/complements |
| Excluir complemento | DELETE/v1/catalog/complements/{complementId} |
| Listar grupos | GET/v1/catalog/groups |
| Detalhe do grupo | GET/v1/catalog/groups/{groupId} |
| Criar grupo | POST/v1/catalog/groups |
| Atualizar grupo | PATCH/v1/catalog/groups/{groupId} |
| Excluir grupo | DELETE/v1/catalog/groups/{groupId} |
| Vincular produtos ao grupo | POST/v1/catalog/groups/{groupId}/products |
| Desvincular produto do grupo | DELETE/v1/catalog/groups/{groupId}/products/{productId} |
| Listar opções | GET/v1/catalog/options |
| Vincular opção ao grupo | POST/v1/catalog/groups/{groupId}/options |
| Editar opções em lote | PATCH/v1/catalog/options |
| Remover opção do grupo | DELETE/v1/catalog/groups/{groupId}/options/{optionId} |
| Enviar imagem | PUT/v1/catalog/{resourceType}/{resourceId}/image |
| Remover imagem | DELETE/v1/catalog/{resourceType}/{resourceId}/image |
Observações
As rotas de OAuth (/v1/oauth/token e /v1/oauth/revoke) não entram nos limites. Prefira webhooks a consultas repetidas para reduzir o número de requisições.
No polling, a cadência mínima é de 1 chamada a cada 20 segundos, e o intervalo recomendado é de 30 segundos. Ao passar da cota, o 429 traz um Retry-After de poucos segundos, sem penalidade: respeite o header e siga.
Respostas 429 de cota não consomem a cota: só as chamadas atendidas contam na janela.
O polling tem cota de 15 por 300 s e também segue a regra de requisição idêntica de 4 segundos. Polling a cada 10 segundos esbarra nas duas; a cadência de 30 segundos respeita ambas com folga.
Um GET idêntico (mesma URL e mesmos filtros) enviado menos de quatro segundos depois de outro responde 429 na hora, com Retry-After: 4 e sem penalidade. Espere a primeira resposta em vez de reenviar.
Toda resposta 429 entra na contagem diária da credencial, qualquer que seja o grupo que a gerou. Desativação da credencial