Skip to main content

​
Introduction

The Fuel Tracking (Tanqueos) API provides comprehensive endpoints for managing fuel consumption records across your fleet. This module supports two types of operations:
  • TANQUEO: Regular fuel refills with vehicle and driver information
  • ANTICIPO: Advance payments to fuel stations without specific vehicle assignment
All endpoints require authentication via JWT token.

​
Base URL

/api/tanqueos

​
Core Endpoints

​
CRUD Operations

MethodEndpointDescription
GET/api/tanqueosList all fuel records with pagination and filters
GET/api/tanqueos/:idGet a specific fuel record by ID
POST/api/tanqueosCreate a new fuel record
PUT/api/tanqueos/:idUpdate an existing fuel record
DELETE/api/tanqueos/:idDelete a fuel record
POST/api/tanqueos/importBulk import fuel records from file

​
Filter & Export

MethodEndpointDescription
GET/api/tanqueos/filter-optionsGet available filter options (conductors, plates, pumps, etc.)
GET/api/tanqueos/reportes/generalExport filtered records for reporting
GET/api/tanqueos/reportes/financieroGet financial report view of fuel records
GET/api/tanqueos/dashboard-linkGet dashboard link for user’s operational area

​
Dashboard Analytics

MethodEndpointDescription
GET/api/tanqueos/dashboard/kpisGet executive KPIs and metrics
GET/api/tanqueos/dashboard/saldos-bombasGet fuel station balance information
GET/api/tanqueos/dashboard/consumption-over-timeGet consumption trends over time
GET/api/tanqueos/dashboard/fuel-distributionGet fuel type distribution
GET/api/tanqueos/dashboard/by-areaGet consumption by operational area
GET/api/tanqueos/dashboard/top-vehiclesGet top 10 vehicles by consumption
GET/api/tanqueos/dashboard/vehicles-by-areaGet vehicles grouped by area
GET/api/tanqueos/dashboard/by-driverGet consumption by driver
GET/api/tanqueos/dashboard/by-pumpGet consumption by fuel station
GET/api/tanqueos/dashboard/alertsGet intelligent alerts for anomalies
GET/api/tanqueos/dashboard/alerts/:alertType/recordsGet detailed records for specific alert
GET/api/tanqueos/dashboard/detailed-tableGet detailed table with flags

​
Common Concepts

​
Authentication

All endpoints require authentication using JWT tokens. Include the token in the Authorization header: 
Authorization: Bearer <your-jwt-token>

​
Pagination

List endpoints support pagination with the following query parameters:
​
page
integer
default:1
Page number (1-based)
​
limit
integer
default:20
Number of records per page
Paginated responses include: 
{
  "data": [...],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 150,
    "totalPages": 8
  },
  "summary": {
    "total_galones": 1234.56,
    "total_valor": 15000000
  }
}

​
Filtering

Most endpoints support comprehensive filtering:
​
conductor
string
Filter by driver name (partial match, case-insensitive)
​
placa
string
Filter by vehicle plate (partial match, case-insensitive)
​
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): ACPM, GASOLINA, EXTRA
​
concepto
string
Filter by concept (exact match): OPERATIVO, ADMINISTRATIVO
​
tipo_operacion
string
Filter by operation type (exact match): TANQUEO, ANTICIPO
​
fecha_inicio
string
Filter by start date (format: YYYY-MM-DD)
​
fecha_fin
string
Filter by end date (format: YYYY-MM-DD)

​
Sorting

​
sort_by
string
default:"fecha"
Field to sort by (e.g., fecha, conductor, placa)
​
sort_order
string
Sort order: asc or desc. Default is descending by fecha if not specified

​
Data Models

​
Tanqueo

Core fuel record object: 
interface Tanqueo {
  id?: number;
  fecha: string;
  conductor_id?: number | null;
  placa_id?: number | null;
  tipo_combustible?: string | null;  // ACPM, GASOLINA, EXTRA
  valor_tanqueo?: number | null;
  cantidad_galones?: number | null;
  costo_por_galon?: number | null;
  valor_anticipo?: number | null;
  saldo_disponible?: number | null;
  bomba_id: number;
  area_operacion_id: number;
  concepto: string;  // OPERATIVO, ADMINISTRATIVO
  tipo_operacion: string;  // TANQUEO, ANTICIPO
  observacion?: string | null;
  horometro?: number | null;
  creado_por?: string;
  actualizado_por?: string;
  actualizado_en?: string;
}

​
TanqueoRelacion

Expanded fuel record with joined relation names: 
interface TanqueoRelacion {
  idx: number;
  id: number;
  fecha: string;
  conductor_id: number;
  conductor: string;  // Joined name
  placa_id: number;
  placa: string;  // Joined plate
  bomba_id: number;
  bomba: string;  // Joined pump name
  area_operacion_id: number;
  area_operacion: string;  // Joined area name
  tipo_combustible: string;
  valor_tanqueo: number;
  cantidad_galones: number;
  horometro: number | null;
  costo_por_galon: number | null;
  valor_anticipo: number | null;
  saldo_disponible: number;
  concepto: string;
  tipo_operacion: string;
  observacion: string | null;
}

​
Quick Start Examples

​
List All Fuel Records

curl -X GET 'https://api.example.com/api/tanqueos?page=1&limit=20' \
  -H 'Authorization: Bearer <token>'

​
Filter by Date Range and Area

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

​
Create a Fuel Record

curl -X POST 'https://api.example.com/api/tanqueos' \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "fecha": "2024-01-15",
    "conductor_id": 123,
    "placa_id": 456,
    "bomba_id": 789,
    "area_operacion_id": 1,
    "tipo_combustible": "ACPM",
    "valor_tanqueo": 150000,
    "cantidad_galones": 12.5,
    "concepto": "OPERATIVO",
    "tipo_operacion": "TANQUEO"
  }'

​
Get Dashboard KPIs

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

​
Error Handling

All endpoints return standard HTTP status codes:
  • 200: Success
  • 201: Created (for POST requests)
  • 400: Bad request (validation errors)
  • 401: Unauthorized (missing or invalid token)
  • 404: Not found
  • 500: Internal server error
Error responses follow this format: 
{
  "error": "Error message description"
}

​
Next Steps

Build docs developers (and LLMs) love

Get started for freeTalk to us