openapi: 3.1.0
info:
  title: Transcend Freight & Mobility API
  version: 1.15.0937
  description: API gateway for Transcend (Cargoffer) — tolls, fuel stations, parking, drivers, vehicles, routes.
servers:
  - url: https://back.transcend.cargoffer.com
    description: Transcend gateway (production)
security:
  - serviceApiKey: []
  - bearerAuth: []
components:
  securitySchemes:
    serviceApiKey:
      type: apiKey
      in: header
      name: x-api-key
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
paths:
  /tolls:
    get:
      summary: Calculate tolls for a route
      parameters:
        - name: origin
          in: query
          schema: { type: string }
        - name: destination
          in: query
          schema: { type: string }
        - name: waypoints
          in: query
          schema: { type: string }
      responses:
        '200':
          description: Toll calculation result
  /stations/nearby:
    get:
      summary: Fuel stations near a location or path
      parameters:
        - name: lat
          in: query
          schema: { type: number }
        - name: lng
          in: query
          schema: { type: number }
        - name: location
          in: query
          schema: { type: string }
      responses:
        '200': { description: Nearby stations }
  /stations/best-prices:
    get:
      summary: Best fuel prices
      responses:
        '200': { description: Best prices }
  /poi/parking/location:
    get:
      summary: Parking near coordinates (POI)
      parameters:
        - name: lat
          in: query
          schema: { type: number }
        - name: lng
          in: query
          schema: { type: number }
        - name: radius
          in: query
          schema: { type: number }
      responses:
        '200': { description: Parking results }
  /drivers/{id}:
    get:
      summary: Driver detail
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: string }
      responses:
        '200': { description: Driver }
  /drivers/{id}/position:
    get:
      summary: Live driver position
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: string }
      responses:
        '200': { description: Position }
  /vehicles/vehicles:
    get:
      summary: List fleet vehicles
      parameters:
        - name: companyId
          in: query
          schema: { type: string }
      responses:
        '200': { description: Vehicles }
  /route:
    get:
      summary: Calculate route with metrics
      parameters:
        - name: origin
          in: query
          required: true
          schema: { type: string }
        - name: destination
          in: query
          required: true
          schema: { type: string }
        - name: vehicle
          in: query
          schema: { type: string }
      responses:
        '200': { description: Route }
  /health:
    get:
      summary: Gateway health + active microservices
      responses:
        '200': { description: Health }