Dashboard Analytics - Tanqueo Backend API

Overview

The dashboard analytics endpoints provide executive insights, consumption trends, distribution analysis, and intelligent alerts for fuel tracking operations. All endpoints support filtering by date range, operational area, fuel type, and other parameters.

Common Filter Parameters

Most dashboard endpoints support these query parameters:

fecha_inicio

string

Start date for filtering (format: YYYY-MM-DD)

fecha_fin

string

End date for filtering (format: YYYY-MM-DD)

area_operacion

string

Filter by operational area name (partial match)

tipo_combustible

string

Filter by fuel type: ACPM, GASOLINA, or EXTRA

conductor

string

Filter by driver name (partial match)

placa

string

Filter by vehicle plate (partial match)

bomba

string

Filter by fuel station name (partial match)

Get Executive KPIs

GET /api/tanqueos/dashboard/kpis

Retrieve comprehensive executive-level KPIs including totals, averages, and breakdowns by fuel type and area.

Response

global

object

Global metrics across all filtered records

totalGalones

number

Total gallons consumed

totalValor

number

Total cost in COP

totalSaldo

number

Total available balance across all fuel stations

numTanqueos

number

Total number of fuel records

promedioGalonesPorTanqueo

number

Average gallons per refuel

costoPromedioGalon

number

Average cost per gallon

vehiculosActivos

number

Number of unique vehicles that refueled

conductoresActivos

number

Number of unique drivers

porcentajeSinHorometro

number

Percentage of records missing hourmeter reading

porCombustible

object

Breakdown by fuel type (keys: ACPM, GASOLINA, EXTRA, etc.)Each fuel type contains:

galones: Total gallons
valor: Total cost
cantidad: Number of records
costoPromedioGalon: Average cost per gallon for this fuel type

costoPorArea

object

Breakdown by operational area and fuel type (only ACPM and GASOLINA)Each area contains fuel types with:

galones: Total gallons
valor: Total cost
costoPromedioGalon: Average cost per gallon

consumoDiario

object

Daily consumption breakdown (keys are dates in YYYY-MM-DD format)Each date contains:

galones: Gallons consumed that day
valor: Total cost that day

Example

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>'

Get Fuel Station Balances

GET /api/tanqueos/dashboard/saldos-bombas

Retrieve current balance information for all active fuel stations, with statistics on negative and critical balances. Respects Row Level Security (RLS).

Response

bombas

array

Array of fuel station balance information

bomba

string

Fuel station name

area_operacion

string

Operational area

saldo_disponible

number

Current available balance in COP

actividad

string

Status: ACTIVADA or DESACTIVADA

stats

object

Summary statistics

totalBombas

number

Total number of active fuel stations

totalSaldo

number

Sum of all balances

numNegativos

number

Number of stations with negative balance

numCriticos

number

Number of stations with balance < -500,000 COP

numBajos

number

Number of stations with balance between -500,000 and 0

numPositivos

number

Number of stations with positive balance

Example

curl -X GET 'https://api.example.com/api/tanqueos/dashboard/saldos-bombas' \
  -H 'Authorization: Bearer <token>'

Get Consumption Over Time

GET /api/tanqueos/dashboard/consumption-over-time

Retrieve fuel consumption trends grouped by date and fuel type.

Response

Array of consumption data points:

fecha

string

Date in YYYY-MM-DD format

tipo_combustible

string

Fuel type

galones

number

Total gallons consumed

valor

number

Total cost in COP

Example

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

Get Fuel Distribution

GET /api/tanqueos/dashboard/fuel-distribution

Get fuel consumption distribution by fuel type with percentages.

Response

Array of fuel type distributions:

tipo_combustible

string

Fuel type name

total_galones

number

Total gallons for this fuel type

total_valor

number

Total cost for this fuel type

porcentaje_galones

number

Percentage of total gallons

porcentaje_valor

number

Percentage of total cost

Example

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

Get Consumption by Area

GET /api/tanqueos/dashboard/by-area

Get fuel consumption grouped by operational area and fuel type.

Response

Array of area consumption data:

area_operacion

string

Operational area name

tipo_combustible

string

Fuel type

galones

number

Total gallons

valor

number

Total cost

Get Top Vehicles

GET /api/tanqueos/dashboard/top-vehicles

Get the top 10 vehicles by fuel consumption.

Response

Array of top vehicles (limited to 10):

placa

string

Vehicle plate

tipo_combustible

string

Fuel type

total_galones

number

Total gallons consumed

total_valor

number

Total cost

Get Vehicles by Area

GET /api/tanqueos/dashboard/vehicles-by-area

Get vehicles grouped by operational area with detailed consumption breakdown. Defaults to last 2 months if no date filter provided.

Response

Array of vehicle records:

placa

string

Vehicle plate

conductor

string

Most recent driver name

ultimoTanqueo

string

Date of most recent refuel

totalGalones

number

Total gallons across all areas

totalValor

number

Total cost across all areas

numTanqueos

number

Total number of refuels

numAreas

number

Number of different operational areas

areas

array

Breakdown by area, sorted by most recent

area_operacion

string

Area name

ultimaFecha

string

Last refuel date in this area

galones

number

Gallons in this area

valor

number

Cost in this area

numTanqueos

number

Number of refuels in this area

Get Consumption by Driver

GET /api/tanqueos/dashboard/by-driver

