API de pedágio para caminhões: como calcular por eixos e integrar ao TMS, ERP ou cotador de fretes

1. O que uma API de pedágio precisa entregar em ambiente de produção

Integrar o cálculo de pedágios diretamente nos sistemas corporativos de uma transportadora, operador logístico ou embarcador — como TMS (Transportation Management System), ERP (SAP, TOTVS Protheus, Senior, Sankhya) ou cotadores web de frete — é um requisito mandatório para a saúde financeira da operação. No transporte rodoviário brasileiro, o pedágio representa frequentemente entre 6% e 14% do custo total da viagem.

Entretanto, para suportar operações reais com centenas de viagens diárias, uma API de pedágio não pode se limitar a devolver uma estimativa aproximada. Em produção, os requisitos de engenharia são rigorosos:

• Baixa Latência Determinística: Chamadas síncronas de roteirização devem responder em menos de 800 milissegundos para não travar a esteira de cotação ou a emissão de Conhecimentos de Transporte Eletrônico (CT-e) e Manifestos Eletrônicos (MDF-e).
• Detecção Fina por Geometria de Rota: A API precisa interceptar as praças físicas e os pórticos Free Flow a partir do traçado real da rota (polylines decodificadas de alta resolução), e não por mero raio circular em torno de cidades.
• Discriminação Praça a Praça: Para viabilizar a antecipação obrigatória do Vale-Pedágio (Lei Federal nº 10.209/2001) e a emissão do comprovante nas operadoras de meios de pagamento habilitadas (IPEFs), o sistema exige a lista ordenada de concessionárias, rodovias (ex: BR-116, SP-330), sentido da via e valor individual.
• Identificação Clara do Status de Cobertura: Respostas transparentes informando se as tarifas foram CONFIRMADA na base oficial homologada, se há COBERTURA_PARCIAL ou se o trecho percorrido é comprovadamente isento de cobrança (SEM_PEDAGIO). O sistema nunca deve retornar R$ 0,00 quando a base estiver aguardando homologação ou quando a concessão for estadual não mapeada.

2. Por que o número de eixos muda o cálculo e as categorias tarifárias

O erro mais recorrente em softwares logísticos que utilizam APIs de mapas voltadas ao público geral é presumir que o pedágio para caminhões é proporcional a uma taxa fixa por quilômetro ou que o multiplicador é igual à contagem bruta de eixos.

Na regulação da ANTT (Agência Nacional de Transportes Terrestres) e das agências reguladoras estaduais (como ARTESP em São Paulo, AGERGS no Rio Grande do Sul e AGEPAR no Paraná), a precificação segue o conceito de Tarifa Básica de Pedágio (TBP) multiplicada pelo fator correspondente à categoria regulatória do veículo:

A Regra do Eixo Suspenso (Lei nº 13.103/2015)

Conforme o artigo 17 da Lei Federal nº 13.103/2015 (Lei do Motorista), os veículos de transporte de carga que circularem vazios não pagam pedágio sobre os eixos que mantiverem suspensos por acionamento pneumático nas rodovias federais e estaduais com legislação convergente.

A fiscalização é efetuada por sensores de solo nas praças convencionais, pesagem em movimento (WIM - Weigh-in-Motion) ou pelo cruzamento eletrônico da placa com o MDF-e: caso não haja manifesto ativo com carga transportada, o caminhão é tarifado apenas pelos eixos em contato com o pavimento.

3. Praças convencionais com barreira versus pórticos Free Flow

A modernização das rodovias brasileiras impulsionou a convivência entre dois modelos tarifários distintos:

1. Praças Físicas Convencionais: Possuem cabines de cobrança manual e pistas automáticas com cancelas. A passagem sem pagamento é contida fisicamente pela barreira ou sinalizada imediatamente à concessionária.
2. Pórticos Free Flow (Pedágio Eletrônico Sem Parada): Regulamentados pela Lei Federal nº 14.157/2021 e pelas Resoluções ANTT nº 6.000/2022 e 6.024/2023. A cobrança ocorre a 110 km/h através de estruturas metálicas elevadas equipadas com antenas RFID (frequência de 915 MHz para leitura de TAGs padrão DSRC) e câmeras de alta resolução com OCR (Reconhecimento Óptico de Placas).

Para sistemas corporativos (TMS/ERP), o Free Flow altera profundamente as regras de auditoria e contingência. Se o caminhão passar por um pórtico automático sem uma TAG ativa ou sem saldo provisionado no Vale-Pedágio Obrigatório, a transportadora dispõe de um prazo legal estrito de 15 dias corridos para efetuar o pagamento avulso nos portais das concessionárias.

4. Contrato e payload mínimo de uma requisição de rota

A API do Geodagio adota arquitetura RESTful com payloads JSON estritamente tipados por schemas TypeBox compilados no Fastify. O endpoint principal para roteirização e cálculo de tarifas é o POST /api/v1/routes/calculate.

Para uma cotação precisa de caminhão, o payload mínimo exige a origem, o destino, a especificação da composição veicular e a data de competência:

{
  "origin": "São Paulo, SP",
  "destination": "Curitiba, PR",
  "vehicle": {
    "axleCount": 6,
    "vehicleClassCode": "2-semitrailer"
  },
  "calculationDate": "2026-10-04"
}

A estrutura de retorno entrega uma visão analítica completa da rota, incluindo o sumário financeiro e a lista discriminada de praças:

{
  "data": {
    "id": "c1f7b8e2-45a9-4d6b-9c3f-8e2b7a1d4f90",
    "route": {
      "distanceMeters": 408500,
      "durationSeconds": 19800,
      "encodedPolyline": "v~`bC..._p|"
    },
    "tolls": {
      "total": {
        "amount": 284.40,
        "currency": "BRL"
      },
      "charges": [
        {
          "tollPointId": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
          "sequence": 1,
          "name": "Praça São Bernardo do Campo (Imigrantes/Anchieta)",
          "roadCode": "SP-160",
          "isFreeFlow": false,
          "amount": {
            "amount": 47.40,
            "currency": "BRL"
          },
          "directionResolution": "RESOLVED",
          "matchConfidence": 0.98
        },
        {
          "tollPointId": "8f2a1b3c-4d5e-6f7a-8b9c-0d1e2f3a4b5c",
          "sequence": 2,
          "name": "Pórtico Free Flow Registro Sul",
          "roadCode": "BR-116",
          "isFreeFlow": true,
          "amount": {
            "amount": 23.70,
            "currency": "BRL"
          },
          "directionResolution": "RESOLVED",
          "matchConfidence": 0.99
        }
      ]
    },
    "coverage": {
      "status": "CONFIRMADA",
      "confirmedSubtotal": {
        "amount": 284.40,
        "currency": "BRL"
      }
    }
  },
  "meta": {
    "requestId": "req_8a9b1c2d3e4f",
    "apiVersion": "v1"
  }
}

5. Exemplos práticos em cURL, Node.js/TypeScript e Python

Abaixo estão implementações prontas para produção, contemplando cabeçalhos de segurança obrigatórios, chave de idempotência e tratamento resiliente de resposta.

5.1. Chamada via cURL

curl -X POST "https://api.geodagio.com/api/v1/routes/calculate" \
  -H "Authorization: Bearer sec_live_9a8b7c6d5e4f3a2b1c0d" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: cota-tms-pedido-98412" \
  -d '{
    "origin": "Santos, SP",
    "destination": "Betim, MG",
    "vehicle": {
      "axleCount": 7,
      "vehicleClassCode": "bitrem-7-eixos"
    },
    "calculationDate": "2026-10-04"
  }'

5.2. Integração em Node.js / TypeScript com Timeout e Retry

Este módulo encapsula o consumo da API com tipagem estrita, controle de cancelamento por AbortSignal e política de retries exponenciais para falhas transitórias de rede:

import { randomUUID } from 'node:crypto';

export interface RouteTollRequest {
  origin: string;
  destination: string;
  axleCount: number;
  vehicleClassCode: string;
  idempotencyKey?: string;
}

export interface RouteTollResponse {
  id: string;
  distanceKm: number;
  durationMinutes: number;
  tollTotalBrl: number;
  tollCount: number;
  freeFlowCount: number;
  coverageStatus: 'CONFIRMADA' | 'COBERTURA_PARCIAL' | 'TARIFA_NAO_CONFIRMADA' | 'COBERTURA_INDISPONIVEL' | 'SEM_PEDAGIO';
}

export class GeodagioTollClient {
  private readonly baseUrl = 'https://api.geodagio.com/api/v1';

  constructor(private readonly apiKey: string) {}

