Limites
Rate limit
Seção intitulada “Rate limit”A API autenticada aplica um limite padrão de cerca de 300 requisições por minuto por IP (janela típica de 60 segundos). Valores podem ser ajustados no servidor via variáveis de ambiente.
Rotas públicas e de lookup usam limites mais baixos.
Quando o limite é excedido, a resposta é 429 com mensagem pedindo para aguardar.
Headers padrão
Seção intitulada “Headers padrão”O middleware de rate limit envia headers padrão (RateLimit-* / Retry-After conforme configuração do servidor). Use-os para adaptar o ritmo das chamadas.
Boas práticas
Seção intitulada “Boas práticas”- Agrupe leituras (listagens com filtros) em vez de N+1 por item
- Evite polling agressivo; prefira intervalos maiores quando possível
- Em jobs em lote, limite a concorrência (ex.: poucas requisições em paralelo)
- Cacheie dados que mudam pouco (categorias, formas de pagamento)
- Em 429, espere antes de retentar — não dispare rajadas
Escopo da integração
Seção intitulada “Escopo da integração”Fora do escopo de parceiros externos:
- Provisionamento da plataforma
- Chat de suporte Nive
- Migração de dados (
/data-migration) e assistente de implantação (/store-onboarding) — usados pela tela do ERP - Warmup interno (
POST /health/warm)
Webhooks outbound de status de nota fiscal estão disponíveis em /outbound-webhooks (nota autorizada, rejeitada, cancelada ou em contingência). Outros eventos (venda criada etc.) ainda não existem. Os demais webhooks são inbound (Mercado Pago, SuperFrete, Loja Integrada, Nuvemshop e Mercado Livre → loja).
Criação e uso de chaves de API exigem plano com entitlement apiAccess (planos Expansão e Rede na tabela pública de planos).