Documentación

API para que sistemas externos se integren con Estárter: servicios, reservas,
vehículos, usuarios y GPS en tiempo real. Esta página es el índice general de
lo que ofrece la API; el detalle de cada endpoint está en su carpeta.

¿Qué es Estárter?

Estárter es una empresa de transporte corporativo en Colombia: mueve a los
empleados de sus clientes en una flota de vehículos, en servicios programados de
ingreso y salida. La API externa expone, de forma controlada, las
operaciones y datos que un tercero necesita para integrarse.

Autenticación

Conseguí una API Key de sistema (generala o solicitala al administrador).

Autenticate en POST /api/v1/externalauth/login enviando la key por el
parámetro token → la respuesta trae un access token.

Incluí ese token en cada request: Authorization: Bearer <access_token>.

Para el GPS de Polaris se usa un service token dedicado (mismo header Bearer).

Hay también POST /api/v1/external/authStaff (Auth Admin) para flujos administrativos.

Base URLs

Dominio	Para
`https://cloud.estarter.co`	Endpoints Estárter (`/api/v1/external/...`)
`https://gps.estarter.co`	GPS en tiempo real de Polaris (`/v1/...`)

Herramientas que ofrece la API

🚐 Servicios

Consultar los servicios de transporte (ingreso/salida) con filtros.

POST /api/v1/external/servicios — listar servicios con filtros.

POST /api/v1/external/servicios/filtros — opciones de filtros disponibles.

📅 Reservas

POST /api/v1/external/reservas — obtener reservas por EID y rango de fechas.

🚗 Vehículos

Alta, consulta y catálogo de la flota.

POST /api/v1/external/vehiculos/crear — crear vehículo desde RUNT.

POST /api/v1/external/vehiculos — obtener vehículos.

GET /api/v1/external/vehiculos/filtros — filtros de vehículos.

PUT /api/v1/external/vehiculos/proveedor — agregar o remover proveedor a un vehículo.

Catálogo: POST/GET /api/v1/catalogo-vehiculos, PUT /api/v1/catalogo-vehiculos/{id}.

Documentos: POST /api/v1/external/properacional — datos de preoperacional (paginado).

👤 Usuarios, Historial y Notificaciones

POST /api/v1/external/authStaff — autenticación de administradores.

GET /api/v1/historial/filtros · POST /api/v1/historial — historial de usuarios con filtros.

Notificaciones / menciones: POST|GET /api/v1/notificaciones/menciones,
PUT .../{id}/visto, GET .../sugerencias-menciones, PUT /api/v1/agentes/alias.

📍 GPS en tiempo real — Polaris

La posición de la flota servida por Polaris (dueño único de la posición canónica;
ingiere de Zonar/Webfleet/OnTrack + teléfono del conductor y la unifica). Carpeta Polaris:

Posición en vivo: GET /v1/all (toda la flota), GET /v1/states?placas= (lote, máx 100),
GET /v1/state/{placa} (estado completo).

Geoespacial: GET /v1/around (cerca de un punto), GET /v1/bbox (dentro de un área).

Histórico: GET /v1/readings?placa=&from=&to= (trazado/recorrido).

Tiempo real (push): GET /v1/stream/{placa} — Server-Sent Events.

GPS legacy (vía backend, compatibilidad): GET /api/v1/external/gps/vehiculos
(flota) y GET /api/v1/external/gps/vehiculos/{placa}. Para tiempo real preferí Polaris.

⭐ Ultra (VIP)

GET /api/public/catalogo-vehiculos-ultra — catálogo de vehículos Ultra.

POST /api/v1/external/solicitud-vip — crear solicitud de servicio VIP.

🛠️ Utilidades

POST /api/v1external/upload-file — almacenar archivo PDF.

GET /api/v1/datatime — hora del servidor.

GET /api/v1/invalidar-cache — invalidar caché.

Convenciones

Auth: Authorization: Bearer <token> en todos los endpoints.

Tiempos: UTC (ISO 8601); el GPS de Polaris incluye además hora Bogotá (UTC-5).

Placa: MAYÚSCULAS, 4–10 alfanumérico (p.ej. PUP074).

Errores: 400 (parámetro inválido), 401 (token faltante/inválido).

El detalle de parámetros, body y respuestas de cada endpoint está en su carpeta
correspondiente del sidebar.

¿Qué es Estárter?#

Autenticación#

Base URLs#

Herramientas que ofrece la API#

🚐 Servicios#

📅 Reservas#

🚗 Vehículos#

👤 Usuarios, Historial y Notificaciones#

📍 GPS en tiempo real — Polaris#

⭐ Ultra (VIP)#

🛠️ Utilidades#

Convenciones#