  async calculateRouteTolls(params: RouteTollRequest): Promise<RouteTollResponse> {
    const idempotencyKey = params.idempotencyKey || `tms-${randomUUID()}`;
    const payload = {
      origin: params.origin,
      destination: params.destination,
      vehicle: {
        axleCount: params.axleCount,
        vehicleClassCode: params.vehicleClassCode
      },
      calculationDate: new Date().toISOString().split('T')[0]
    };

    let attempts = 0;
    const maxAttempts = 3;

    while (attempts < maxAttempts) {
      attempts++;
      try {
        const response = await fetch(`${this.baseUrl}/routes/calculate`, {
          method: 'POST',
          headers: {
            'Authorization': `Bearer ${this.apiKey}`,
            'Content-Type': 'application/json',
            'Idempotency-Key': idempotencyKey,
            'Accept': 'application/json'
          },
          body: JSON.stringify(payload),
          signal: AbortSignal.timeout(8000) // Timeout de 8 segundos
        });

        if (response.status === 429 || response.status >= 500) {
          if (attempts >= maxAttempts) {
            throw new Error(`Falha transitória na API Geodagio: HTTP ${response.status}`);
          }
          await new Promise((res) => setTimeout(res, attempts * 1000));
          continue;
        }

        if (!response.ok) {
          const errBody = await response.json().catch(() => ({}));
          throw new Error(`Erro na API Geodagio [${errBody?.error?.code || response.status}]: ${errBody?.error?.message || 'Erro desconhecido'}`);
        }

        const json = await response.json();
        const data = json.data;
        const charges = data.tolls?.charges || [];
        const freeFlowTolls = charges.filter((c: any) => c.isFreeFlow === true);

        return {
          id: data.id,
          distanceKm: Math.round(data.route.distanceMeters / 1000),
          durationMinutes: Math.round(data.route.durationSeconds / 60),
          tollTotalBrl: data.tolls?.total?.amount ?? 0,
          tollCount: charges.length,
          freeFlowCount: freeFlowTolls.length,
          coverageStatus: data.coverage.status
        };
      } catch (error: any) {
        if (attempts >= maxAttempts) throw error;
        await new Promise((res) => setTimeout(res, attempts * 1000));
      }
    }

    throw new Error('Falha inesperada ao tentar comunicar com a API.');
  }
}

5.3. Integração em Python (para backends Django/FastAPI)

import requests
from datetime import date
from typing import Dict, Any

class GeodagioClient:
    def __init__(self, api_key: str):
        self.base_url = "https://api.geodagio.com/api/v1"
        self.session = requests.Session()
        self.session.headers.update({
            "Authorization": f"Bearer {api_key}",
            "Content-Type": "application/json",
            "Accept": "application/json"
        })

    def calculate_tolls(self, origin: str, destination: str, axle_count: int, idempotency_key: str) -> Dict[str, Any]:
        url = f"{self.base_url}/routes/calculate"
        payload = {
            "origin": origin,
            "destination": destination,
            "vehicle": {
                "axleCount": axle_count,
                "vehicleClassCode": f"truck-{axle_count}-axles"
            },
            "calculationDate": date.today().isoformat()
        }
        headers = {"Idempotency-Key": idempotency_key}

        response = self.session.post(url, json=payload, headers=headers, timeout=10)
        response.raise_for_status()
        res_json = response.json()
        data = res_json["data"]

        return {
            "calculation_id": data["id"],
            "distance_km": round(data["route"]["distanceMeters"] / 1000, 2),
            "toll_total_brl": data.get("tolls", {}).get("total", {}).get("amount", 0.0),
            "charges_count": len(data.get("tolls", {}).get("charges", [])),
            "coverage_status": data["coverage"]["status"]
        }

Vídeo Oficial: Como Integrar APIs Logísticas com Idempotência e Retries

Assista ao guia técnico em vídeo do canal oficial Geodagio no YouTube demonstrando como orquestrar chamadas de rotas e pedágios em sistemas TMS, prevenir falhas de rede com retries exponenciais e assegurar zero passivo financeiro na esteira de expedição:

6. Idempotência, rate limits, timeouts e tratamento de erros (RFC 7807)

Em sistemas distribuídos de transporte, rotinas de precificação em lote e cotadores em tempo real estão sujeitos a quedas intermitentes de conexão e timeouts em gateways reversos. Para evitar problemas graves, quatro pilares arquiteturais devem ser respeitados:

6.1. O Cabeçalho Idempotency-Key

Quando seu TMS envia uma solicitação de cálculo e a resposta é interrompida por um corte de socket TCP, o TMS não sabe se a requisição foi gravada ou não. Se o sistema reenviar a solicitação cegamente, poderá duplicar a cobrança de créditos ou gerar registros concorrentes de rotas.

Ao enviar o cabeçalho Idempotency-Key: <chave-unica> (como o ID do pedido no TMS ou o hash dos parâmetros), a API do Geodagio garante:

• Primeira Requisição: Executa a roteirização completa no grafo viário, consulta as bases de pedágio e devolve HTTP 201 Created.
• Retries com a Mesma Chave: Reconhece a chave previamente processada no repositório de idempotência e devolve HTTP 200 OK com o resultado exato armazenado em cache determinístico, com zero consumo adicional de cota.

6.2. Padrão de Erros RFC 7807

A API do Geodagio nunca retorna mensagens genéricas em texto puro ou páginas HTML de erro. Todas as respostas de falha seguem envelopes padronizados conforme a especificação RFC 7807 (Problem Details for HTTP APIs):

{
  "error": {
    "code": "INVALID_VEHICLE_AXLES",
    "message": "A quantidade de eixos informada (22) excede o limite máximo permitido pelo CONTRAN para composições rodoviárias (20 eixos).",
    "details": {
      "field": "vehicle.axleCount",
      "allowedRange": [1, 20]
    }
  },
  "meta": {
    "requestId": "req_f8e7d6c5b4a3",
    "apiVersion": "v1"
  }
}

