openapi: 3.0.0
info:
  title: Tolls
  description: '# 🚛 Módulo de Gestión de Peajes


    Este API es parte de la plataforma **Transcend** y proporciona funcionalidades
    completas para calcular y gestionar costos de peajes en rutas de transporte de
    mercancías.


    ## 🎯 Casos de Uso Principales


    - **Planificación de Rutas**: Calcular costos totales de transporte incluyendo
    peajes, combustible y mantenimiento

    - **Presupuestos**: Obtener desglose detallado de costos para propuestas comerciales

    - **Optimización**: Identificar rutas más económicas considerando peajes y tiempos

    - **Análisis Ambiental**: Calcular emisiones de CO2 para reportes de sostenibilidad


    ## 🚀 Características Principales


    - **Cálculo Inteligente**: Costos de peajes, combustible, mantenimiento y tiempo
    de conducción

    - **Tiempos Legales**: Incluye tiempos de descanso obligatorios según normativa
    de transporte

    - **Múltiples Combustibles**: Soporte para diesel, gasolina y gas natural vehicular

    - **Peajes Detallados**: Información por peaje individual con métodos de pago

    - **Cache Optimizado**: Rutas frecuentes cacheadas por 24 horas

    - **Integración Geolocalización**: Google Maps, Here Maps y sistemas de navegación


    ## 📊 Límites Operativos


    | Parámetro | Límite | Descripción |

    |-----------|--------|-------------|

    | Distancia máxima | 1,000 km | Entre origen y destino |

    | Peajes por ruta | 50 | Máximo número de peajes procesados |

    | Actualización precios | 24h | Frecuencia de actualización de tarifas |

    | Tasa de requests | 100/min | Por cliente autenticado |

    | Coordenadas | WGS84 | Sistema de coordenadas estándar |


    ## 🔐 Autenticación


    La autenticación es **opcional** pero recomendada para acceso a funcionalidades
    avanzadas y límites elevados.


    ```http

    # Ejemplo de uso con autenticación

    GET /api/costs?origin={"lat":41.3851,"lng":2.1734}&destination={"lat":40.4168,"lng":-3.7038}

    Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

    ```


    ## 🎪 Ejemplo Completo


    ```bash

    # Cálculo de ruta Barcelona -> Madrid con carga completa

    curl -X GET "https://back.transcend.cargoffer.com/tolls/costs?\

    origin={\"lat\":41.3851,\"lng\":2.1734}&\

    destination={\"lat\":40.4168,\"lng\":-3.7038}&\

    with_tolls=true&\

    avg_consumption=35&\

    cargo_weight=15000&\

    fuel_type=diesel" \

    -H "Authorization: Bearer your_jwt_token_here"

    ```

    '
  version: 1.0.0
  contact:
    email: support@cargoffer.com
    name: Equipo de Soporte Transcend
    url: https://transcend.cargoffer.com/support
  license:
    name: Private API - Access by agreement only
    url: https://transcend.cargoffer.com/terms
servers:
- url: https://api.pro.cargoffer.com
  description: Producción
tags:
- name: Route Calculation
  description: Endpoints para el cálculo de costos y peajes en rutas.
