API de peajes para TMS: presupuestar, despachar y auditar rutas

Respuesta directa: un TMS necesita el coste de peaje en tres momentos —al presupuestar el servicio al cliente, al elegir ruta en el despacho y al conciliar la factura del operador— y los tres se resuelven contra la misma API de peajes, cambiando solo cuándo y con qué precisión se consulta.

Los tres puntos de integración

1. Pre-billing (cotización)

En el momento de la oferta, el pedido aún no tiene ruta definitiva. Consulta con origen, destino y perfil estándar de la unidad asignada, y guarda el resultado marcado como estimación. Aquí conviene el endpoint de costes (POST https://api.cargoffer.com/costs/calculate), que devuelve peaje + combustible + conductor en una sola llamada.

2. Decisión de ruta en despacho

Cuando el algoritmo de routing genera dos o tres candidatas, compara el peaje de cada una enviando su polilínea al endpoint de peajes. La ruta "más barata" en kilómetros no siempre gana en coste total: un desvío de 30 km sin peaje puede batir a la autopista. Documenta el perfil de cada vehículo una sola vez y reutilízalo —ver calculadora de peajes para camiones—.

3. Post-auditing (conciliación de facturas)

Con la ruta realmente realizada (de tu GPS o del tacógrafo), vuelve a calcular el peaje esperado y compara tramo a tramo contra la factura del operador. El desglose por toll_sections está diseñado para esto: localize el tramo exacto donde la factura se desvía de lo esperado.

Patrón de integración de ejemplo

// Pseudocódigo de adaptación en tu TMS (Node.js)
async function quoteOrder(order: Order) {
  const route = await router.calculate(order.waypoints, order.truckProfile);
  const tolls = await tollsClient.calculate({
    polyline: route.polyline,
    vehicle_class: order.truckProfile.tollClass,
    payment_method: order.truckProfile.badge ?? 'CASH',
  });
  return { estimate: tolls.total_toll_cost_eur, queriedAt: new Date().toISOString(), routeId: route.id };
}

Claves del patrón: guardar la fecha de consulta junto al importe (las tarifas cambian), asociar el resultado a la geometría de ruta concreta y nunca sobrescribir la estimación al auditar: la desviación entre estimación y factura es el dato que buscas.

Requisitos antes de integrar

• Perfil de vehículo por matrícula: ejes, masa, clase EURO y transpondedor habitual.
• Un enrutador de pesados que produzca polilíneas; la API de peajes no traza rutas por sí sola salvo que uses el endpoint de costes con waypoints.
• Política de redondeo para ofertas: una estimación no es un precio en firme hasta la consulta del día del viaje.

Aviso: cualquier cifra usada en documentación de integración es ilustrativa; el resultado real depende de la consulta en vivo.