7. Processamento em lote (Batch API) para cotação em escala

Quando uma transportadora precisa cotar 500 pedidos simultaneamente para um leilão de fretes ou rodar uma conciliação noturna de todas as viagens do dia anterior, abrir 500 conexões HTTP sequenciais gera latência acumulada excessiva e gargalos de rede (handshakes TLS repetidos).

O Geodagio disponibiliza o endpoint dedicado POST /api/v1/routes/batch, que aceita até 100 rotas em uma única requisição:

{
  "calculations": [
    {
      "origin": "Curitiba, PR",
      "destination": "Joinville, SC",
      "vehicle": { "axleCount": 6, "vehicleClassCode": "carreta-6-eixos" },
      "calculationDate": "2026-10-04"
    },
    {
      "origin": "São Paulo, SP",
      "destination": "Campinas, SP",
      "vehicle": { "axleCount": 3, "vehicleClassCode": "truck-3-eixos" },
      "calculationDate": "2026-10-04"
    },
    {
      "origin": "Belo Horizonte, MG",
      "destination": "Vitória, ES",
      "vehicle": { "axleCount": 7, "vehicleClassCode": "bitrem-7-eixos" },
      "calculationDate": "2026-10-04"
    }
  ]
}

O processamento interno executa as rotas de forma concorrente em memória, aplicando chaves de idempotência indexadas (${batchKey}:${index}) e devolvendo a matriz completa consolidada.

8. Como armazenar memória de cálculo e garantir auditoria fiscal

Um dos maiores gargalos contábeis em transportadoras é a divergência entre o pedágio cotado no frete e o valor efetivamente cobrado pela concessionária na fatura mensal da TAG (Sem Parar, ConectCar, Veloe, Move Mais).

A prática recomendada de engenharia envolve:

1. Persistência do Identificador de Rota: Salvar o UUID data.id retornado pela API na tabela de viagens ou na ordem de frete do TMS.
2. Armazenamento do JSON de Praças: Persistir o array charges contendo os IDs das praças, nomes das rodovias e tarifas esperadas para cada ponto.
3. Reconciliação Automática com a Fatura: Quando o arquivo eletrônico da operadora de TAG for importado no final do mês, cruzar as passagens de cada placa com a memória de cálculo armazenada no TMS.
4. Prova Pericial perante o Embarcador: Caso o embarcador conteste o valor antecipado no Vale-Pedágio Obrigatório, a transportadora pode consultar o cálculo histórico a qualquer momento via GET /api/v1/calculations/:id, demonstrando os dados oficiais vigentes na data da viagem.

9. Critérios técnicos para comparar provedores de API de pedágio

Antes de contratar um fornecedor de dados de rotas e pedágios para o seu ecossistema corporativo, avalie os seguintes critérios de maturidade técnica:

10. Arquitetura recomendada de integração com TMS, ERP e Portal de Cotação

O diagrama abaixo demonstra o fluxo de dados desacoplado e resiliente recomendado para integrar a API do Geodagio aos módulos de planejamento e faturamento de um sistema de transporte:

11. Perguntas Frequentes sobre a API de Pedágio (FAQ Técnico)

Fontes Oficiais e Regulatórias Homologadas

Este guia técnico foi elaborado com base nas regulamentações e fontes públicas oficiais vigentes em outubro de 2026:

• ANTT (Agência Nacional de Transportes Terrestres): Portal de Dados Abertos — Relação Oficial de Praças de Pedágio e Coordenadas Geográficas (dados.antt.gov.br).
• Regulamentação do Free Flow: Lei Federal nº 14.157/2021 e Resoluções ANTT nº 6.000/2022 e 6.024/2023.
• Vale-Pedágio Obrigatório: Lei Federal nº 10.209/2001 e Resolução ANTT nº 5.862/2019.
• Isenção de Eixo Suspenso: Lei Federal nº 13.103/2015 (Lei do Motorista), Artigo 17.
• Código de Trânsito Brasileiro (CTB): Artigo 209-A (Evasão de Pedágio e não pagamento em rodovias Free Flow).

Continue Explorando a Engenharia Logística do Geodagio:

• API de Rotas, KM & Pedágios Oficiais — Detalhes do produto de cálculo de rotas com pedágios físicos e Free Flow.
• VPO e Free Flow: Provisionamento e Reconciliação — Como evitar autuações por evasão e conciliar passagens automáticas.
• Cálculo do Custo Total de Rotas de Caminhão — Comparativo financeiro entre menor distância em KM e menor custo operacional.
• Documentação OpenAPI Interativa — Schemas completos, exemplos em tempo real e guias de segurança.