Uso e Rate Limits

A API do PlacaFlow tem limites para garantir estabilidade e performance para todos os usuários.

Base URL

https://api.placaflow.com.br

Em desenvolvimento:

http://localhost:3000

Headers obrigatórios

Toda requisição deve incluir:

Authorization: Bearer <api_key>

Para endpoints que enviam JSON:

Content-Type: application/json

Para reconhecimento por foto:

Content-Type: application/octet-stream

Rate Limits

Quando o limite é excedido, a API retorna:

HTTP 429 Too Many Requests

{
  "error": "Limite de requisições atingido. Aguarde um momento."
}

Créditos

O endpoint POST /api/recognize consome 1 crédito por chamada bem-sucedida. Se o saldo for zero:

HTTP 402 Payment Required

{
  "error": "Créditos insuficientes. Adquira mais créditos para continuar."
}

Consulte o saldo a qualquer momento com GET /api/credits.

Boas práticas

Caching

• Armazene resultados de reconhecimento localmente para evitar consultas repetidas
• Use GET /api/recognitions/:id apenas quando precisar das URLs presignadas (válidas por 1h)

Paginação eficiente

• Use limit adequado ao seu caso (não peça 200 se precisa de 10)
• Combine filtros (plate, cameraId, from, to) para reduzir o volume

Tratamento de erros

• Sempre verifique o status HTTP antes de processar a resposta
• Implemente retry com backoff exponencial para erros 5xx
• Não faça retry em erros 4xx (são erros do cliente)

Webhooks vs polling

• Prefira webhooks para receber eventos em tempo real
• Evite polling frequente em GET /api/recognitions — use webhooks para recognition.created