🚚 Frete API

API REST desenvolvida em Python + FastAPI para validação e cálculo automatizado de cotações de frete rodoviário.

A aplicação recebe informações de uma carga, valida os CEPs de origem e destino, calcula automaticamente a rota rodoviária, obtém uma estimativa de pedágios e aplica as regras de cálculo de frete configuradas no projeto.

O projeto foi estruturado para funcionar também como backend de agentes de IA, mantendo as regras de negócio, validações e cálculos centralizados na API.

📌 Funcionalidades

Validação dos dados de entrada com Pydantic
Validação de CEPs
Consulta de endereços através do ViaCEP
Cálculo automático da distância rodoviária
Estimativa da duração da viagem
Estimativa de pedágios
Cálculo de frete por quilometragem e número de eixos
Aplicação de custo de carga e descarga
Validação de urgência e data limite
Cálculo do valor final da cotação
Contrato de resposta com Pydantic
Documentação automática com Swagger/OpenAPI
Endpoint de health check
Testes automatizados com Pytest
Integrações externas desacopladas em services
Estrutura preparada para deploy na Vercel
Arquitetura preparada para integração com agentes de IA

🏗️ Arquitetura

O fluxo principal da aplicação é:

Cliente / Agente
       │
       ▼
 POST /cotacao
       │
       ▼
Validação Pydantic
       │
       ▼
Validação dos CEPs
       │
       ▼
    ViaCEP
       │
       ▼
Google Routes API
   │           │
   ▼           ▼
Distância    Duração
   │
   └──────► Pedágio estimado
                │
                ▼
        Motor de cálculo
                │
                ▼
        Tabela de frete
                │
                ▼
          Frete base
                │
                ▼
    Frete base + Pedágio
                │
                ▼
         Cotação final

A responsabilidade de calcular distância, duração e estimativa de pedágio fica no backend.

O consumidor da API não precisa informar manualmente a quilometragem da rota.

🛠️ Tecnologias

Python 3.12+
FastAPI
Pydantic
Uvicorn
HTTPX
python-dotenv
Pytest
ViaCEP
Google Routes API
Git / GitHub
Vercel

📂 Estrutura do projeto

frete-api/
│
├── api/
│   └── index.py
│
├── app/
│   ├── data/
│   │   └── tabela_frete.json
│   │
│   ├── models/
│   │   ├── cotacao.py
│   │   └── cotacao_response.py
│   │
│   ├── routes/
│   │   └── cotacao.py
│   │
│   ├── services/
│   │   ├── calculo_frete_service.py
│   │   ├── cep_service.py
│   │   ├── cotacao_service.py
│   │   └── rota_service.py
│   │
│   ├── config.py
│   └── main.py
│
├── tests/
│   ├── test_calculo_frete.py
│   ├── test_cotacao_endpoint.py
│   └── test_cotacao_model.py
│
├── .gitignore
├── README.md
└── requirements.txt

🧮 Como funciona o cálculo

O cálculo do frete base utiliza a seguinte regra:

Frete base =
(distância em km × coeficiente por eixo)
+ custo de carga/descarga

Exemplo

Distância:          500 km
Número de eixos:    3
Coeficiente:        R$ 5,0977/km
Carga/descarga:     R$ 541,86

Cálculo do deslocamento:

500 × 5,0977
= R$ 2.548,85

Adicionando carga e descarga:

R$ 2.548,85 + R$ 541,86
= R$ 3.090,71

A cotação final considera também a estimativa de pedágio:

Cotação final =
Frete base + Pedágio estimado

⚠️ Estimativa de pedágios

Os valores de pedágio são obtidos através da Google Routes API.

Esses valores são tratados pela aplicação como estimativas.

Eles não devem ser interpretados como garantia do valor efetivamente cobrado para veículos comerciais, pois tarifas reais podem variar conforme:

categoria do veículo;
número de eixos;
concessionária;
praça de pedágio;
rota efetivamente utilizada;
alterações tarifárias.

Uma integração especializada em pedágios para veículos comerciais poderá substituir essa fonte em versões futuras.

📥 Exemplo de requisição

Endpoint

POST /cotacao

Body

{
  "cep_origem": "30130-010",
  "cep_destino": "01001-000",
  "peso_total_kg": 15000,
  "valor_declarado": 45000,
  "quantidade_volumes": 500,
  "numero_eixos": 3,
  "urgencia": "normal",
  "data_limite": null
}

A quilometragem não precisa ser informada.

A própria API determina a distância rodoviária entre origem e destino.

📤 Exemplo de resposta

{
  "origem": {
    "cep": "30130-010",
    "logradouro": "Praça Sete de Setembro",
    "bairro": "Centro",
    "cidade": "Belo Horizonte",
    "estado": "MG"
  },
  "destino": {
    "cep": "01001-000",
    "logradouro": "Praça da Sé",
    "bairro": "Sé",
    "cidade": "São Paulo",
    "estado": "SP"
  },
  "carga": {
    "peso_total_kg": 15000,
    "valor_declarado": 45000,
    "quantidade_volumes": 500,
    "numero_eixos": 3
  },
  "rota": {
    "distancia_km": 583.22,
    "duracao_minutos": 461,
    "pedagios": {
      "valor_estimado": 25.6,
      "moeda": "BRL",
      "fonte": "Google Routes"
    }
  },
  "calculo_frete": {
    "tabela": {
      "versao": "2026-07-16",
      "fonte": "Tabela ANTT fornecida pela logística",
      "vigencia_inicio": "2026-07-16"
    },
    "quilometragem": 583.22,
    "numero_eixos": 3,
    "coeficiente_km": 5.0977,
    "custo_deslocamento": 2973.08,
    "custo_carga_descarga": 541.86,
    "valor_total_frete": 3514.94
  },
  "resumo_cotacao": {
    "frete_base": 3514.94,
    "pedagio_estimado": 25.6,
    "valor_total_cotacao": 3540.54,
    "moeda": "BRL"
  },
  "prazo": {
    "urgencia": "normal",
    "data_limite": null
  },
  "status": "Cotação calculada com sucesso"
}

