Da primeira chamada
à sua próxima rota.

Uma API. Dois jeitos de informar a rota.

Envie cidades no formato Cidade/UF ou pares de latitude e longitude. A API calcula o trajeto e retorna as praças de pedágio, os custos por categoria de veículo e a geometria da rota.

1. Autenticação

Depois de criar sua conta e ativar o plano, acesse Chave de API no painel. Envie a chave no cabeçalho de todas as chamadas:

Authorization: Bearer SUA_API_KEY
Content-Type: application/json

Também é aceito o cabeçalho api_key: SUA_API_KEY. Se os dois forem enviados, api_key tem prioridade.

2. Faça sua primeira requisição

Substitua SUA_API_KEY pela sua chave. O exemplo consulta São Paulo → Campinas. Node.js usa fetch nativo; Python requer requests; C++ requer libcurl.

const resposta = await fetch(
  "https://calcularpedagio.com.br/api/pontos/v3",
  {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      Authorization: "Bearer SUA_API_KEY"
    },
    body: JSON.stringify({
      pontos: ["São Paulo/SP", "Campinas/SP"]
    })
  }
);
const dados = await resposta.json();
if (!resposta.ok) throw new Error(dados.error);
console.log(dados);

import requests

resposta = requests.post(
    "https://calcularpedagio.com.br/api/pontos/v3",
    headers={"Authorization": "Bearer SUA_API_KEY"},
    json={"pontos": ["São Paulo/SP", "Campinas/SP"]},
    timeout=65
)
resposta.raise_for_status()
print(resposta.json())

curl --request POST \
  'https://calcularpedagio.com.br/api/pontos/v3' \
  --header 'Authorization: Bearer SUA_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{"pontos":["São Paulo/SP","Campinas/SP"]}'

// Requer libcurl. Compile com: g++ exemplo.cpp -lcurl
#include <curl/curl.h>

int main() {
  curl_global_init(CURL_GLOBAL_DEFAULT);
  CURL* curl = curl_easy_init();
  if (!curl) { curl_global_cleanup(); return 1; }
  curl_slist* headers = nullptr;
  headers = curl_slist_append(headers,
    "Authorization: Bearer SUA_API_KEY");
  headers = curl_slist_append(headers,
    "Content-Type: application/json");
  curl_easy_setopt(curl, CURLOPT_URL,
    "https://calcularpedagio.com.br/api/pontos/v3");
  curl_easy_setopt(curl, CURLOPT_HTTPHEADER, headers);
  curl_easy_setopt(curl, CURLOPT_POSTFIELDS,
    R"({"pontos":["São Paulo/SP","Campinas/SP"]})");
  curl_easy_setopt(curl, CURLOPT_TIMEOUT, 65L);
  curl_easy_setopt(curl, CURLOPT_FAILONERROR, 1L);
  CURLcode result = curl_easy_perform(curl);
  curl_slist_free_all(headers);
  curl_easy_cleanup(curl);
  curl_global_cleanup();
  return result == CURLE_OK ? 0 : 1;
}

Busca de endereços, bairros e CEP

Converte o que o usuário digita em pontos prontos para a consulta de rota: cidade, rua, número, bairro, rodovia ou CEP. Serve para montar um campo de autocompletar. Base de dados OpenStreetMap do Brasil, lista de municípios do IBGE e CEPs dos Correios, tudo hospedado por nós, sem Google. Não consome usos; limite de 120 buscas por minuto por chave.

curl "https://calcularpedagio.com.br/api/geocode/v1?q=avenida+7+de+setembro+leme&lat=-22.18&lng=-47.30" \
  -H "Authorization: Bearer SUA_API_KEY"

{
  "status": "OK",
  "consulta": "avenida 7 de setembro leme",
  "resultados": [
    {
      "label": "Avenida 7 de Setembro, Centro, Leme/SP",
      "descricao": "Rua · CEP 13610-000",
      "tipo": "street",
      "lat": -22.1809, "lng": -47.3841,
      "cidade": "Leme", "uf": "SP",
      "ponto": "Avenida 7 de Setembro, Centro, Leme/[email protected],-47.3841"
    }
  ]
}

Mostre label e descricao ao usuário e envie o campo ponto dentro de pontos nos endpoints de rota. Ele já vem no formato aceito: Cidade/UF para municípios e Rótulo@lat,lng para endereços. tipo pode ser city, street, house, district, locality, postcode ou other. Para CEP, a resposta traz a rua e o bairro já resolvidos.

API de Pedágios por Endereço

Informe de 2 a 100 pontos, na ordem do trajeto. A primeira é a origem; a última, o destino; as intermediárias são paradas. Cada ponto é um município no formato Cidade/UF ou um endereço no formato Rótulo@latitude,longitude, como devolvido pela busca de endereços. Os dois formatos podem ser misturados na mesma lista.

{
  "pontos": ["São Paulo/SP", "Jundiaí/SP", "Avenida 7 de Setembro, Centro, Leme/[email protected],-47.3841"]
}

API de Pedágios por Coordenadas

Informe de 2 a 100 pares na ordem [latitude, longitude], em graus decimais e dentro do Brasil.

