Skip to main content

​
Endpoint

POST /api/tanqueos
Create a new fuel tracking record. Supports two types of operations:
  • TANQUEO: Regular fuel refill with vehicle and driver information
  • ANTICIPO: Advance payment to fuel station without specific vehicle assignment

​
Authentication

Requires JWT authentication token. The authenticated user’s ID is automatically recorded as creado_por.

​
Request Body

​
Common Fields (Required for Both Types)

​
fecha
string
required
Transaction date in format YYYY-MM-DD
​
bomba_id
number
required
Fuel station identifier (must exist in areas_bombas table)
​
area_operacion_id
number
required
Operational area identifier (must exist in areas_operacion table)
​
concepto
string
default:"OPERATIVO"
Concept classification:
  • OPERATIVO - Operational use (default)
  • ADMINISTRATIVO - Administrative use
​
tipo_operacion
string
default:"TANQUEO"
Operation type:
  • TANQUEO - Regular fuel refill (default)
  • ANTICIPO - Advance payment
​
observacion
string
Optional notes or observations
​
saldo_disponible
number
Available balance at fuel station after this transaction

​
TANQUEO-Specific Fields

Required when tipo_operacion = "TANQUEO":
​
conductor_id
number
required
Driver identifier (must exist in areas_conductores table)
​
placa_id
number
required
Vehicle plate identifier (must exist in areas_placas table)
​
tipo_combustible
string
default:"ACPM"
Fuel type:
  • ACPM - Diesel (default)
  • GASOLINA - Regular gasoline
  • EXTRA - Premium gasoline
​
valor_tanqueo
number
required
Total fuel cost in COP (Colombian Pesos)
​
cantidad_galones
number
required
Quantity of fuel in gallons
​
horometro
number
Hourmeter reading at time of refueling (recommended for tracking)

​
ANTICIPO-Specific Fields

Required when tipo_operacion = "ANTICIPO":
​
valor_anticipo
number
required
Advance payment amount in COP

​
Response

Returns the created fuel record with all fields including auto-generated values.
​
id
number
Unique identifier for the created record
​
fecha
string
Transaction date
​
conductor_id
number | null
Driver identifier (null for ANTICIPO)
​
placa_id
number | null
Vehicle plate identifier (null for ANTICIPO)
​
bomba_id
number
Fuel station identifier
​
area_operacion_id
number
Operational area identifier
​
tipo_combustible
string | null
Fuel type (null for ANTICIPO)
​
valor_tanqueo
number | null
Total fuel cost (null for ANTICIPO)
​
cantidad_galones
number | null
Fuel quantity in gallons (null for ANTICIPO)
​
costo_por_galon
number | null
Automatically calculated cost per gallon (valor_tanqueo / cantidad_galones)
​
horometro
number | null
Hourmeter reading
​
valor_anticipo
number | null
Advance payment amount (null for TANQUEO)
​
saldo_disponible
number | null
Available balance at fuel station
​
concepto
string
Concept: OPERATIVO or ADMINISTRATIVO
​
tipo_operacion
string
Operation type: TANQUEO or ANTICIPO
​
observacion
string | null
Observations or notes
​
creado_por
string
User ID who created the record

​
Examples

​
Create Regular Fuel Refill (TANQUEO)

curl -X POST 'https://api.example.com/api/tanqueos' \
  -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...' \
  -H 'Content-Type: application/json' \
  -d '{
    "fecha": "2024-03-15",
    "conductor_id": 42,
    "placa_id": 156,
    "bomba_id": 7,
    "area_operacion_id": 2,
    "tipo_combustible": "ACPM",
    "valor_tanqueo": 150000,
    "cantidad_galones": 12.5,
    "horometro": 1250.5,
    "saldo_disponible": 2500000,
    "concepto": "OPERATIVO",
    "tipo_operacion": "TANQUEO",
    "observacion": "Tanqueo regular de ruta matutina"
  }'

​
Create Advance Payment (ANTICIPO)

curl -X POST 'https://api.example.com/api/tanqueos' \
  -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...' \
  -H 'Content-Type: application/json' \
  -d '{
    "fecha": "2024-03-15",
    "bomba_id": 7,
    "area_operacion_id": 2,
    "valor_anticipo": 500000,
    "saldo_disponible": 3000000,
    "concepto": "OPERATIVO",
    "tipo_operacion": "ANTICIPO",
    "observacion": "Anticipo mensual para Estación Central"
  }'

​
Create with Minimal Fields

curl -X POST 'https://api.example.com/api/tanqueos' \
  -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...' \
  -H 'Content-Type: application/json' \
  -d '{
    "fecha": "2024-03-15",
    "conductor_id": 42,
    "placa_id": 156,
    "bomba_id": 7,
    "area_operacion_id": 2,
    "valor_tanqueo": 80000,
    "cantidad_galones": 6.5
  }'

​
Success Response Example

Status Code: 201 Created 
{
  "id": 4523,
  "fecha": "2024-03-15",
  "conductor_id": 42,
  "placa_id": 156,
  "bomba_id": 7,
  "area_operacion_id": 2,
  "tipo_combustible": "ACPM",
  "valor_tanqueo": 150000,
  "cantidad_galones": 12.5,
  "costo_por_galon": 12000,
  "horometro": 1250.5,
  "valor_anticipo": null,
  "saldo_disponible": 2500000,
  "concepto": "OPERATIVO",
  "tipo_operacion": "TANQUEO",
  "observacion": "Tanqueo regular de ruta matutina",
  "creado_por": "550e8400-e29b-41d4-a716-446655440000",
  "actualizado_por": null,
  "actualizado_en": null
}

​
Validation Rules

​
Automatic Calculations

  • costo_por_galon: Automatically calculated as valor_tanqueo / cantidad_galones when both values are provided and cantidad_galones > 0
  • creado_por: Automatically set to the authenticated user’s ID from the JWT token

​
Type-Specific Validation

For TANQUEO operations:
  • conductor_id, placa_id, tipo_combustible, valor_tanqueo, and cantidad_galones are required
  • valor_anticipo must be null or omitted
For ANTICIPO operations:
  • valor_anticipo is required
  • Vehicle and driver fields (conductor_id, placa_id, tipo_combustible, valor_tanqueo, cantidad_galones) must be null or omitted

​
Date Format

  • fecha must be in ISO format: YYYY-MM-DD
  • Future dates are allowed (for scheduled transactions)

​
Numeric Fields

  • All monetary values should be in Colombian Pesos (COP)
  • cantidad_galones accepts decimal values (e.g., 12.5)
  • horometro accepts decimal values for precise tracking

​
Error Responses

​
400 Bad Request - Missing Required Fields

{
  "error": "Missing required field: conductor_id"
}

​
400 Bad Request - Invalid Foreign Key

{
  "error": "insert or update on table \"tanqueo\" violates foreign key constraint \"tanqueo_bomba_id_fkey\""
}

​
400 Bad Request - Invalid Data Type

{
  "error": "invalid input syntax for type numeric: \"abc\""
}

​
401 Unauthorized

{
  "error": "Authentication required"
}

​
500 Internal Server Error

{
  "error": "Error en el servidor"
}

​
Implementation Notes

  • The endpoint writes to the tanqueo table (not the tanqueo_relaciones view)
  • Foreign key constraints ensure referential integrity with related tables
  • The authenticated user’s ID from the JWT token is automatically recorded in creado_por
  • Cost per gallon is automatically calculated server-side to ensure consistency
  • Default values are applied for optional fields (concepto defaults to “OPERATIVO”, tipo_combustible defaults to “ACPM”)

Build docs developers (and LLMs) love

Get started for freeTalk to us