> ## 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.

# Bulk import trips

> Imports a single trip or an array of up to 1000 trips for your organization. Idempotent on `(external_id, org_id)`: trips that already exist are updated, the rest are inserted — so you can safely re-send the same batch. Every `vehicle_external_id` must belong to the API key's org. Duplicate `external_id`s within one request are collapsed (last one wins).



## OpenAPI

````yaml /openapi.json post /trips/bulk
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/bulk:
    post:
      tags:
        - Trips
      summary: Bulk import trips
      description: >-
        Imports a single trip or an array of up to 1000 trips for your
        organization. Idempotent on `(external_id, org_id)`: trips that already
        exist are updated, the rest are inserted — so you can safely re-send the
        same batch. Every `vehicle_external_id` must belong to the API key's
        org. Duplicate `external_id`s within one request are collapsed (last one
        wins).
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TripBulkImportRequest'
            examples:
              bulk:
                summary: Bulk array
                value:
                  - external_id: 9876543
                    vehicle_external_id: 12345
                    start_date: '2026-05-26T08:32:00.000Z'
                    stop_date: '2026-05-26T10:14:00.000Z'
                    distance_km: 82.4
                    max_speed_kph: 104.2
                  - external_id: 9876544
                    vehicle_external_id: 12345
                    start_date: '2026-05-26T12:05:00.000Z'
                    stop_date: '2026-05-26T12:48:00.000Z'
                    distance_km: 31.7
              single:
                summary: Single trip
                value:
                  external_id: 9876543
                  vehicle_external_id: 12345
                  start_date: '2026-05-26T08:32:00.000Z'
      responses:
        '200':
          description: Imported
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TripBulkImportResponse'
              example:
                inserted: 18
                updated: 2
                ids:
                  - 482219
                  - 482220
                  - 482221
        '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: A referenced vehicle does not exist 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.
        '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:
    TripBulkImportRequest:
      anyOf:
        - 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
        - type: array
          items:
            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
          minItems: 1
          maxItems: 1000
    TripBulkImportResponse:
      type: object
      properties:
        inserted:
          type: integer
          description: Number of trips newly created.
          example: 18
        updated:
          type: integer
          description: Number of existing trips updated.
          example: 2
        ids:
          type: array
          items:
            type: integer
          description: Internal ids of every imported (inserted or updated) trip.
      required:
        - inserted
        - updated
        - ids
    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
  securitySchemes:
    ApiKeyAuth:
      type: http
      scheme: bearer
      bearerFormat: ulk_<prefix>_<secret>
      description: >-
        Authorization: Bearer ulk_<prefix>_<secret>. Cree la clave en
        Configuración → API.

````