Get fuel consumption grouped by driver and fuel type, sorted by consumption.

Response

Array of driver consumption records:

conductor

string

Driver name

tipo_combustible

string

Fuel type

total_galones

number

Total gallons

total_valor

number

Total cost

num_tanqueos

number

Number of refuels

Get Consumption by Pump

GET /api/tanqueos/dashboard/by-pump

Get fuel consumption grouped by fuel station and fuel type.

Response

Array of pump consumption records:

bomba

string

Fuel station name

tipo_combustible

string

Fuel type

total_galones

number

Total gallons

total_valor

number

Total cost

Get Intelligent Alerts

GET /api/tanqueos/dashboard/alerts

Get intelligent alerts for anomalies and issues in fuel tracking data.

Alert Types

SIN_HOROMETRO: Records missing hourmeter readings
COSTO_ANORMAL: Cost per gallon outside expected range
SALDO_CRITICO: Balance below -500,000 COP
CONSUMO_ATIPICO: Consumption > 2 standard deviations above mean

Fuel Price Thresholds

ACPM: 9,000 - 15,000 COP/gallon
GASOLINA: 10,000 - 16,000 COP/gallon
EXTRA: 11,000 - 17,000 COP/gallon

Response

Array of alert objects:

tipo_alerta

string

Alert type code

mensaje

string

Human-readable alert message

cantidad

number

Number of records triggering this alert

severidad

string

Alert severity: warning or error

Example

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

Response Example

[
  {
    "tipo_alerta": "SIN_HOROMETRO",
    "mensaje": "15 tanqueo(s) sin registro de horómetro",
    "cantidad": 15,
    "severidad": "warning"
  },
  {
    "tipo_alerta": "COSTO_ANORMAL",
    "mensaje": "3 tanqueo(s) con costo por galón fuera de rango esperado",
    "cantidad": 3,
    "severidad": "error"
  }
]

Get Alert Records

GET /api/tanqueos/dashboard/alerts/:alertType/records

Get detailed records for a specific alert type.

Path Parameters

alertType

string

required

Alert type: SIN_HOROMETRO, COSTO_ANORMAL, SALDO_CRITICO, or CONSUMO_ATIPICO

Response

Array of full TanqueoRelacion records that match the alert criteria.

Example

curl -X GET 'https://api.example.com/api/tanqueos/dashboard/alerts/SIN_HOROMETRO/records?fecha_inicio=2024-01-01' \
  -H 'Authorization: Bearer <token>'

Get Detailed Table

GET /api/tanqueos/dashboard/detailed-table

Get paginated fuel records with alert flags for each record.

Query Parameters

Supports all standard filters plus pagination:

page

integer

default:1

Page number

limit

integer

default:20

Records per page

Response

data

array

Array of fuel records with flagsEach record includes all TanqueoRelacion fields plus:

flags

object

Alert flags for this record

sin_horometro

boolean

True if hourmeter is missing

costo_anormal

boolean

True if cost per gallon is outside expected range

saldo_critico

boolean

True if balance is below -500,000 COP

pagination

object

Pagination metadata (same as list endpoint)

Example

curl -X GET 'https://api.example.com/api/tanqueos/dashboard/detailed-table?page=1&limit=50&area_operacion=NORTE' \
  -H 'Authorization: Bearer <token>'

Notes

All dashboard endpoints filter to tipo_operacion = 'TANQUEO' (excludes ANTICIPO records)
Dates are inclusive when using fecha_inicio and fecha_fin
Statistical calculations (standard deviation, averages) exclude null values
The vehicles-by-area endpoint defaults to the last 2 months if no date filter is provided
All monetary values are in Colombian Pesos (COP)
Saldos-bombas endpoint respects Row Level Security (RLS) based on authenticated user

List Fuel Records - View detailed records
Get Filter Options - Get available filter values

Authentication

Fuel Tracking

Lubrication Services

Fleet Management

Vehicle Documents

Maintenance

Budgets

Fuel Station Balances

Catalogs

File Upload

​Overview

​Common Filter Parameters

​Get Executive KPIs

​Response

​Example

​Get Fuel Station Balances

​Response

​Example

​Get Consumption Over Time

​Response

​Example

​Get Fuel Distribution

​Response

​Example

​Get Consumption by Area

​Response

​Get Top Vehicles

​Response

​Get Vehicles by Area

​Response

​Get Consumption by Driver

​Response

​Get Consumption by Pump

​Response

​Get Intelligent Alerts

​Alert Types

​Fuel Price Thresholds

​Response

​Example

​Response Example

​Get Alert Records

​Path Parameters

​Response

​Example

​Get Detailed Table

​Query Parameters

​Response

​Example

​Notes

​Related Endpoints

Build docs developers (and LLMs) love

Overview

Common Filter Parameters

Get Executive KPIs

Response

Example

Get Fuel Station Balances

Response

Example

Get Consumption Over Time

Response

Example

Get Fuel Distribution

Response

Example

Get Consumption by Area

Response

Get Top Vehicles

Response

Get Vehicles by Area

Response

Get Consumption by Driver

Response

Get Consumption by Pump

Response

Get Intelligent Alerts

Alert Types

Fuel Price Thresholds

Response

Example

Response Example

Get Alert Records

Path Parameters

Response

Example

Get Detailed Table

Query Parameters

Response

Example

Notes

Related Endpoints