🚀 Executando localmente

1. Clone o repositório

git clone https://github.com/Eubastosdev/frete-api.git
cd frete-api

2. Crie um ambiente virtual

Windows

py -3.12 -m venv .venv
.\.venv\Scripts\Activate.ps1

Linux/macOS

python3 -m venv .venv
source .venv/bin/activate

3. Instale as dependências

python -m pip install -r requirements.txt

🔐 Variáveis de ambiente

Crie um arquivo:

.env

na raiz do projeto.

Adicione:

GOOGLE_MAPS_API_KEY=SUA_CHAVE_AQUI

A chave precisa possuir acesso à Google Routes API.

Nunca versione o arquivo .env, API Keys, tokens ou outras credenciais.

Opcionalmente, utilize um .env.example:

GOOGLE_MAPS_API_KEY=

▶️ Iniciando a aplicação

Execute:

python -m uvicorn app.main:app --reload

A API estará disponível em:

http://127.0.0.1:8000

📖 Swagger

A documentação interativa pode ser acessada em:

http://127.0.0.1:8000/docs

📄 OpenAPI

O schema OpenAPI está disponível em:

http://127.0.0.1:8000/openapi.json

Esse schema pode ser utilizado por aplicações e agentes para compreender o contrato da API.

❤️ Health Check

GET /health

Resposta esperada:

{
  "status": "ok"
}

🧪 Testes

Execute:

python -m pytest -v

A suíte atual testa:

cálculo de frete;
cálculo de 500 km com veículo de 3 eixos;
validação de urgência;
obrigatoriedade de data para cargas urgentes;
validação de peso;
validação de número de eixos;
endpoint completo de cotação;
cálculo do valor final;
integração entre rota, frete e pedágio utilizando mocks.

As APIs externas são simuladas nos testes do endpoint.

Isso evita:

dependência de conexão com a internet;
consumo desnecessário da Google Routes API;
instabilidade causada por serviços externos.

Resultado validado durante o desenvolvimento:

7 passed

☁️ Deploy na Vercel

O projeto possui um entrypoint específico para execução na Vercel:

api/
└── index.py

O arquivo expõe a aplicação FastAPI:

from app.main import app

Isso permite manter a implementação principal em:

app/main.py

sem acoplar a lógica da aplicação ao provedor de hospedagem.

Configuração na Vercel

Importe o repositório GitHub para a Vercel.

Configure:

Application Preset: FastAPI
Root Directory: ./

Em:

Project Settings
→ Environment Variables

adicione:

GOOGLE_MAPS_API_KEY

com sua chave real da Google Routes API.

A chave deve existir somente como variável de ambiente e nunca dentro do código-fonte.

Validação após o deploy

Após a publicação, valide:

/health

Depois:

/docs

E:

/openapi.json

Por último, realize uma requisição:

POST /cotacao

para validar as integrações externas no ambiente publicado.

🔒 Segurança

O projeto não deve versionar:

.env
.venv/
venv/
__pycache__/
.pytest_cache/
.vscode/
*.pyc
*.log

Credenciais devem ser fornecidas exclusivamente através de variáveis de ambiente.

🌐 Serviços externos

ViaCEP

Responsável pela validação dos CEPs e obtenção dos dados de endereço utilizados pela aplicação.

Google Routes API

Responsável por fornecer:

distância rodoviária;
duração estimada;
estimativa de pedágios.

🤖 Integração com agentes de IA

A API foi estruturada para funcionar como uma camada de regras de negócio para agentes de IA.

O agente não precisa executar diretamente:

validação de CEP;
cálculo de distância;
cálculo do frete;
aplicação dos coeficientes;
estimativa de pedágios;
soma da cotação.

O fluxo esperado é:

Usuário
   │
   ▼
Agente de IA
   │
   ▼
Frete API
   │
   ├── valida dados
   ├── valida CEPs
   ├── calcula rota
   ├── estima pedágio
   ├── calcula frete
   └── calcula total
   │
   ▼
Resposta estruturada
   │
   ▼
Agente
   │
   ▼
Usuário

Isso mantém as regras críticas de negócio centralizadas no backend.

🗺️ Roadmap

🎯 Objetivo do projeto

A Frete API foi desenvolvida para centralizar cálculos e validações relacionados à cotação de frete rodoviário.

O objetivo é permitir que sistemas, aplicações ou agentes de IA enviem apenas os dados essenciais da carga e recebam uma cotação estruturada e reproduzível.

A arquitetura mantém as regras de negócio dentro da API, evitando que consumidores externos precisem reproduzir a lógica de cálculo.

Name		Name	Last commit message	Last commit date
api		api
app		app
tests		tests
.gitignore		.gitignore
README.md		README.md
requirements.txt		requirements.txt

Latest commit

History

Folders and files

Repository files navigation