> ## Documentation Index
> Fetch the complete documentation index at: https://docs.unitedpetroleum.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Create a trip

> Creates a trip for your organization. The vehicle (`vehicle_external_id`) must belong to the API key's org. `external_id` must be unique per org.



## OpenAPI

````yaml /openapi.json post /trips
openapi: 3.1.0
info:
  title: United Logistics API
  version: 0.1.0
  description: >-
    Industry-grade public API for fleet, fuel, and toll operations. Every
    endpoint is scoped to the organization owning the API key. Authentication:
    bearer API key (`ulk_<prefix>_<secret>`). Rate limit: 60 requests/minute/key
    by default (override per key via the dashboard).
  contact:
    name: United Logistics Engineering
    email: sfuentes@assetmg.tech
servers:
  - url: https://app.unitedlogistics.com.do/api/v1
    description: Production
  - url: http://localhost:3000/api/v1
    description: Local development
security:
  - ApiKeyAuth: []
paths:
  /trips:
    post:
      tags:
        - Trips
      summary: Create a trip
      description: >-
        Creates a trip for your organization. The vehicle
        (`vehicle_external_id`) must belong to the API key's org. `external_id`
        must be unique per org.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateTripRequest'
            examples:
              minimal:
                summary: Minimal trip
                value:
                  external_id: 9876543
                  vehicle_external_id: 12345
                  start_date: '2026-05-26T08:32:00.000Z'
              complete:
                summary: Complete trip with metrics
                value:
                  external_id: 9876543
                  vehicle_external_id: 12345
                  provider: karma
                  driver_external_id: 4421
                  device_id: GPS-DEV-001
                  vehicle_number: UL-021
                  start_date: '2026-05-26T08:32:00.000Z'
                  start_latitude: 18.4861
                  start_longitude: -69.9312
                  start_odometer_km: 124530.4
                  stop_date: '2026-05-26T10:14:00.000Z'
                  stop_latitude: 18.6792
                  stop_longitude: -68.4014
                  stop_odometer_km: 124612.8
                  duration_s: 6120
                  distance_km: 82.4
                  max_speed_kph: 104.2
                  driving_score: 87
                  eco_score: 72.4
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateTripResponse'
              example:
                data:
                  id: 482219
                  external_id: 9876543
                  provider: karma
                  org_id: d87f7281-ea19-45cd-b6fd-d8eb9e310da1
                  vehicle_external_id: 12345
                  driver_external_id: 4421
                  device_id: GPS-DEV-001
                  vehicle_number: UL-021
                  trip_active: 0
                  start_message_id: 91827361
                  start_date: '2026-05-26T08:32:00.000Z'
                  start_latitude: 18.4861
                  start_longitude: -69.9312
                  start_odometer_km: 124530.4
                  stop_message_id: 91827881
                  stop_date: '2026-05-26T10:14:00.000Z'
                  stop_latitude: 18.6792
                  stop_longitude: -68.4014
                  stop_odometer_km: 124612.8
                  duration_s: 6120
                  distance_km: 82.4
                  duration_night_s: 0
                  distance_night_km: 0
                  max_speed_kph: 104.2
                  driving_score: 87
                  eco_score: 72.4
                  fetch_timestamp: '2026-05-26T10:14:31.221Z'
                  created_at: '2026-05-26T10:14:31.221Z'
                  updated_at: '2026-05-26T10:14:31.221Z'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorObject'
              example:
                error:
                  code: bad_request
                  message: Invalid trip payload.
                  details:
                    fieldErrors:
                      start_date:
                        - start_date must be ISO 8601 datetime
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorObject'
              example:
                error:
                  code: unauthorized
                  message: API key missing or invalid.
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorObject'
              example:
                error:
                  code: forbidden
                  message: No tienes permisos para modificar viajes.
        '404':
          description: Vehicle not found in this organization
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorObject'
              example:
                error:
                  code: not_found
                  message: El vehículo especificado no existe en esta organización.
        '409':
          description: Trip with this external_id already exists
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorObject'
              example:
                error:
                  code: conflict
                  message: >-
                    Ya existe un viaje con ese external_id para esta
                    organización.
        '429':
          description: Rate limited
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorObject'
              example:
                error:
                  code: too_many_requests
                  message: Rate limit exceeded.
      security:
        - ApiKeyAuth: []