components:
  schemas:
    RouteCostResponse:
      type: object
      description: "# \U0001F4CB Respuesta de Costos de Ruta\n\nRespuesta completa\
        \ con todos los costos calculados para una ruta de transporte.\nIncluye desglose\
        \ detallado de peajes, combustible, mantenimiento, tiempo y emisiones ambientales.\n\
        \n## \U0001F4B0 Campos Principales\n\n- **Costos Totales**: `total_cost` en\
        \ el objeto `costs`\n- **Duración**: Incluye descansos legales obligatorios\n\
        - **Distancia**: En metros para precisión\n- **Emisiones**: CO2 en kg para\
        \ reportes de sostenibilidad\n\n## \U0001F3AF Ejemplo de Uso\n\n```json\n\
        {\n  \"duration\": 343,\n  \"distance\": 621456,\n  \"departure\": \"2025-05-15T08:00:00+02:00\"\
        ,\n  \"arrival\": \"2025-05-15T15:43:00+02:00\",\n  \"total_tolls\": 87.25,\n\
        \  \"fuel\": 186.43,\n  \"co2\": 499.62,\n  \"fuel_type\": \"diesel\",\n \
        \ \"costs\": {\n    \"total_cost\": 542.89,\n    \"toll\": 87.25,\n    \"\
        fuel\": {\n      \"monetary\": 240.49,\n      \"fuel\": 186.43\n    },\n \
        \   // ... más componentes de costo\n  },\n  \"tolls\": [\n    {\n      \"\
        country\": \"ES\",\n      \"cia_name\": \"ASEFA\",\n      \"price\": 12.75,\n\
        \      \"currency\": \"EUR\",\n      \"paymentMethods\": [\"cash\", \"card\"\
        ]\n    }\n    // ... más peajes\n  ]\n}\n```\n"
      properties:
        duration:
          type: number
          description: '**⏱️ Duración Total del Viaje**


            Tiempo total en minutos, incluyendo **descansos legales obligatorios**.


            - Se añaden 45 minutos de descanso por cada 4.5 horas de conducción

            - Basado en normativa europea de transporte

            '
          example: 343
        distance:
          type: number
          description: '**📏 Distancia Total**


            Longitud total de la ruta en **metros**.


            **Conversión**: Dividir entre 1000 para obtener kilómetros

            '
          example: 621456
        departure:
          type: string
          format: date-time
          description: '**🕐 Hora de Salida Real**


            Fecha y hora de inicio del viaje con zona horaria.

            Puede diferir del parámetro `departure` si se calcula basado en `arrival`.

            '
          example: '2025-05-15T08:00:00+02:00'
        arrival:
          type: string
          format: date-time
          description: '**🕔 Hora de Llegada Estimada**


            Fecha y hora estimada de llegada con zona horaria.

            Incluye el efecto de los descansos legales.

            '
          example: '2025-05-15T15:43:00+02:00'
        fuelPrice:
          type: number
          description: '**⛽ Precio del Combustible**


            Precio medio del combustible por litro en EUR.

            Basado en datos de mercado actualizados.

            '
          example: 1.29
        timeCost:
          type: number
          description: '**💰 Costo del Tiempo**


            Valor del tiempo de conducción en minutos.

            Usado para cálculos de productividad.

            '
          example: 343
        fuelCost:
          type: number
          description: '**💶 Costo Total de Combustible**


            Costo total del combustible consumido en EUR.

            Calculado como: `fuel * fuelPrice`

            '
          example: 240.49
        total_tolls:
          type: number
          description: '**🏷️ Costo Total de Peajes**


            Suma de todos los peajes en la ruta en EUR.

            Coincide con `costs.toll` en el desglose detallado.

            '
          example: 87.25
        tolls:
          type: array
          description: '**📋 Lista Detallada de Peajes**


            Array con información individual de cada peaje en la ruta.

            Solo presente cuando `with_tolls=true`.


            **Orden**: Aparecen en el orden de la ruta

            '
          items:
            type: object
            description: Información de un peaje individual
            properties:
              country:
                type: string
                description: Código ISO del país (ES, FR, PT, etc.)
                example: ES
              cia_name:
                type: string
                description: Nombre de la compañía gestora del peaje
                example: ASEFA
              price:
                type: number
                description: Precio del peaje en EUR
                example: 12.75
              currency:
                type: string
                description: Moneda del peaje (siempre EUR)
                example: EUR
              paymentMethods:
                type: array
                description: Métodos de pago aceptados en el peaje
                items:
                  type: string
                example:
                - cash
                - card
        fuel:
          type: number
          description: '**🛢️ Consumo de Combustible**


            Total de litros de combustible consumidos en el viaje.

            Afectado por `cargo_weight` y `avg_consumption`.

            '
          example: 186.43
        co2:
          type: number
          description: '**🌱 Emisiones de CO2**


            Kilogramos de CO2 emitidos durante el viaje.

            Calculado según el tipo de combustible y distancia.

            '
          example: 499.62
        fuel_type:
          type: string
          description: '**🔥 Tipo de Combustible Usado**


            Tipo de combustible considerado para los cálculos.

            Coincide con el parámetro `fuel_type` o usa el valor por defecto.

            '
          example: diesel
        costs:
          type: object
          description: '# 💰 Desglose Completo de Costos


            Objeto con el desglose detallado de todos los costos operativos del viaje.


            ## 🛠️ Componentes de Mantenimiento


            Costos calculados basados en el desgaste por kilómetro de cada componente
            del vehículo.


            ## ⛽ Costos de Combustible


            Incluye tanto el costo monetario como el consumo en litros.


            ## 🏷️ Peajes


            Costo total de peajes (coincide con `total_tolls`).

            '
          properties:
            oil:
              type: number
              description: Costo de cambio de aceite por km
              example: 1.035
            oil_filter:
              type: number
              description: Costo de filtro de aceite por km
              example: 0.414
            fuel_filter:
              type: number
              description: Costo de filtro de combustible por km
              example: 0.414
            brake_paste:
              type: number
              description: Costo de pastillas de freno por km
              example: 0.31
            brake_liquid:
              type: number
              description: Costo de líquido de frenos por km
              example: 0.31
            cabine_filter:
              type: number
              description: Costo de filtro de cabina por km
              example: 0.515
            direccion:
              type: number
              description: Costo de dirección por km
              example: 0.515
            escape:
              type: number
              description: Costo de escape por km
              example: 0.515
            wheels:
              type: number
              description: Costo de ruedas por km (8 ruedas)
              example: 4.367
            clutch:
              type: number
              description: Costo de embrague por km
              example: 5.17
            aire:
              type: number
              description: Costo de filtro de aire por km
              example: 0.157
            correa:
              type: number
              description: Costo de correa de distribución por km
              example: 4.136
            toll:
              type: number
              description: Costo total de peajes
              example: 87.25
            fuel:
              type: object
              description: Costos relacionados con el combustible
              properties:
                monetary:
                  type: number
                  description: Costo monetario total del combustible
                  example: 240.49
                fuel:
                  type: number
                  description: Litros totales de combustible consumidos
                  example: 186.43
            total_cost:
              type: number
              description: '**💰 Costo Total del Viaje**


                Suma de todos los costos: mantenimiento + combustible + peajes.


                **Fórmula**: `sum(mantenimiento) + fuel.monetary + toll`

                '
              example: 542.89
      required:
      - duration
      - distance
      - fuelCost
      - costs
      - total_tolls
      - fuel
      - co2
      - fuel_type
    Error:
      type: object
      description: 'Respuesta de error estandarizada.

        Todos los errores incluyen código HTTP y mensaje descriptivo.

        '
      properties:
        message:
          type: string
          description: 'Mensaje descriptivo del error.

            Ejemplos:

            - "Token JWT inválido o expirado"

            - "Parámetro ''origin'' es requerido"

            - "Distancia entre origen y destino excede el límite de 1000km"

            '
          example: Token JWT inválido o expirado
        code:
          type: integer
          description: Código HTTP del error
          example: 401
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: 'Autenticación mediante JWT obtenido del servicio IAM de Transcend.

        Formato del header:

        ```

        Authorization: Bearer {token}

        ```

        '
  parameters:
    AuthorizationHeader:
      name: Authorization
      in: header
      required: false
      schema:
        type: string
      description: 'Token JWT de Autenticación. Formato: `Bearer {token}`.

        El token se obtiene del servicio de IAM de Transcend.

        Opcional - si no se proporciona, se procesa la solicitud sin autenticación.

        '
      example: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VySWQiOiI2M2Q3OTA3Y2JlNzY0MDNiMzVkYTYzZGYiLCJlbWFpbCI6ImNpYUB0ZXN0aW5nLmNvbSIsInJvbGUiOiJhZG1pbiIsImlhdCI6MTc0MTI3NzU2OSwiZXhwIjoxNzQxMzYzOTY5fQ.9LtCdRFKVXB2oONyupGToxYz_wu4zH9dKhmw2beBNGI