{
  "pontos": [
    [-29.5008, -51.9484],
    [-29.2562, -51.5341]
  ]
}

Múltiplos trajetos

Use o mesmo corpo dos endpoints anteriores para comparar as alternativas disponíveis.

A rota mais rápida e a mais barata podem ser a mesma. Para comparar caminhões, use os totais da categoria em cada opção retornada.

Veículo, ida e volta e ordem otimizada

Os endpoints /pontos/v3, /coordenadas/v3 (e as versões v1) aceitam três campos opcionais junto com pontos. Sem eles, a resposta é a mesma de sempre.

{
  "pontos": ["São Paulo/SP", "Ribeirão Preto/SP", "Campinas/SP", "Curitiba/PR"],
  "veiculo": { "tipo": "caminhao", "eixos": 5 },
  "retorno": true,
  "otimizar": true
}

Toda resposta de rota traz também links.googleMaps (a rota nas coordenadas calculadas) e, quando os pontos foram enviados como Cidade/UF, links.calculadora com a mesma consulta aberta na calculadora do site.

Pedágios sobre uma rota calculada fora

Já tem a rota do Google Maps, HERE, Mapbox ou do seu próprio roteador? Envie só a geometria e receba as praças e os custos, sem novo roteamento. Segue as faixas por distância e pedágios e os limites por chamada descritos em Consumo e limites.

{
  "polyline": "hkzlCr}h{GfDzB~F`D...",
  "veiculo": { "tipo": "caminhao", "eixos": 5 },
  "data": "2026-09-19"
}

Resposta: dados.pedagiosRota, totais por categoria, pracasNaoCobradas, distanciaMetros (comprimento da geometria enviada) e pontos. Não há polyline nem duracaoSegundos, pois a rota é sua. Quanto mais fiel a geometria (sem simplificação agressiva), melhor o casamento com as praças.

Imagem da rota

Devolve um mapa esquemático em SVG (image/svg+xml) com os limites dos estados, a linha da rota, as praças com o valor cobrado, origem, paradas e destino, e um rodapé com distância, tempo e total de pedágios. Serve para cotações, e-mails e PDFs sem depender de serviço de mapas. Consome usos como uma consulta de rota.

{
  "pontos": ["São Paulo/SP", "Curitiba/PR"],
  "veiculo": "caminhao-5",
  "largura": 900,
  "altura": 600,
  "titulo": "Cotação 1234"
}

Tabela de frete (piso mínimo ANTT)

Calcula o piso mínimo do transporte rodoviário de cargas pela metodologia da Resolução ANTT nº 5.867/2020: piso = distância (km) × CCD + CC, com os coeficientes da tabela vigente na data informada. Informe a distância ou os pontos da rota.

curl -X POST https://calcularpedagio.com.br/api/frete/v1 \
  -H "Authorization: Bearer SUA_API_KEY" -H "Content-Type: application/json" \
  -d '{"pontos":["São Paulo/SP","Curitiba/PR"],"eixos":5,"tipoCarga":"carga_geral","tabela":"A","retornoVazio":true}'

Resposta: pisoMinimo, custoDeslocamento, custoCargaDescarga, coeficientes.ccd, coeficientes.cc, retornoVazio.valor, total e vigencia (início e resolução). Combinações cuja tabela ainda não foi carregada respondem 503 com pendente: true. GET /api/frete/catalogo lista tipos de carga, tabelas e vigências.

Frete junto com a rota

