Design de uma API pública: as decisões por trás do nosso lançamento
Por que escolhemos REST em vez de GraphQL, header em vez de query string, e quotas rolling em vez de calendário.
A audiência define o estilo
Nossa API é consumida por desenvolvedores de RH e fintech que normalmente integram cinco ou seis APIs por projeto.[^irs-2025] Eles não querem aprender uma nova linguagem de query nem montar resolvers — querem cURL, fetch, requests. Por isso fomos com REST clássico: cinco endpoints, JSON simples, OpenAPI 3.1. Para o caso de uso (calcular distância e reembolso), GraphQL não acrescenta nada. Ele só adicionaria um cliente extra e uma curva de aprendizado.
Autenticação no header, não na URL
Api keys passadas em query string aparecem em logs de servidor, em referers de browser e em capturas de tela. Movê-las para `X-API-Key` (com fallback para `Authorization: Bearer …`) elimina a maior parte desse vazamento sem complicar a vida do desenvolvedor — todo cliente HTTP suporta headers de primeira classe.
Quotas rolling de 30 dias, não calendário
Escolhemos rolling 30 dias em vez de "mês civil" porque calendário cria picos artificiais no início do mês. Com janela rolling, o limite se distribui naturalmente. A janela é renovada quando a primeira requisição mais antiga sai dos últimos 30 dias — implementação simples no banco com um `usage_window_start` e contador.
Free tier suficiente para validar valor
1.000 requisições por janela cobre confortavelmente um protótipo, um hackathon ou uma equipe de 10 pessoas testando uma integração. Acima disso esperamos conversa humana — quem está consumindo 5.000 req/mês geralmente já tem requisitos de SLA, IP allowlist ou rotação de chaves que merecem um plano partner customizado.
Hash de integridade no recibo
O endpoint `POST /receipt` retorna um SHA-256 dos campos de entrada. Auditores podem recalcular o hash localmente e comparar — qualquer alteração no PDF é detectada instantaneamente. É a mesma técnica que bancos usam para extratos imutáveis.
OpenAPI antes do código
Desenhamos a OpenAPI primeiro, geramos os types do TypeScript a partir dela, e só então escrevemos os handlers. Isso garante que a documentação nunca fica desatualizada — ela é o contrato.
O que ficou de fora (por enquanto)
Webhooks, batch endpoints e suporte a multi-stop com otimização de rota. Cada um tem demanda real, mas adiciona complexidade. Vamos lançá-los conforme parceiros pedirem — e cada release vai aparecer no [changelog público](/api/changelog) com RSS para que ninguém precise nos perguntar.