Skip to main content

​
Endpoint

GET /api/tanqueos
Retrieve a paginated list of fuel tracking records with comprehensive filtering options. Returns both TANQUEO (fuel refills) and ANTICIPO (advance payments) records from the tanqueo_relaciones view, which includes joined relation names.

​
Authentication

Requires JWT authentication token in the Authorization header.

​
Query Parameters

​
Pagination

​
page
integer
default:1
Page number (1-based indexing)
​
limit
integer
default:20
Number of records per page (max recommended: 100)

​
Filters

​
conductor
string
Filter by driver name (partial match, case-insensitive). Example: Juan matches “Juan Pérez”
​
placa
string
Filter by vehicle plate (partial match, case-insensitive). Example: ABC matches “ABC-123”
​
bomba
string
Filter by fuel station name (partial match, case-insensitive)
​
area_operacion
string
Filter by operational area name (partial match, case-insensitive)
​
tipo_combustible
string
Filter by fuel type (exact match). Valid values:
  • ACPM - Diesel
  • GASOLINA - Gasoline
  • EXTRA - Premium gasoline
​
concepto
string
Filter by concept (exact match). Valid values:
  • OPERATIVO - Operational use
  • ADMINISTRATIVO - Administrative use
​
tipo_operacion
string
Filter by operation type (exact match). Valid values:
  • TANQUEO - Fuel refill
  • ANTICIPO - Advance payment
​
fecha_inicio
string
Filter records from this date onwards (inclusive). Format: YYYY-MM-DD
​
fecha_fin
string
Filter records up to this date (inclusive). Format: YYYY-MM-DD

​
Sorting

​
sort_by
string
default:"fecha"
Field to sort by. Common values: fecha, conductor, placa, valor_tanqueo, cantidad_galones
​
sort_order
string
Sort order:
  • asc - Ascending
  • desc - Descending
If not specified, defaults to descending by fecha (most recent first)

​
Response

​
data
TanqueoRelacion[]
Array of fuel records with joined relation names
​
id
number
Unique fuel record identifier
​
idx
number
Index number from the database view
​
fecha
string
Date of the fuel transaction (YYYY-MM-DD)
​
conductor_id
number
Driver’s unique identifier
​
conductor
string
Driver’s full name
​
placa_id
number
Vehicle plate’s unique identifier
​
placa
string
Vehicle license plate
​
bomba_id
number
Fuel station’s unique identifier
​
bomba
string
Fuel station name
​
area_operacion_id
number
Operational area’s unique identifier
​
area_operacion
string
Operational area name
​
tipo_combustible
string
Fuel type: ACPM, GASOLINA, or EXTRA
​
valor_tanqueo
number
Total fuel cost in COP (Colombian Pesos)
​
cantidad_galones
number
Quantity of fuel in gallons
​
costo_por_galon
number | null
Cost per gallon (calculated: valor_tanqueo / cantidad_galones)
​
horometro
number | null
Hourmeter reading at time of refueling
​
valor_anticipo
number | null
Advance payment amount (only for ANTICIPO type)
​
saldo_disponible
number
Available balance at fuel station after transaction
​
concepto
string
Concept: OPERATIVO or ADMINISTRATIVO
​
tipo_operacion
string
Operation type: TANQUEO or ANTICIPO
​
observacion
string | null
Additional observations or notes
​
pagination
object
Pagination metadata
​
page
number
Current page number
​
limit
number
Records per page
​
total
number
Total number of records matching the filters
​
totalPages
number
Total number of pages
​
summary
object
Summary totals for all records matching filters (not just current page)
​
total_galones
number
Total gallons across all matching records (rounded to 2 decimals)
​
total_valor
number
Total value in COP across all matching records (rounded to 2 decimals)

​
Examples

​
List First Page (Default)

curl -X GET 'https://api.example.com/api/tanqueos' \
  -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...'

​
Filter by Date Range

curl -X GET 'https://api.example.com/api/tanqueos?fecha_inicio=2024-01-01&fecha_fin=2024-01-31' \
  -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...'

​
Filter by Driver and Fuel Type

curl -X GET 'https://api.example.com/api/tanqueos?conductor=Juan&tipo_combustible=ACPM' \
  -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...'

​
Paginate with Custom Page Size

curl -X GET 'https://api.example.com/api/tanqueos?page=2&limit=50' \
  -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...'

​
Sort by Amount (Descending)

curl -X GET 'https://api.example.com/api/tanqueos?sort_by=valor_tanqueo&sort_order=desc' \
  -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...'

​
Complex Filter Example

curl -X GET 'https://api.example.com/api/tanqueos?area_operacion=NORTE&tipo_combustible=GASOLINA&fecha_inicio=2024-01-01&fecha_fin=2024-03-31&page=1&limit=100' \
  -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...'

​
Response Example

{
  "data": [
    {
      "idx": 1,
      "id": 4523,
      "fecha": "2024-03-15",
      "conductor_id": 42,
      "conductor": "Juan Carlos Pérez",
      "placa_id": 156,
      "placa": "ABC-123",
      "bomba_id": 7,
      "bomba": "Estación Central",
      "area_operacion_id": 2,
      "area_operacion": "NORTE",
      "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"
    },
    {
      "idx": 2,
      "id": 4522,
      "fecha": "2024-03-15",
      "conductor_id": 38,
      "conductor": "María González",
      "placa_id": 201,
      "placa": "DEF-456",
      "bomba_id": 7,
      "bomba": "Estación Central",
      "area_operacion_id": 2,
      "area_operacion": "NORTE",
      "tipo_combustible": "GASOLINA",
      "valor_tanqueo": 95000,
      "cantidad_galones": 7.3,
      "costo_por_galon": 13013.7,
      "horometro": null,
      "valor_anticipo": null,
      "saldo_disponible": 2650000,
      "concepto": "OPERATIVO",
      "tipo_operacion": "TANQUEO",
      "observacion": null
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 156,
    "totalPages": 8
  },
  "summary": {
    "total_galones": 1847.25,
    "total_valor": 22450000
  }
}

​
Notes

  • The endpoint queries the tanqueo_relaciones database view which automatically joins related tables to provide human-readable names
  • Summary totals are calculated across ALL records matching the filters, not just the current page
  • Default sorting is by fecha descending (most recent first) and then by id descending
  • Partial string matches (conductor, placa, bomba, area_operacion) are case-insensitive and use PostgreSQL’s ILIKE
  • The costo_por_galon field is automatically calculated as valor_tanqueo / cantidad_galones when creating records
  • Records with tipo_operacion = 'ANTICIPO' will have null values for vehicle and driver fields

​
Get Filter Options

To get available values for filters, use the Filter Options endpoint: 
GET /api/tanqueos/filter-options
This returns: 
{
  "conductores": ["Carlos López", "Juan Pérez", ...],
  "placas": ["ABC-123", "DEF-456", ...],
  "bombas": ["Estación Central", "Bomba Norte", ...],
  "areas_operacion": ["NORTE", "SUR", "CENTRO"],
  "tipos_combustible": ["ACPM", "GASOLINA", "EXTRA"],
  "conceptos": ["OPERATIVO", "ADMINISTRATIVO"],
  "tipos_operacion": ["TANQUEO", "ANTICIPO"]
}
The filter options respect Row Level Security (RLS) and only show values available to the authenticated user.

​
Error Responses

​
400 Bad Request

{
  "error": "Invalid date format for fecha_inicio"
}

​
401 Unauthorized

{
  "error": "Authentication required"
}

​
500 Internal Server Error

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

Build docs developers (and LLMs) love

Get started for freeTalk to us