paths:
  /costs:
    get:
      tags:
      - Route Calculation
      summary: 📊 Calcular costos completos de ruta
      description: '# 🛣️ Cálculo de Costos de Ruta


        Calcula los costos completos de una ruta de transporte, incluyendo:

        - **Peajes**: Costos detallados por peaje individual

        - **Combustible**: Consumo y costo basado en tipo de vehículo y carga

        - **Mantenimiento**: Desgaste de componentes del vehículo

        - **Tiempo**: Duración del viaje con descansos legales incluidos

        - **Emisiones**: Cálculo de CO2 emitido durante el trayecto


        ## 🎯 Casos de Uso


        - **Transportistas**: Presupuestar costos de operación

        - **Logística**: Comparar rutas alternativas

        - **Finanzas**: Predecir costos operativos

        - **Sostenibilidad**: Reportar huella de carbono


        ## 📝 Ejemplos Prácticos


        ### Ejemplo Básico (Sin Autenticación)

        ```http

        GET /costs?origin={"lat":41.3851,"lng":2.1734}&destination={"lat":40.4168,"lng":-3.7038}

        ```


        ### Ejemplo Avanzado (Con Autenticación)

        ```http

        GET /costs?origin={"lat":41.3851,"lng":2.1734}&destination={"lat":40.4168,"lng":-3.7038}&with_tolls=true&avg_consumption=35&cargo_weight=15000&fuel_type=diesel

        Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

        ```


        ### Ejemplo con Horarios Específicos

        ```http

        GET /costs?origin={"lat":41.3851,"lng":2.1734}&destination={"lat":40.4168,"lng":-3.7038}&departure=2025-05-15T08:00:00&arrival=2025-05-15T18:00:00

        ```


        ## ⚠️ Consideraciones Importantes


        - **Formato Coordenadas**: Usar formato JSON con lat/lng en grados decimales

        - **Distancia Máxima**: 1,000 km entre origen y destino

        - **Cache**: Resultados cacheados 24 horas para rutas idénticas

        - **Tiempos Legales**: Se incluyen descansos obligatorios cada 4.5 horas

        - **Moneda**: Todos los costos en EUR (Euros)

        '
      operationId: getRouteCosts
      security:
      - bearerAuth: []
      parameters:
      - $ref: '#/components/parameters/AuthorizationHeader'
      - name: origin
        in: query
        description: '**📍 Punto de Origen**


          Coordenadas de inicio de la ruta en formato JSON.


          **Formato**: `{"lat": número, "lng": número}`

          **Sistema**: WGS84 (grados decimales)

          **Precisión**: 6 decimales recomendados


          **Ejemplos**:

          - Barcelona: `{"lat":41.3851,"lng":2.1734}`

          - Madrid: `{"lat":40.4168,"lng":-3.7038}`

          - Valencia: `{"lat":39.4699,"lng":-0.3763}`


          **Límites**:

          - Latitud: -90 a 90

          - Longitud: -180 a 180

          '
        required: true
        schema:
          type: string
          pattern: ^\{"lat":-?\d+(\.\d+)?,"lng":-?\d+(\.\d+)?\}$
        example: '{"lat":41.3851,"lng":2.1734}'
      - name: destination
        in: query
        description: '**🎯 Punto de Destino**


          Coordenadas de destino de la ruta en formato JSON.


          Mismos requisitos y formato que el parámetro `origin`.


          **Validación**: La distancia entre origen y destino no puede exceder 1,000
          km.

          '
        required: true
        schema:
          type: string
          pattern: ^\{"lat":-?\d+(\.\d+)?,"lng":-?\d+(\.\d+)?\}$
        example: '{"lat":40.4168,"lng":-3.7038}'
      - name: departure
        in: query
        description: '**🕐 Hora de Salida**


          Fecha y hora de inicio del viaje. Usado para calcular peajes con tarifas
          variables por horario.


          **Formato**: ISO 8601 `YYYY-MM-DDTHH:MM:SS`

          **Zona Horaria**: Se asume la zona horaria del servidor si no se especifica

          **Valor por Defecto**: Hora actual del servidor


          **Ejemplos**:

          - Mañana a las 8:00: `2025-05-15T08:00:00`

          - Tarde a las 14:30: `2025-05-15T14:30:00`

          '
        required: false
        schema:
          type: string
          format: date-time
          pattern: ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}$
        example: '2025-05-15T08:00:00'
      - name: arrival
        in: query
        description: '**🕔 Hora de Llegada Estimada**


          Fecha y hora estimada de llegada. Si se especifica, se usa para cálculo
          de peajes nocturnos.


          **Nota**: No puede usarse simultáneamente con `departure`

          **Comportamiento**: Si se especifica `arrival`, se ignora `departure`

          '
        required: false
        schema:
          type: string
          format: date-time
          pattern: ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}$
        example: '2025-05-15T12:30:00'
      - name: with_tolls
        in: query
        description: '**💰 Incluir Detalles de Peajes**


          Controla si se incluye información detallada de cada peaje en la respuesta.


          - `true`: Incluye array `tolls` con detalles de cada peaje

          - `false`: Solo incluye costo total en `total_tolls`


          **Recomendación**: Usar `true` para análisis detallado, `false` para respuestas
          más rápidas.

          '
        required: false
        schema:
          type: boolean
          default: true
        example: true
      - name: with_points
        in: query
        description: '**🔄 Incluir Puntos Intermedios**


          Incluye puntos de la ruta para visualización en mapas.


          **Costo**: Aumenta ligeramente el tiempo de respuesta

          **Uso**: Principalmente para interfaces gráficas

          '
        required: false
        schema:
          type: boolean
          default: false
        example: false
      - name: avg_consumption
        in: query
        description: '**⛽ Consumo Medio de Combustible**


          Consumo del vehículo en litros por cada 100 km.


          **Valores Típicos**:

          - Camión ligero: 25-35 L/100km

          - Camión pesado: 35-45 L/100km

          - Tráiler: 40-55 L/100km


          **Impacto**: Afecta directamente los costos de combustible y mantenimiento

          '
        required: false
        schema:
          type: number
          format: float
          minimum: 20
          maximum: 100
          default: 35
        example: 35
      - name: cargo_weight
        in: query
        description: '**📦 Peso de la Carga**


          Peso total de la mercancía transportada en kilogramos.


          **Efecto**: Aumenta el consumo de combustible aproximadamente 0.02 L/100km
          por kg

          **Ejemplos**:

          - Carga ligera: 5,000 kg

          - Carga media: 15,000 kg

          - Carga completa: 25,000 kg

          '
        required: false
        schema:
          type: number
          format: float
          minimum: 0
          maximum: 50000
        example: 15000
      - name: fuel_type
        in: query
        description: '**🔥 Tipo de Combustible**


          Tipo de combustible utilizado por el vehículo.


          **Opciones**:

          - `diesel`: Gasóleo (predeterminado)

          - `gasoline`: Gasolina

          - `gnv`: Gas Natural Vehicular


          **Impacto**: Afecta el cálculo de emisiones de CO2 y costos de combustible

          '
        required: false
        schema:
          type: string
          enum:
          - diesel
          - gasoline
          - gnv
          default: diesel
        example: diesel
      responses:
        '200':
          description: Cálculo exitoso de costos de peaje
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RouteCostResponse'
        '400':
          description: Parámetros inválidos o faltantes
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: No autorizado (token inválido o faltante)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Error interno del servidor
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'