Limites de uso

Os limites protegem a sua software house e os outros parceiros. Quando um deles estoura, a API responde 429 com o header Retry-After, que diz quantos segundos esperar:

HTTP/1.1 429 Too Many Requests
Retry-After: 37
Content-Type: application/json

{
  "message": "Muitas requisições. Tente novamente mais tarde.",
  "result": false,
  "data": null,
  "error": "Muitas requisições. Tente novamente mais tarde."
}

Rotas autenticadas

Valem para /v1/access-requests e para os feeds.

Limite	Valor padrão	Conta
Por software house	15 por minuto (definido no seu cadastro)	Todas as rotas e todos os clientes juntos
Por IP	60 por minuto	Todas as software houses que saem do mesmo IP (em IPv6, do mesmo bloco /64)

O limite por software house é combinado no cadastro. Com 15 por minuto e páginas de 1000 itens, dá para ler até 15 mil registros por minuto. Se precisar de mais, peça ao Concilia+.

Login (POST /oauth/token)

Limite	Valor padrão
Pedidos por IP	15 por minuto
Falhas por IP	5 falhas em 15 minutos bloqueiam o IP por 15 minutos
Tokens emitidos por software house	10 por hora
Logins simultâneos do mesmo IP	5, menos as falhas dos últimos 15 minutos (o excedente recebe 429 com Retry-After: 1)

Contam como falha: client_id inexistente ou fora do formato, client_secret errado, software house revogada ou com acesso vencido.

:::warning IP bloqueado Com o IP bloqueado, até a credencial certa recebe 429, e um login certo não limpa as falhas anteriores. Se o seu sistema errar o client_secret em loop, ele bloqueia o próprio IP. Pare de tentar ao receber 401 no login e confira a credencial. :::

Período disponível

Vendas e recebimentos ficam disponíveis por 90 dias para trás, contados pela data da venda (sale_date) ou do crédito (payment_date), no horário de Brasília. Recebimentos com crédito futuro aparecem normalmente. Uma venda mais antiga que isso não aparece, nem se for alterada (por exemplo, um chargeback). Guarde no seu sistema o que precisar manter por mais tempo.

Boas práticas

• Reutilize o token de acesso por 10 minutos, em todas as chamadas e todos os clientes. Um token por chamada estoura a cota de 10 por hora.
• Use page_size=1000 nas vendas e nos recebimentos para fazer menos chamadas.
• Respeite o Retry-After. Não repita antes do tempo indicado.
• Distribua os clientes no tempo. O limite por minuto soma todos os clientes. Com muitos clientes, sincronize em fila, não todos de uma vez.
• Em 500 ou 503, tente de novo com espera crescente (por exemplo 2 s, 4 s, 8 s...).