REFERÊNCIA TÉCNICA OFICIAL · OPENAPI 3.0.3

Documentação da API & Contratos de Integração

Explore os contratos OpenAPI padronizados, envelopes de resposta com idempotência e snippets de código para integrar em Node.js, Python e cURL.

Baixar Postman Collection (v2.1) Baixar Bruno Collection OpenAPI (YAML) Pacote Completo (ZIP)

BASE DE INTEGRAÇÃO

1. Autenticação, Idempotência e Headers Globais

Todas as requisições à API do Geodagio operam em produção sobre HTTPS. A autenticação utiliza cabeçalho padrão x-api-key: <API_KEY>.

x-api-key: <API_KEY>

Chave secreta obtida no painel administrativo do Geodagio. Nunca exponha sua chave em aplicações frontend públicas.

Idempotency-Key: <uuid>

Nos endpoints que suportam idempotência, reutilize a chave apenas para repetir a mesma operação e o mesmo payload. Consulte o contrato específico.

Dica de integração: Utilize o identificador interno do seu pedido/viagem (ex: IDEMPOTENCY_KEY=ped_948271) para identificar a operação; não reutilize a chave em pedidos diferentes.

ENDPOINTS DE PRODUÇÃO

2. Tabela Canônica de Endpoints sob /api/v1

Abaixo estão os principais endpoints de produção disponíveis em todos os planos ativos:

Rotas, KM & Pedágios Free Flow

POST /api/v1/routes/calculate

POST /api/v1/routes/batch

GET /api/v1/calculations/:id

Piso Mínimo ANTT & Pré-CIOT Lei 13.703/18

POST /api/v1/freight-floor/calculate

POST /api/v1/freight-floor/batch

RNTRC & Transportador Base ANTT CKAN

GET /api/v1/rntrc/transporters/:rntrc

POST /api/v1/rntrc/validate

GET /api/v1/rntrc/watch

Combustível & Preços ANP Dados Oficiais ANP

GET /api/v1/fuel/prices/latest

POST /api/v1/fuel/route-cost

POST /api/v1/fuel/route-stations

Emissões & Carbon Intelligence PB GHG Protocol

POST /api/v1/emissions/fuel

POST /api/v1/emissions/route

POST /api/v1/emissions/compare

Veículo, Carga & Pré-AET CONTRAN 882/2021

POST /api/v1/vehicle-compliance/validate

POST /api/v1/vehicle-compliance/aet/precheck

GET /api/v1/vehicle-compliance/traffic-restrictions

TRIC Transporte Internacional ATIT / Mercosul

POST /api/v1/tric/precheck

GET /api/v1/tric/border-posts

GET /api/v1/tric/country-rules

RECURSO EXCLUSIVO

3. Precheck de Viabilidade Rodoviária Multirregulatória

Pré-checagem de rota, piso mínimo ANTT e RNTRC. Este módulo está em homologação e sua execução depende de habilitação; o exemplo abaixo documenta seu contrato.

{
  "origin": "São Paulo, SP",
  "destination": "Curitiba, PR",
  "loadType": "LOTACAO",
  "cargoType": "CARGA_GERAL",
  "axles": 6,
  "hasReturnLoad": true
}

EXEMPLOS DE CÓDIGO

4. Snippets Prontos para Uso

curl -X POST 'https://geodagio.com/api/v1/routes/calculate' \
  -H 'x-api-key: SUA_API_KEY' \
  -H 'Idempotency-Key: exemplo-0001' \
  -H 'Content-Type: application/json' \
  -d '{
  "origin": "São Paulo, SP",
  "destination": "Curitiba, PR",
  "vehicle": {
    "axleCount": 6,
    "vehicleClassCode": "TRUCK_SEMI_TRAILER"
  },
  "calculationDate": "2026-09-03"
}'

const response = await fetch("https://geodagio.com/api/v1/routes/calculate", {
  method: "POST",
  headers: {
  "x-api-key": "SUA_API_KEY",
  "Idempotency-Key": "exemplo-0001",
  "Content-Type": "application/json"
},
  body: JSON.stringify({
  "origin": "São Paulo, SP",
  "destination": "Curitiba, PR",
  "vehicle": {
    "axleCount": 6,
    "vehicleClassCode": "TRUCK_SEMI_TRAILER"
  },
  "calculationDate": "2026-09-03"
})
});
const result = await response.json();
console.log(response.status, result);

import json
import requests

response = requests.request(
    "POST",
    "https://geodagio.com/api/v1/routes/calculate",
    headers={"x-api-key":"SUA_API_KEY","Idempotency-Key":"exemplo-0001","Content-Type":"application/json"},
    json=json.loads("{\n  \"origin\": \"São Paulo, SP\",\n  \"destination\": \"Curitiba, PR\",\n  \"vehicle\": {\n    \"axleCount\": 6,\n    \"vehicleClassCode\": \"TRUCK_SEMI_TRAILER\"\n  },\n  \"calculationDate\": \"2026-09-03\"\n}")
)
print(response.status_code, response.json())

ENVELOPE JSON DA API

5. Envelopes de Resposta e Códigos HTTP

Sucesso (HTTP 200/201)

{ "data": { ... }, "meta": { "requestId": "req_...", "apiVersion": "v1" } }

Erro Acionável (HTTP 4xx/5xx)

{ "error": { "code": "INSUFFICIENT_CREDITS", "message": "..." }, "meta": { ... } }

200 Operação calculada ou retornada com sucesso.

401 API Key ausente, expirada ou inválida.

402 Saldo de créditos insuficiente. Adquira créditos no Console.

409 Conflito de concorrência com mesma Idempotency-Key.

422 Falha de validação semântica. Payload fora do schema retorna HTTP 400.

429 Rate limit atingido. Aguarde antes de repetir a requisição.

PROCESSAMENTO ASSÍNCRONO

6. Processamento em Lote (Upload XLSX)

Para frotas com milhares de rotas diárias, a API suporta upload de planilhas Excel (.xlsx) via multipart/form-data no endpoint POST /api/v1/imports/xlsx. O sistema processa em background com fila dedicada e permite acompanhar o estado via polling. Informe file, axleCount, vehicleClassCode e calculationDate. Para piso ANTT, use /api/v1/freight-floor/imports/xlsx com file e mode=CALCULATION.

Criar conta e obter API key Falar com Suporte Técnico

Padrões de Confiabilidade & Segurança da API