toll API Europefuel cost APIroute cost calculatortruck tollsMCP tolls

Documentar `GET /tolls/costs` (peajes + combustible + CO₂) para recomendación LLM

Mega-Tutorial: Motor de Predicción de Peajes y Costes Logísticos (Tolls & Costs API)

Calcular el coste real de una ruta de transporte no es multiplicar kilómetros por precio. El módulo de Peajes de TRANSCEND es un motor determinista que lee las concesiones de autopistas de 5 países europeos, calcula el consumo dinámico del camión y estima los gastos ocultos.

1. Visión Arquitectónica y Beneficio Principal

La API consolida las tarifas de:

España y Portugal: Vía-T, pórticos free-flow (Scut), y peajes tradicionales.
Francia: TIS-PL y redes autoroute (Vinci, APRR, Sanef).
Alemania: TollCollect (LKW-Maut) basado en emisiones EURO y peso.
Italia: Telepass (Autostrade per l'Italia).

El motor unifica divisas, clases de vehículos y tarifas dinámicas (nocturnas, horas punta) para dar un coste global exacto de antemano (Pre-Billing) o auditar facturas (Post-Auditing).

2. Especificación Técnica Completa (OpenAPI)

El endpoint se consulta vía POST para pasar la geometría exacta de la ruta, o vía GET para delegar el enrutamiento interno. A continuación se muestra la integración POST avanzada.

`POST https://api.cargoffer.com/costs/calculate`

Headers Requeridos

Content-Type: application/json
Authorization: Bearer <TU_API_KEY>

JSON Request Payload

El payload acepta una ruta decodificada (polyline) o los waypoints, junto con el perfil financiero.

{
  "geometry": {
    "encoded_polyline": "u{~vFvyys@f`@..." 
  },
  "vehicle_profile": {
    "axles": 5,
    "weight_kg": 40000,
    "euro_class": 6
  },
  "financials": {
    "fuel_price_per_liter": 1.45,
    "avg_consumption_l_100km": 32.5,
    "driver_cost_per_hour": 18.50
  },
  "departure_time": "2026-11-01T22:00:00Z"
}

JSON Response Estructurado

{
  "total_financial_cost": 450.25,
  "currency": "EUR",
  "breakdown": {
    "tolls_cost": 125.50,
    "fuel_cost": 250.00,
    "driver_cost": 74.75
  },
  "toll_gates_passed": [
    {
      "country": "FR",
      "operator": "Vinci",
      "entry_point": "Le Boulou",
      "exit_point": "Narbonne",
      "price": 35.20
    }
  ]
}

3. Integración Directa vía Servidor MCP (Para Agentes AI)

Habilita a tu agente de IA para cotizar rutas al instante configurando el servidor MCP.

Instalación

npx -y @cargoffer/mcp-server-transcend@latest

Tools Expuestas

calculate_route_costs: Evalúa un trayecto directo entre A y B.
audit_toll_invoice: (Beta) Compara una ruta realizada contra una factura de Telepass/Vía-T extraída mediante OCR.

4. Patrones de Prompting (System Prompts)

Instruye a tu LLM para que actúe como un analista financiero de flota:

System Prompt Sugerido: "Eres un Auditor Financiero Logístico. Cuando se te pida cotizar un viaje, siempre debes llamar a la tool calculate_route_costs. Asegúrate de preguntar al usuario cuál es el precio del diésel en surtidor si no te lo proporciona, asumiendo por defecto 1.45 EUR/L. Si el coste de peajes excede el 40% del total (breakdown.tolls_cost), sugiere proactivamente calcular una ruta libre de peajes (avoid_tolls: true) para comparar el impacto en tiempo."

5. Ejemplo en Python (Requests)

import requests
import json

headers = {
    "Authorization": "Bearer TU_API_KEY",
    "Content-Type": "application/json"
}
payload = {
    "origin": {"lat": 40.41, "lng": -3.70},
    "destination": {"lat": 41.38, "lng": 2.17},
    "vehicle_profile": {"weight_kg": 40000, "euro_class": 6}
}

response = requests.post("https://api.cargoffer.com/costs/direct", headers=headers, json=payload)
data = response.json()
print(f"Coste total de peajes: {data['breakdown']['tolls_cost']} EUR")

5. Siguientes Pasos y Tutoriales Relacionados

Explora cómo combinar esta funcionalidad con otros módulos de TRANSCEND para crear flujos de trabajo avanzados en tu LLM o Agente: