# Lançamento da API pública gratuita de quilometragem

> Cinco endpoints REST, autenticação por API key e free tier de 1.000 requisições por janela de 30 dias.

**Autor:** Camila Ribeiro — Editora de Operações de Campo  
**Publicado:** 2026-05-02  
**Atualizado:** 2026-05-02  
**URL:** https://quilometragem.com.br/blog/free-mileage-api-launch

**TL;DR:** Cinco endpoints REST, autenticação por API key e free tier de 1.000 requisições por janela de 30 dias.

- Reembolso de quilometragem é uma das peças mais ignoradas da pilha de despesas corporativas.
- O contrato é deliberadamente pequeno.
- A chave vai no header X-API-Key (ou como Bearer).
- Publicamos clientes oficiais em JavaScript/TypeScript (npm install quilometragem-sdk-js) e Python (pip install quilometragem), ambos sob licença MIT.
- Pronto para enviar ao endpoint de reembolso ou direto para a sua interface.

## Por que estamos publicando uma API pública

Reembolso de quilometragem é uma das peças mais ignoradas da pilha de despesas corporativas.[^irs-2025] Existem ERPs gigantes para folha, ferramentas dedicadas para cartão corporativo, mas para quilometragem a maioria das equipes ainda usa planilhas. A API pública do Quilometragem nasce para resolver isso: cinco endpoints REST que entregam distância via GPS, taxa oficial por país, cálculo de reembolso, recibo PDF assinado e geocodificação. Tudo gratuito até 1.000 requisições por janela de 30 dias por chave.

## Os cinco endpoints

O contrato é deliberadamente pequeno. `POST /distance` calcula a distância e a duração entre dois pontos, aceitando endereços livres ou pares lat/lng. `POST /reimbursement` aplica a taxa oficial do país e ano informados — atualmente cobrimos US, BR, MX, CO, UK e CA. `POST /receipt` gera um PDF de recibo com hash SHA-256 que sustenta auditoria. `GET /rates/{country}/{year}` devolve a taxa oficial com link para a fonte. `GET /geocode` converte um endereço em coordenadas. É o suficiente para construir uma calculadora completa, um portal de motoristas ou um conector ERP.

## Autenticação e limites

A chave vai no header `X-API-Key` (ou como Bearer). Cada resposta carrega `X-RateLimit-Limit` e `X-RateLimit-Remaining` para você monitorar consumo sem chamadas extras. O free tier de 1.000 requisições por janela de 30 dias rolling cobre tranquilamente protótipos, hackathons e times pequenos. Quando precisar de mais, há um plano partner com volumes sob medida.

## SDKs e OpenAPI

Publicamos clientes oficiais em JavaScript/TypeScript (`npm install quilometragem-sdk-js`) e Python (`pip install quilometragem`), ambos sob licença MIT. Para outras linguagens, importe nosso OpenAPI 3.1 em `https://quilometragem.com/api/openapi.json` no Postman, no Insomnia ou diretamente em um plugin do ChatGPT. Os exemplos cURL, Axios, Ruby, Go e PHP estão na documentação interativa em `/api`.

## Como começar em 60 segundos

Faça login, abra `/account/api`, crie uma chave (você verá o valor uma única vez), e teste com cURL:

```
curl -X POST https://quilometragem.com/api/v1/public/distance \
  -H 'X-API-Key: qkm_live_…' \
  -H 'Content-Type: application/json' \
  -d '{"origin":"São Paulo, BR","destination":"Rio de Janeiro, BR"}'
```

Você recebe distância em km, duração estimada e polyline da rota. Pronto para enviar ao endpoint de reembolso ou direto para a sua interface.

## Fontes

- [IRS — Standard Mileage Rates for 2025](https://www.irs.gov/tax-professionals/standard-mileage-rates) — Internal Revenue Service (2026-04-28)
- [OpenStreetMap — Map data and routing](https://www.openstreetmap.org/about) — OpenStreetMap Foundation (2026-04-28)