Skip to main content

​
Overview

The Dashboard endpoints provide analytics, KPIs, and expiration tracking for all vehicle documents. These endpoints are optimized for dashboard displays and management reporting.

​
Get KPIs

curl -X GET "https://api.example.com/api/documentos/dashboard/kpis" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"
Retrieves executive KPIs summarizing document status across all vehicles.

​
Query Parameters

​
placa
string
Filter by vehicle license plate (partial match)
​
area_operacion
string
Filter by operating area (partial match)

​
Response

​
totalVehiculos
integer
Total number of vehicles in the dataset
​
vencidos
integer
Number of expired documents (expiration date < today)
​
porVencer
integer
Number of documents expiring within 30 days
​
proximos
integer
Number of documents expiring within 31-60 days
​
vigentes
integer
Number of valid documents (expiring in >60 days)
​
sinDocumento
integer
Number of documents without expiration date
​
totalDocumentos
integer
Total number of documents (excludes sinDocumento)

​
Example Response

{
  "totalVehiculos": 150,
  "vencidos": 12,
  "porVencer": 8,
  "proximos": 15,
  "vigentes": 415,
  "sinDocumento": 0,
  "totalDocumentos": 450
}

​
Document Status Logic

Documents are categorized based on days until expiration:
  • VENCIDO (Expired): Days remaining < 0
  • POR_VENCER (About to expire): 0-30 days
  • PROXIMO (Upcoming): 31-60 days
  • VIGENTE (Valid): >60 days
  • SIN_FECHA (No date): No expiration date set

​
Get Calendar Events

curl -X GET "https://api.example.com/api/documentos/dashboard/calendar?year=2026&month=3" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"
Retrieves document expiration events for calendar display.

​
Query Parameters

​
year
integer
Year for calendar (defaults to current year)
​
month
integer
Month for calendar, 1-12 (defaults to current month)
​
placa
string
Filter by vehicle license plate
​
area_operacion
string
Filter by operating area
​
tipo_documento
string
Filter by document type: SOAT, RTM, or Póliza

​
Response

Returns an array of calendar events, sorted by date.
​
id
string
Unique event identifier (format: {vehiculo_id}-{field_name})
​
placa
string
Vehicle license plate
​
area_operacion
string
Operating area
​
tipo_documento
string
Document type: SOAT, RTM, or Póliza
​
fecha
string
Expiration date (YYYY-MM-DD)
​
estado
string
Document status: VENCIDO, POR_VENCER, PROXIMO, or VIGENTE
​
diasRestantes
integer
Days until expiration (negative if expired)
​
color
string
Color indicator: red, orange, yellow, or green
​
pdf
string
URL to PDF document (null if not available)

​
Example Response

[
  {
    "id": "123-fecha_vencimiento_soat",
    "placa": "ABC123",
    "area_operacion": "Bogotá Norte",
    "tipo_documento": "SOAT",
    "fecha": "2026-03-15",
    "estado": "POR_VENCER",
    "diasRestantes": 11,
    "color": "orange",
    "pdf": "https://storage.example.com/soat/abc123.pdf"
  },
  {
    "id": "124-fecha_vencimiento_rtm",
    "placa": "DEF456",
    "area_operacion": "Medellín",
    "tipo_documento": "RTM",
    "fecha": "2026-03-20",
    "estado": "POR_VENCER",
    "diasRestantes": 16,
    "color": "orange",
    "pdf": "https://storage.example.com/rtm/def456.pdf"
  }
]

​
Date Range

The endpoint returns events within the specified month ± 7 days to ensure events near month boundaries are included.

​
Get Expiring Documents List

curl -X GET "https://api.example.com/api/documentos/dashboard/expiring-list?limit=10" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"
Retrieves a prioritized list of documents requiring attention, sorted by expiration urgency.

​
Query Parameters