Em qualquer endpoint de rota (/pontos/*, /coordenadas/*, inclusive múltiplos trajetos), envie o objeto opcional frete e a resposta traz o campo frete com o piso calculado sobre a distância daquela rota (em múltiplos trajetos, um por rota). Não consome usos adicionais.

{
  "pontos": ["São Paulo/SP", "Curitiba/PR"],
  "frete": { "eixos": 5, "tipoCarga": "carga_geral", "tabela": "A", "retornoVazio": false }
}

Se a combinação ainda não tiver coeficiente, frete vem como { "pendente": true, "erro": "..." } e a rota é devolvida normalmente. Parâmetros inválidos em frete respondem 400.

3. Entenda a resposta

Exemplo estrutural reduzido e ilustrativo da v3. Os valores abaixo não representam uma cotação; as categorias e praças foram abreviadas para facilitar a leitura.

{
  "status": "OK",
  "dados": {
    "pais": "Brasil",
    "moeda": "BRL",
    "pedagiosRota": [],
    "custoTotalPedagiosDinheiro": { "auto2eixos": 0 },
    "custoTotalPedagiosTag": { "auto2eixos": 0 },
    "pracasNaoCobradas": []
  },
  "usuario": "null",
  "polyline": {
    "type": "LineString",
    "coordinates": [[-51.9484, -29.5008], [-51.5341, -29.2562]]
  },
  "distancia": "35KM",
  "duracaoSegundos": 2400
}

Categorias de veículos

Na v3, as chaves são moto2eixos, auto2eixos, auto3eixos, auto4eixos, valorPorEixoCaminhao, onibus2Eixos, motorHome2eixos, motorHome3eixos e motorHome4eixos. Para caminhões, multiplique valorPorEixoCaminhao pela quantidade de eixos cobrados. Observe a letra E maiúscula em onibus2Eixos.

Consumo e limites

Cada chamada de cálculo consome 1 uso. Acima de 15 pedágios ou 1.000 km: 5 usos; acima de 20 pedágios ou 1.500 km: 10 usos; acima de 40 pedágios ou 2.000 km: 50 usos. Vale somente a maior faixa atingida. Máximo de 50 pedágios e 3.000 km por chamada; acima disso, a chamada é recusada sem consumo. Ida e volta somam distância e passagens por pedágios; nas alternativas, valem os maiores valores entre as rotas.

A quantidade de pontos não altera o consumo: são aceitos de 2 a 100 pontos nos endpoints da API. A regra vale para consultas de rota, imagem, polyline e frete por rota. Busca de endereços, catálogo de frete e frete somente por distância continuam sem consumo. O limite de distância também se aplica ao frete por distância.

Confira X-Usage-Units (usos desta chamada), X-RateLimit-Limit (cota) e X-RateLimit-Remaining (saldo após a chamada). Acima de 50 pedágios ou 3.000 km: HTTP 400, sem consumo. Saldo pago insuficiente: HTTP 429; sem plano ativo e sem cortesia suficiente: HTTP 402. Falhas não descontam usos. O histórico anterior é preservado.

Erros e soluções

Verifique o status HTTP e o campo error antes de usar a resposta.

Use timeout no cliente e tentativas limitadas para falhas temporárias. Não repita indefinidamente chamadas com erro de autenticação ou cota. Se sua conexão cair após o processamento, uma nova chamada pode consumir outro uso.

Webhooks

Cadastre uma URL sua em Webhook (menu do painel) para receber, por HTTP POST, as chamadas recentes e o uso da sua conta em tempo real, um resumo diário do histórico de chamadas e um aviso quando o plano estiver vencendo. Não é preciso ficar consultando a API para saber o que aconteceu: nós avisamos sua aplicação.

Cabeçalhos da requisição

Verificando a assinatura (Node.js)

const crypto = require('crypto');

function assinaturaValida(corpoBruto, assinaturaRecebida, chaveSecreta) {
  const esperada = crypto.createHmac('sha256', chaveSecreta).update(corpoBruto).digest('hex');
  return crypto.timingSafeEqual(Buffer.from(esperada), Buffer.from(assinaturaRecebida));
}

// corpoBruto deve ser a string original do corpo (ex.: req.rawBody), não o objeto já convertido.

O webhook aceita uma URL HTTPS pública, sem credenciais na URL. Endereços internos e redirecionamentos são bloqueados. Em uso, usadoNoMes inclui usos de cortesia; usadoDoPlanoNoMes conta só usos pagos, restante informa a cota paga restante e saldoTotalRestante soma a cota paga e os usos de cortesia.

Eventos

{
  "evento": "chamada.criada",
  "enviadoEm": "2026-09-13T14:32:10.000Z",
  "dados": {
    "endpoint": "/pontos/v3",
    "source": "api",
    "statusCode": 200,
    "durationMs": 480,
    "units": 1,
    "pontos": 3,
    "resumo": "São Paulo/SP → Campinas/SP",
    "uso": {
      "plano": "Plano 3.000",
      "limiteMensal": 3000,
      "usadoNoMes": 812,
      "usadoDoPlanoNoMes": 812,
      "restante": 2188,
      "saldoTotalRestante": 2188,
      "creditosGratuitosRestantes": 0
    }
  }
}

{
  "evento": "historico.diario",
  "enviadoEm": "2026-09-13T06:00:04.000Z",
  "dados": { "periodo": "ultimas24h", "chamadas": 214, "erros": 3, "usosConsumidos": 198 }
}

{
  "evento": "plano.vencimento",
  "enviadoEm": "2026-09-13T06:00:04.000Z",
  "dados": { "plano": "Plano 3.000", "vencimento": "2026-09-20", "diasRestantes": 7 }
}

Marque ou desmarque cada evento na aba Webhook do painel. Gerar uma nova chave secreta invalida a assinatura calculada com a anterior.

Compatibilidade com a v1

As rotas POST /pontos/v1 e POST /coordenadas/v1 continuam disponíveis com o mesmo corpo de entrada. A v1 retorna dados.totalPedagiosRota, com chaves como auto e moto, além de distanciaMetros. Na v3, use os totais de dinheiro e TAG separados e a chave auto2eixos.

Para novas integrações, use a v3. As coordenadas individuais das praças, km e campo interno de direção são removidos das respostas públicas v3; a geometria da rota continua disponível.

Precisa de ajuda com a integração?

Envie o endpoint utilizado, um exemplo do corpo sem dados sensíveis e o erro retornado. Não compartilhe sua chave de API.

Importe os dois arquivos no Postman (Import → File), selecione o ambiente "API Pedágios · produção" e preencha a variável apiKey. A coleção traz 18 requisições prontas, incluindo a busca de endereços e os formatos Cidade/UF e Rótulo@lat,lng.