Qargo Use case / Tracking API

openapi: 3.2.0
info:
  title: Qargo TMS Use case / Tracking API
  description: For support, please contact integrations@qargo.com.
  version: 1.2.0
servers:
- url: https://api.qargo.com
tags:
- name: Use case / Tracking
  description: ''
paths:
  /v1/webhook/tracking-update:
    post:
      tags:
      - Use case / Tracking
      summary: Tracking Update
      description: 'Webhook for tracking updates.


        Push to the endpoint to update tracking information for a resource.'
      operationId: tracking-update
      security:
      - BasicAuthWebhookCredentials: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TrackingUpdatePayload'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                anyOf:
                - $ref: '#/components/schemas/TrackingUpdateResponse'
                - type: 'null'
                title: Response Tracking-Update
        '400':
          description: Bad Request — invalid input or malformed request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationErrorResponse'
        '401':
          description: Unauthorized — missing or invalid authentication credentials
        '403':
          description: Forbidden — insufficient permissions for this operation
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
        '429':
          description: Too Many Requests — rate limit exceeded. See the `Retry-After` header
        '500':
          description: Internal Server Error
        '503':
          description: Service Unavailable — temporarily unable to handle the request
components:
  schemas:
    VehicleMatchInput:
      properties:
        name:
          anyOf:
          - $ref: '#/components/schemas/FieldMatchInput'
          - type: 'null'
        generic_id:
          anyOf:
          - $ref: '#/components/schemas/FieldMatchInput'
          - type: 'null'
        integration_object_id:
          anyOf:
          - $ref: '#/components/schemas/FieldMatchInput'
          - type: 'null'
          description: 'The resource ID in the given context of your integration. '
      type: object
      title: VehicleMatchInput
      example:
        generic_id:
          matches_any:
          - VEH-001
    TrackingUpdateResponse:
      properties:
        errors:
          anyOf:
          - items:
              $ref: '#/components/schemas/ErrorStatus'
            type: array
          - type: 'null'
          title: Errors
          description: List of errors that occurred during the webhook processing. If empty/omitted, the webhook was processed successfully.
          examples:
          - error_message: The payload is invalid.
            error_type: USER_INPUT_ERROR
          - error_message: Not supported.
            error_type: NOT_SUPPORTED
          - error_message: Unknown error.
            error_type: INTERNAL_ERROR
      type: object
      title: TrackingUpdateResponse
      description: 'Response schema for the tracking update webhook.

        This schema is used to return errors or success messages.'
    TrackingUpdateFuelData:
      properties:
        timestamp:
          type: string
          format: date-time
          title: Timestamp
          description: Timestamp at which tracking event occured
          examples:
          - '2024-01-15T10:30:00Z'
        fuel_level_percentage:
          anyOf:
          - type: number
          - type: 'null'
          title: Fuel Level Percentage
          examples:
          - 75
      type: object
      required:
      - timestamp
      title: TrackingUpdateFuelData
    SubcontractorMatchInput:
      properties:
        name:
          anyOf:
          - $ref: '#/components/schemas/FieldMatchInput'
          - type: 'null'
        generic_id:
          anyOf:
          - $ref: '#/components/schemas/FieldMatchInput'
          - type: 'null'
        integration_object_id:
          anyOf:
          - $ref: '#/components/schemas/FieldMatchInput'
          - type: 'null'
          description: 'The resource ID in the given context of your integration. '
      type: object
      title: SubcontractorMatchInput
      example:
        name:
          matches_any:
          - Acme Logistics
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
    FieldMatchInput:
      properties:
        matches_any:
          items:
            type: string
          type: array
          title: Matches Any
      type: object
      title: FieldMatchInput
    ErrorStatus:
      properties:
        error_type:
          $ref: '#/components/schemas/ErrorType'
        error_message:
          anyOf:
          - type: string
          - type: 'null'
          title: Error Message
          description: (User visible) error message
      type: object
      required:
      - error_type
      title: ErrorStatus
    ValidationErrorResponse:
      properties:
        message:
          description: Human-readable summary of the validation failure
          title: Message
          type: string
        errors:
          description: One entry per validation failure. Always present and non-empty — a single failure yields a one-item array, so integrators can handle one and many the same way.
          items:
            $ref: '#/components/schemas/ValidationErrorDetail'
          minItems: 1
          title: Errors
          type: array
      required:
      - message
      - errors
      title: ValidationErrorResponse
      type: object
    ContainerMatchInput:
      properties:
        name:
          anyOf:
          - $ref: '#/components/schemas/FieldMatchInput'
          - type: 'null'
        generic_id:
          anyOf:
          - $ref: '#/components/schemas/FieldMatchInput'
          - type: 'null'
        integration_object_id:
          anyOf:
          - $ref: '#/components/schemas/FieldMatchInput'
          - type: 'null'
          description: 'The resource ID in the given context of your integration. '
      type: object
      title: ContainerMatchInput
      example:
        generic_id:
          matches_any:
          - CONT-001
    TrackingUpdatePayload:
      properties:
        updates:
          items:
            $ref: '#/components/schemas/TrackingUpdateItem'
          type: array
          title: Updates
          description: List of tracking updates to process
      type: object
      title: TrackingUpdatePayload
    TrackingUpdateTemperatureData:
      properties:
        timestamp:
          type: string
          format: date-time
          title: Timestamp
          description: Timestamp at which tracking event occured
          examples:
          - '2024-01-15T10:30:00Z'
        temperatures:
          items:
            $ref: '#/components/schemas/TrackingUpdateTemperatureMeasurement'
          type: array
          title: Temperatures
        temperature_setpoints:
          items:
            $ref: '#/components/schemas/TrackingUpdateTemperatureMeasurement'
          type: array
          title: Temperature Setpoints
      type: object
      required:
      - timestamp
      title: TrackingUpdateTemperatureData
    TrackingUpdateWeightData:
      properties:
        timestamp:
          type: string
          format: date-time
          title: Timestamp
          description: Timestamp at which tracking event occured
          examples:
          - '2024-01-15T10:30:00Z'
        axle_weight:
          anyOf:
          - type: number
          - type: 'null'
          title: Axle Weight
          examples:
          - 8500
      type: object
      required:
      - timestamp
      title: TrackingUpdateWeightData
    ValidationErrorDetail:
      properties:
        message:
          description: Human-readable summary of this validation failure
          title: Message
          type: string
        field:
          anyOf:
          - type: string
          - type: 'null'
          default: null
          description: Name of the field that failed validation, if known
          title: Field
        path:
          anyOf:
          - type: string
          - type: 'null'
          default: null
          description: JSON path to the field within the request payload (e.g. '$.consignor.address.country')
          title: Path
        detail:
          anyOf:
          - type: string
          - type: object
          - type: 'null'
          default: null
          description: Additional structured context about the failure, if provided by the backend
          title: Detail
      required:
      - message
      title: ValidationErrorDetail
      type: object
    ErrorType:
      type: string
      enum:
      - USER_INPUT_ERROR
      - INTERNAL_ERROR
      - NOT_SUPPORTED
      title: ErrorType
    TrackingMatchInput:
      properties:
        resource:
          anyOf:
          - $ref: '#/components/schemas/TrackingResourceMatchInput'
          - type: 'null'
      type: object
      title: TrackingMatchInput
    TachographActivityEnum:
      type: string
      enum:
      - DRIVING
      - WORKING
      - BREAK
      - REST
      - WAITING
      - UNKNOWN
      title: TachographActivityEnum
    TrackingUpdateData:
      properties:
        position:
          anyOf:
          - $ref: '#/components/schemas/TrackingUpdatePositionData'
          - type: 'null'
        temperature:
          anyOf:
          - $ref: '#/components/schemas/TrackingUpdateTemperatureData'
          - type: 'null'
        tachograph:
          anyOf:
          - $ref: '#/components/schemas/TrackingUpdateTachographData'
          - type: 'null'
        fuel:
          anyOf:
          - $ref: '#/components/schemas/TrackingUpdateFuelData'
          - type: 'null'
        mileage:
          anyOf:
          - $ref: '#/components/schemas/TrackingUpdateMileageData'
          - type: 'null'
        weight:
          anyOf:
          - $ref: '#/components/schemas/TrackingUpdateWeightData'
          - type: 'null'
      type: object
      title: TrackingUpdateData
    TrackingUpdateTachographData:
      properties:
        timestamp:
          type: string
          format: date-time
          title: Timestamp
          description: Timestamp at which tracking event occured
          examples:
          - '2024-01-15T10:30:00Z'
        activity:
          anyOf:
          - $ref: '#/components/schemas/TachographActivityEnum'
          - type: 'null'
          description: Tachograph activity
          examples:
          - DRIVING
        driving_since:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Driving Since
          examples:
          - '2024-01-15T08:00:00Z'
        resting_since:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Resting Since
        on_break_since:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: On Break Since
        waiting_since:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Waiting Since
        next_break_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Next Break At
          examples:
          - '2024-01-15T12:30:00Z'
        next_rest_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Next Rest At
      type: object
      required:
      - timestamp
      title: TrackingUpdateTachographData
    TrackingResourceMatchInput:
      properties:
        driver:
          anyOf:
          - $ref: '#/components/schemas/DriverMatchInput'
          - type: 'null'
        vehicle:
          anyOf:
          - $ref: '#/components/schemas/VehicleMatchInput'
          - type: 'null'
        subcontractor:
          anyOf:
          - $ref: '#/components/schemas/SubcontractorMatchInput'
          - type: 'null'
        container:
          anyOf:
          - $ref: '#/components/schemas/ContainerMatchInput'
          - type: 'null'
      type: object
      title: TrackingResourceMatchInput
    TrackingMatchTarget:
      properties:
        matches_any:
          items:
            $ref: '#/components/schemas/TrackingMatchInput'
          type: array
          title: Matches Any
      type: object
      title: TrackingMatchTarget
    TrackingUpdatePositionData:
      properties:
        timestamp:
          type: string
          format: date-time
          title: Timestamp
          description: Timestamp at which tracking event occured
          examples:
          - '2024-01-15T10:30:00Z'
        latitude:
          type: number
          title: Latitude
          examples:
          - 51.0543
        longitude:
          type: number
          title: Longitude
          examples:
          - 3.7174
      type: object
      required:
      - timestamp
      - latitude
      - longitude
      title: TrackingUpdatePositionData
    TrackingUpdateItem:
      properties:
        tracking_match:
          $ref: '#/components/schemas/TrackingMatchTarget'
        tracking_update_data:
          items:
            $ref: '#/components/schemas/TrackingUpdateData'
          type: array
          title: Tracking Update Data
      type: object
      required:
      - tracking_match
      title: TrackingUpdateItem
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    TrackingUpdateTemperatureMeasurement:
      properties:
        sensor:
          type: string
          title: Sensor
          description: The sensor from which the temperature was measured
          examples:
          - sensor-1
        temperature:
          type: number
          title: Temperature
          description: The measured temperature value in degrees Celsius
          examples:
          - -18.5
      type: object
      required:
      - sensor
      - temperature
      title: TrackingUpdateTemperatureMeasurement
    TrackingUpdateMileageData:
      properties:
        timestamp:
          type: string
          format: date-time
          title: Timestamp
          description: Timestamp at which tracking event occured
          examples:
          - '2024-01-15T10:30:00Z'
        mileage_meter:
          anyOf:
          - type: number
          - type: 'null'
          title: Mileage Meter
          examples:
          - 150000
      type: object
      required:
      - timestamp
      title: TrackingUpdateMileageData
    DriverMatchInput:
      properties:
        name:
          anyOf:
          - $ref: '#/components/schemas/FieldMatchInput'
          - type: 'null'
        generic_id:
          anyOf:
          - $ref: '#/components/schemas/FieldMatchInput'
          - type: 'null'
        integration_object_id:
          anyOf:
          - $ref: '#/components/schemas/FieldMatchInput'
          - type: 'null'
          description: 'The resource ID in the given context of your integration. '
      type: object
      title: DriverMatchInput
      example:
        name:
          matches_any:
          - John Doe
  securitySchemes:
    oAuth2ClientCredentials:
      type: oauth2
      flows:
        clientCredentials:
          scopes: {}
          tokenUrl: /v1/auth/token
    BasicAuthWebhookCredentials:
      type: http
      scheme: basic
x-tagGroups:
- name: Use cases
  tags:
  - Use case / Accounting
  - Use case / Customer portal
  - Use case / Document import
  - Use case / E-invoicing
  - Use case / Fleet dispatch
  - Use case / Intermodal [partner]
  - Use case / Location booking
  - Use case / Master data sync
  - Use case / Order
  - Use case / Subcontractor dispatch
  - Use case / Tracking
  - Use case / Trip import
  - Use case / Visibility
- name: API
  tags:
  - API / Accounting
  - API / Authentication
  - API / Company
  - API / Document
  - API / Order
  - API / Resource
  - API / Task
  - API / Trip
- name: System
  tags:
  - System
- name: Webhooks
  tags:
  - Webhooks / Inbound
  - Webhooks / Outbound
- name: ''
  tags: []