components:
  schemas:
    CreateTripRequest:
      type: object
      properties:
        external_id:
          type: integer
          exclusiveMinimum: 0
          description: Provider trip id (legacy `trip_id`). Unique per `org_id`.
          example: 9876543
        vehicle_external_id:
          type: integer
          exclusiveMinimum: 0
          description: Provider vehicle id (legacy `vehicle_id`).
          example: 12345
        provider:
          type: string
          minLength: 1
          maxLength: 64
          default: karma
          description: Telematics provider slug. Defaults to `karma`.
          example: karma
        driver_external_id:
          type:
            - integer
            - 'null'
          description: Provider driver id, if known.
          example: 4421
        device_id:
          type:
            - string
            - 'null'
          maxLength: 255
          example: GPS-DEV-001
        vehicle_number:
          type:
            - string
            - 'null'
          maxLength: 255
          description: Denormalized vehicle number at the time of the trip.
          example: UL-021
        trip_active:
          type:
            - integer
            - 'null'
        start_message_id:
          type:
            - integer
            - 'null'
        start_date:
          type: string
          format: date-time
          description: ISO 8601 timestamp when the trip started.
          example: '2026-05-26T08:32:00.000Z'
        start_latitude:
          type:
            - number
            - 'null'
          minimum: -90
          maximum: 90
        start_longitude:
          type:
            - number
            - 'null'
          minimum: -180
          maximum: 180
        start_odometer_km:
          type:
            - number
            - 'null'
          minimum: 0
        stop_message_id:
          type:
            - integer
            - 'null'
        stop_date:
          type:
            - string
            - 'null'
          format: date-time
        stop_latitude:
          type:
            - number
            - 'null'
          minimum: -90
          maximum: 90
        stop_longitude:
          type:
            - number
            - 'null'
          minimum: -180
          maximum: 180
        stop_odometer_km:
          type:
            - number
            - 'null'
          minimum: 0
        duration_s:
          type:
            - integer
            - 'null'
          minimum: 0
        distance_km:
          type:
            - number
            - 'null'
          minimum: 0
        duration_night_s:
          type:
            - integer
            - 'null'
          minimum: 0
        distance_night_km:
          type:
            - number
            - 'null'
          minimum: 0
        max_speed_kph:
          type:
            - number
            - 'null'
          minimum: 0
        driving_score:
          type:
            - integer
            - 'null'
          minimum: 0
          maximum: 100
        eco_score:
          type:
            - number
            - 'null'
          minimum: 0
          maximum: 100
      required:
        - external_id
        - vehicle_external_id
        - start_date
    CreateTripResponse:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/Trip'
      required:
        - data
    ErrorObject:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              example: unauthorized
            message:
              type: string
              example: Missing Authorization header.
            details: {}
          required:
            - code
            - message
      required:
        - error
    Trip:
      type: object
      properties:
        id:
          type: integer
          description: Internal numeric id. Stable per org.
          example: 482219
        external_id:
          type: integer
          description: Provider trip id (legacy `trip_id`). Stable per `org_id`.
          example: 9876543
        provider:
          $ref: '#/components/schemas/Provider'
        org_id:
          type: string
        vehicle_external_id:
          type: integer
          description: Provider vehicle id (legacy `vehicle_id`).
          example: 12345
        driver_external_id:
          type:
            - integer
            - 'null'
          description: Local driver id (legacy `driver_id`).
          example: 4421
        device_id:
          type:
            - string
            - 'null'
        vehicle_number:
          type:
            - string
            - 'null'
        trip_active:
          type:
            - integer
            - 'null'
        start_message_id:
          type:
            - integer
            - 'null'
        start_date:
          type:
            - string
            - 'null'
        start_latitude:
          type:
            - number
            - 'null'
        start_longitude:
          type:
            - number
            - 'null'
        start_odometer_km:
          type:
            - number
            - 'null'
        stop_message_id:
          type:
            - integer
            - 'null'
        stop_date:
          type:
            - string
            - 'null'
        stop_latitude:
          type:
            - number
            - 'null'
        stop_longitude:
          type:
            - number
            - 'null'
        stop_odometer_km:
          type:
            - number
            - 'null'
        duration_s:
          type:
            - integer
            - 'null'
        distance_km:
          type:
            - number
            - 'null'
        duration_night_s:
          type:
            - integer
            - 'null'
        distance_night_km:
          type:
            - number
            - 'null'
        max_speed_kph:
          type:
            - number
            - 'null'
        driving_score:
          type:
            - integer
            - 'null'
        eco_score:
          type:
            - number
            - 'null'
        fetch_timestamp:
          type:
            - string
            - 'null'
        created_at:
          type:
            - string
            - 'null'
        updated_at:
          type:
            - string
            - 'null'
      required:
        - id
        - external_id
        - provider
        - org_id
        - vehicle_external_id
        - driver_external_id
        - device_id
        - vehicle_number
        - trip_active
        - start_message_id
        - start_date
        - start_latitude
        - start_longitude
        - start_odometer_km
        - stop_message_id
        - stop_date
        - stop_latitude
        - stop_longitude
        - stop_odometer_km
        - duration_s
        - distance_km
        - duration_night_s
        - distance_night_km
        - max_speed_kph
        - driving_score
        - eco_score
        - fetch_timestamp
        - created_at
        - updated_at
    Provider:
      anyOf:
        - type: string
          enum:
            - karma
            - internal
        - type: string
          pattern: ^[a-z][a-z0-9][a-z0-9_-]{0,62}$
      description: >-
        Registered: karma (Karma sync), internal (created in the app). Custom
        integrators use a stable lowercase slug.
      example: karma
  securitySchemes:
    ApiKeyAuth:
      type: http
      scheme: bearer
      bearerFormat: ulk_<prefix>_<secret>
      description: >-
        Authorization: Bearer ulk_<prefix>_<secret>. Cree la clave en
        Configuración → API.

````