> ## 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 fuel entry

> Creates a fuel entry for your organization. When `vehicle_external_id` and `transaction_date` are provided, the entry is automatically matched against the nearest trip and GPS message (±30 min). `odometer_reading` drives the efficiency trigger.



## OpenAPI

````yaml /openapi.json post /fuel/entries
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:
  /fuel/entries:
    post:
      tags:
        - Fuel
      summary: Create a fuel entry
      description: >-
        Creates a fuel entry for your organization. When `vehicle_external_id`
        and `transaction_date` are provided, the entry is automatically matched
        against the nearest trip and GPS message (±30 min). `odometer_reading`
        drives the efficiency trigger.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateFuelEntryRequest'
            examples:
              minimal:
                summary: Minimal entry
                value:
                  vehicle_number: L18N / L534991
                  product_name: Diesel Regular
                  product_type: Regular
                  gallons: 60.008
                  price_per_gallon: 224.8
              complete:
                summary: Complete entry with telemetry hints
                value:
                  vehicle_external_id: 16056
                  vehicle_number: L18N / L534991
                  vehicle_name: L18N
                  name: Juan Pérez
                  product_id: f788c39d-02c8-4bd6-aa1a-fa2af011b5a3
                  product_name: Diesel Regular
                  product_type: Regular
                  vendor_id: 2f81f423-db0c-46d8-923e-c177fa78a54c
                  gallons: 60.008
                  price_per_gallon: 224.8
                  odometer_reading: 10997
                  transaction_date: '2026-02-26T03:15:47.000Z'
                  source: API
                  reference_id: '300030586'
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateFuelEntryResponse'
              example:
                data:
                  id: 589c258d-4736-4b6f-876f-87835992191e
                  org_id: d87f7281-ea19-45cd-b6fd-d8eb9e310da1
                  transaction_date: '2026-02-26T03:15:47.000Z'
                  transaction_id: TXN-9921
                  notes: null
                  vehicle_external_id: 16056
                  vehicle_number: L18N / L534991
                  vehicle_name: L18N
                  driver_external_id: null
                  driver_key: null
                  name: Juan Pérez
                  product_id: f788c39d-02c8-4bd6-aa1a-fa2af011b5a3
                  product_name: Diesel Regular
                  product_type: Regular
                  vendor_id: 2f81f423-db0c-46d8-923e-c177fa78a54c
                  vendor_name: Estación El Higuero - United Petroleum
                  vendor_address: Santo Domingo Norte, DO
                  gallons: 60.008
                  price_per_gallon: 224.8
                  total_cost: 13489.8
                  odometer_reading: 10997
                  previous_odometer_reading: 10120
                  distance_traveled: 877
                  fuel_efficiency: 14.61
                  trip_external_id: null
                  matched_message_id: 6213486243
                  gps_odometer_reading: 10997.05
                  karma_driver_id: null
                  source: API
                  reference_id: '300030586'
                  created_by: null
                  created_at: '2026-02-26T15:30:03.048Z'
                  updated_at: '2026-02-26T15:30:03.048Z'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorObject'
              example:
                error:
                  code: bad_request
                  message: Invalid fuel entry payload.
                  details:
                    fieldErrors:
                      gallons:
                        - gallons must be greater than 0
        '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: 'API key is missing required scope: fuel_entries:write.'
        '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.
        '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:
    CreateFuelEntryRequest:
      type: object
      properties:
        vehicle_external_id:
          type:
            - integer
            - 'null'
          description: >-
            Provider vehicle id (legacy `vehicle_id`). Enables trip/GPS
            matching.
          example: 16056
        vehicle_number:
          type: string
          minLength: 1
          maxLength: 255
          description: Denormalized vehicle number/plate at the time of the refuel.
          example: L18N / L534991
        vehicle_name:
          type:
            - string
            - 'null'
          maxLength: 255
        driver_external_id:
          type:
            - integer
            - 'null'
        driver_key:
          type:
            - string
            - 'null'
          maxLength: 255
        name:
          type:
            - string
            - 'null'
          maxLength: 255
          description: Driver name (denormalized). Defaults to `Desconocido`.
          example: Juan Pérez
        product_id:
          type:
            - string
            - 'null'
          format: uuid
        product_name:
          type: string
          minLength: 1
          maxLength: 255
          example: Diesel Regular
        product_type:
          type: string
          minLength: 1
          maxLength: 255
          example: Regular
        vendor_id:
          type:
            - string
            - 'null'
          format: uuid
        vendor_name:
          type:
            - string
            - 'null'
          maxLength: 255
        vendor_address:
          type:
            - string
            - 'null'
          maxLength: 500
        gallons:
          type: number
          exclusiveMinimum: 0
          example: 60.008
        total_cost:
          type: number
          minimum: 0
          description: Transaction total; price_per_gallon is inferred when provided.
          example: 13489.8
        price_per_gallon:
          type: number
          minimum: 0
          example: 224.8
        odometer_reading:
          type: number
          minimum: 0
          example: 10997
        transaction_date:
          type:
            - string
            - 'null'
          format: date-time
          example: '2026-02-26T03:15:47.000Z'
        transaction_id:
          type:
            - string
            - 'null'
          maxLength: 255
        notes:
          type:
            - string
            - 'null'
          maxLength: 2000
        source:
          type:
            - string
            - 'null'
          enum:
            - API
            - manual
            - import
          description: >-
            Origin of the entry. `manual` for UI capture, `import` for bulk
            CSV/Excel, `API` for integrations. Legacy `ERM` is accepted and
            stored as `manual`.
          example: API
        reference_id:
          type:
            - string
            - 'null'
          maxLength: 255
        trip_external_id:
          type:
            - integer
            - 'null'
        matched_message_id:
          type:
            - integer
            - 'null'
        gps_odometer_reading:
          type:
            - number
            - 'null'
          minimum: 0
        karma_driver_id:
          type:
            - integer
            - 'null'
      required:
        - vehicle_number
        - product_name
        - product_type
        - gallons
    CreateFuelEntryResponse:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/FuelEntry'
      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
    FuelEntry:
      type: object
      properties:
        id:
          type: string
          format: uuid
        org_id:
          type: string
          format: uuid
        transaction_date:
          type:
            - string
            - 'null'
        transaction_id:
          type:
            - string
            - 'null'
        notes:
          type:
            - string
            - 'null'
        vehicle_external_id:
          type:
            - integer
            - 'null'
        vehicle_number:
          type:
            - string
            - 'null'
        vehicle_name:
          type:
            - string
            - 'null'
        driver_external_id:
          type:
            - integer
            - 'null'
        driver_key:
          type:
            - string
            - 'null'
        name:
          type:
            - string
            - 'null'
        product_id:
          type:
            - string
            - 'null'
          format: uuid
        product_name:
          type:
            - string
            - 'null'
        product_type:
          type:
            - string
            - 'null'
        vendor_id:
          type:
            - string
            - 'null'
          format: uuid
        vendor_name:
          type:
            - string
            - 'null'
        vendor_address:
          type:
            - string
            - 'null'
        gallons:
          type:
            - number
            - 'null'
        price_per_gallon:
          type:
            - number
            - 'null'
        total_cost:
          type:
            - number
            - 'null'
        odometer_reading:
          type:
            - number
            - 'null'
        previous_odometer_reading:
          type:
            - number
            - 'null'
        distance_traveled:
          type:
            - number
            - 'null'
        fuel_efficiency:
          type:
            - number
            - 'null'
        trip_external_id:
          type:
            - integer
            - 'null'
        matched_message_id:
          type:
            - integer
            - 'null'
        gps_odometer_reading:
          type:
            - number
            - 'null'
        karma_driver_id:
          type:
            - integer
            - 'null'
        source:
          type:
            - string
            - 'null'
        reference_id:
          type:
            - string
            - 'null'
        created_by:
          type:
            - string
            - 'null'
        created_at:
          type: string
        updated_at:
          type: string
      required:
        - id
        - org_id
        - transaction_date
        - transaction_id
        - notes
        - vehicle_external_id
        - vehicle_number
        - vehicle_name
        - driver_external_id
        - driver_key
        - name
        - product_id
        - product_name
        - product_type
        - vendor_id
        - vendor_name
        - vendor_address
        - gallons
        - price_per_gallon
        - total_cost
        - odometer_reading
        - previous_odometer_reading
        - distance_traveled
        - fuel_efficiency
        - trip_external_id
        - matched_message_id
        - gps_odometer_reading
        - karma_driver_id
        - source
        - reference_id
        - created_by
        - created_at
        - updated_at
  securitySchemes:
    ApiKeyAuth:
      type: http
      scheme: bearer
      bearerFormat: ulk_<prefix>_<secret>
      description: >-
        Authorization: Bearer ulk_<prefix>_<secret>. Cree la clave en
        Configuración → API.

````