​
placa
string
Filter by vehicle license plate
​
area_operacion
string
Filter by operating area
​
tipo_documento
string
Filter by document type: SOAT, RTM, or Póliza
​
estado
string
Filter by status: VENCIDO, POR_VENCER, PROXIMO, or VIGENTE
​
limit
integer
default:"50"
Maximum number of items to return

​
Response

Returns an array of document items, prioritized by urgency (expired first, then soonest to expire).
​
id
string
Unique item identifier
​
vehiculo_id
integer
Vehicle database ID
​
placa
string
Vehicle license plate
​
area_operacion
string
Operating area
​
tipo_documento
string
Document type: SOAT, RTM, or Póliza
​
fecha_vencimiento
string
Expiration date
​
estado
string
Document status
​
diasRestantes
integer
Days until expiration
​
color
string
Color indicator for UI
​
pdf
string
URL to PDF document

​
Example Response

[
  {
    "id": "120-fecha_vencimiento_soat",
    "vehiculo_id": 120,
    "placa": "XYZ789",
    "area_operacion": "Cali",
    "tipo_documento": "SOAT",
    "fecha_vencimiento": "2026-02-28",
    "estado": "VENCIDO",
    "diasRestantes": -4,
    "color": "red",
    "pdf": "https://storage.example.com/soat/xyz789.pdf"
  },
  {
    "id": "121-fecha_vencimiento_rtm",
    "vehiculo_id": 121,
    "placa": "ABC123",
    "area_operacion": "Bogotá Norte",
    "tipo_documento": "RTM",
    "fecha_vencimiento": "2026-03-10",
    "estado": "POR_VENCER",
    "diasRestantes": 6,
    "color": "orange",
    "pdf": null
  }
]

​
Sorting Priority

  1. Expired documents (negative diasRestantes)
  2. About to expire (0-30 days)
  3. Upcoming expirations (31-60 days)
  4. Valid documents (>60 days)

​
Get Documents by Area

curl -X GET "https://api.example.com/api/documentos/dashboard/by-area" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"
Retrieves document status distribution grouped by operating area.

​
Response

Returns an array of area summaries, sorted by priority (areas with most urgent documents first).
​
area
string
Operating area name
​
total
integer
Total documents in this area
​
vencidos
integer
Expired documents
​
porVencer
integer
Documents expiring within 30 days
​
proximos
integer
Documents expiring within 31-60 days
​
vigentes
integer
Valid documents (>60 days)

​
Example Response

[
  {
    "area": "Bogotá Norte",
    "total": 150,
    "vencidos": 8,
    "porVencer": 5,
    "proximos": 12,
    "vigentes": 125
  },
  {
    "area": "Medellín",
    "total": 90,
    "vencidos": 3,
    "porVencer": 2,
    "proximos": 8,
    "vigentes": 77
  },
  {
    "area": "SIN ÁREA",
    "total": 15,
    "vencidos": 1,
    "porVencer": 1,
    "proximos": 2,
    "vigentes": 11
  }
]

​
Sorting

Areas are sorted by urgency: (vencidos + porVencer) in descending order, showing problem areas first.

​
Dashboard Usage Examples

​
Alert Dashboard

Get critical alerts requiring immediate attention: 
curl -X GET "https://api.example.com/api/documentos/dashboard/expiring-list?estado=VENCIDO&limit=20" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

​
Area Manager View

Get KPIs and expiring documents for a specific area: 
# Get KPIs
curl -X GET "https://api.example.com/api/documentos/dashboard/kpis?area_operacion=Bogotá Norte" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

# Get expiring list
curl -X GET "https://api.example.com/api/documentos/dashboard/expiring-list?area_operacion=Bogotá Norte&limit=50" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

​
Monthly Calendar

Get all expirations for the current month: 
curl -X GET "https://api.example.com/api/documentos/dashboard/calendar?year=2026&month=3" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

​
SOAT-Only Dashboard

Focus on SOAT documents only: 
curl -X GET "https://api.example.com/api/documentos/dashboard/calendar?tipo_documento=SOAT" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Build docs developers (and LLMs) love

Get started for freeTalk to us