Boas práticas de integração

Cache e ETag

GETs públicos em /v1/* usam cache Redis por 300 segundos quando disponível. Respostas 200 podem incluir ETag e X-Cache: HIT ou MISS.

Envie If-None-Match com o ETag anterior. Uma resposta 304 não possui corpo e permite reutilizar seu dado local.

Limites

O limite padrão implementado para tráfego público sem chave específica é 60 requisições por minuto por IP. Chaves possuem limite próprio armazenado no cadastro. O limite de produto por plano e sua exposição em headers adicionais ainda estão a confirmar.

Ao receber 429, respeite Retry-After. Redis falha aberto para preservar leituras; por isso o rate limit não deve ser tratado como proteção contra abuso suficiente por si só.

CORS

CORS é relevante apenas para chamadas no navegador. A API aceita origens exatas configuradas em API_CORS_ORIGINS, métodos GET e OPTIONS e os headers X-API-Key, Content-Type e If-None-Match. Backends não dependem de CORS.

Não exponha uma API key em frontend. O playground é a exceção controlada para teste manual e limpa sua credencial ao sair.

Versionamento

O contrato público atual usa /v1. Alterações incompatíveis devem criar uma nova versão ou passar por aviso e janela de depreciação. A duração dessa janela ainda está a confirmar. URLs de documentação antigas devem permanecer acessíveis durante a transição.

Idempotência e webhooks

Os endpoints públicos são somente leitura (GET), portanto não usam chaves de idempotência. Webhooks não estão implementados. Rotas administrativas de escrita são internas e não aparecem nesta documentação.

Resiliência

• configure timeout de conexão e resposta;
• retente apenas falhas transitórias com backoff e jitter;
• registre status, rota, duração e identificador interno — nunca a API key;
• monitore taxa de 401, 429 e 503;
• valide campos opcionais e preserve números/valores decimais como strings;
• trate cada fonte de forma independente.