# Construa um app de quilometragem em 50 linhas de código

> Tutorial passo a passo usando o SDK JavaScript oficial e Express.

**Autor:** Camila Ribeiro — Editora de Operações de Campo  
**Publicado:** 2026-05-02  
**Atualizado:** 2026-05-02  
**URL:** https://quilometragem.com.br/blog/build-mileage-app-in-50-lines

**TL;DR:** Tutorial passo a passo usando o SDK JavaScript oficial e Express.

- Vamos construir um pequeno app que recebe origem, destino e país, calcula a distância via GPS, aplica a taxa oficial e devolve um recibo PDF — tudo em menos de 50 linhas de Node.js.
- Você precisa de Node.js 18+ e uma chave de API.
- Passo 1: instalar dependências.
- Em três passos você tem um microserviço de quilometragem pronto para integrar a um portal de RH, um chat-bot de despesas ou um plugin de Slack.
- Envolva a chamada com cache de 24h por par origem-destino para reduzir consumo do free tier.

## O objetivo

Vamos construir um pequeno app que recebe origem, destino e país, calcula a distância via GPS, aplica a taxa oficial e devolve um recibo PDF — tudo em menos de 50 linhas de Node.js.[^irs-2025] O ingrediente secreto é o SDK oficial `quilometragem-sdk-js`.

## Pré-requisitos

Você precisa de Node.js 18+ e uma chave de API. Pegue uma em `https://quilometragem.com/account/api` (gratuito, 1.000 requisições por janela de 30 dias).

## Passo 1: instalar dependências

```
npm init -y
npm install express quilometragem-sdk-js
```

## Passo 2: o servidor

```
import express from 'express';
import { Quilometragem } from 'quilometragem-sdk-js';
const app = express(); app.use(express.json());
const qkm = new Quilometragem({ apiKey: process.env.QKM_API_KEY });

app.post('/quote', async (req, res) => {
  const { origin, destination, country = 'us', employeeName } = req.body;
  const route = await qkm.distance({ origin, destination });
  const r = await qkm.reimbursement({ distanceKm: route.distance, country });
  const receipt = await qkm.receipt({
    employeeName, origin, destination,
    distanceKm: route.distance, ratePerKm: r.ratePerKm,
    currency: r.currency,
  });
  res.json({ distance: route.distance, amount: r.amount,
    currency: r.currency, receiptUrl: receipt.url, hash: receipt.hash });
});
app.listen(3000, () => console.log('http://localhost:3000'));
```

## Passo 3: testar

```
QKM_API_KEY=qkm_live_… node server.js
curl -X POST localhost:3000/quote -H 'Content-Type: application/json' \
  -d '{"origin":"São Paulo","destination":"Campinas","country":"br","employeeName":"Ada"}'
```

A resposta traz distância, valor de reembolso, link público do recibo e hash SHA-256. É isso. Em três passos você tem um microserviço de quilometragem pronto para integrar a um portal de RH, um chat-bot de despesas ou um plugin de Slack.

## Próximo passo: produção

Envolva a chamada com cache de 24h por par origem-destino para reduzir consumo do free tier. Adicione um middleware de autenticação para que só seu app interno chame `/quote`. E monitore os headers `X-RateLimit-Remaining` para alertar antes de bater o limite mensal.

## Fontes

- [IRS — Standard Mileage Rates for 2025](https://www.irs.gov/tax-professionals/standard-mileage-rates) — Internal Revenue Service (2026-04-28)