RemaFleet API v1

Documentación del API de RemaFleet

El API REST de RemaFleet expone toda la plataforma de gestión de flotas: telemetría en tiempo real, historial de recorridos, comandos a dispositivos, video a bordo, geocercas, alarmas, vehículos y reportes. Todo lo que ves en la consola está disponible por API.

Todas las peticiones se hacen sobre HTTPS contra el nodo de tu cuenta y devuelven JSON. El API es multi-tenant: cada API key opera sobre los datos de su tenant (o de todos, si es una key global).

URL base Cada cuenta opera contra su propio servidor: tu URL base se entrega junto con tu API key en tu panel de cliente. Todos los ejemplos de esta documentación la referencian como $BASE_URL.

La especificación completa está disponible en formato OpenAPI 3.1 en $BASE_URL/_openapi.yaml, lista para importar en Postman, Insomnia o para generar clientes tipados.

🤖 ¿Vienes por agentes de IA? RemaFleet es también un servidor MCP: conecta Claude, Codex, Gemini o Grok y opera la flota en lenguaje natural, con los permisos del usuario. Ve directo a Servidor MCP.

Tu primera petición

# Tu URL base y tu API key vienen en tu panel de cliente
export BASE_URL="https://…/api/v1"

# Snapshot de toda la flota en un request
curl "$BASE_URL/devices/live" \
  -H "Authorization: Bearer rfsk_live_9f4K2…"

Respuesta

{
  "items": [
    {
      "imei": "860000000000000",
      "name": "DEMO-01",
      "online": true,
      "motionState": "moving",
      "location": { "lat": 14.6349, "lng": -90.5069 },
      "speed": 62,
      "heading": 148,
      "acc": true,
      "vehicle": { "plate": "P-123ABC", "name": "Camión 4" }
    }
  ],
  "total": 128
}

Autenticación

El API acepta dos credenciales, ambas enviadas en el header Authorization: Bearer:

API keys `rfsk_live_*`

La credencial recomendada para integraciones servidor-a-servidor. Cada key lleva scopes granulares y existe en dos variantes:

Per-Tenant — toda consulta queda automáticamente acotada al tenant de la key. Es la variante que se entrega a clientes e integradores.
Global — cross-tenant, para operadores de la plataforma. Puede acotarse a un tenant con ?tenant_id=<id>.

Trata tu key como una contraseña: guárdala en un gestor de secretos, no la incluyas en código cliente (apps móviles, navegador) y rótala si sospechas exposición.

JWT de RemaFleet Auth

Los tokens emitidos por el servidor de identidad de RemaFleet (ES256) también son válidos — la URL de autenticación de tu cuenta también viene en tu panel de cliente. El claim dom define el tenant y los scopes gw:<recurso>:<acción> autorizan cada endpoint. Es el mecanismo que usa la propia consola; útil si tu integración actúa en nombre de un usuario.

Con API key

curl $BASE_URL/devices \
  -H "Authorization: Bearer rfsk_live_9f4K2…"

Con JWT (en nombre de un usuario)

# 1. Login contra RemaFleet Auth ($AUTH_URL viene en tu panel)
curl -X POST "$AUTH_URL/v1/auth/login" \
  -H "Content-Type: application/json" \
  -d '{"identifier":"usuario@empresa.com","password":"…"}'

# 2. Usa el access_token contra el gateway
curl $BASE_URL/devices \
  -H "Authorization: Bearer eyJhbGciOiJFUzI1NiJ9…"

401 sin credencial válida

{
  "status": "ER",
  "payload": { "code": "E_UNAUTHORIZED", "message": "Invalid API key" }
}

Scopes y permisos

Cada endpoint exige un scope con el formato <recurso>:<acción> (por ejemplo devices:read). Las API keys llevan los scopes tal cual; en un JWT los mismos scopes van con el prefijo gw: (por ejemplo gw:devices:read).

Recursos disponibles:

Recurso	Cubre
`devices`	Dispositivos, telemetría en vivo, tracking, eventos, viajes, acceso por usuario
`multimedia`	Fotos/video del dispositivo, streams JT1078, HLS, grabaciones
`geofences`	Geocercas, asignaciones y eventos de entrada/salida
`alarms`	Alarmas, reglas, reconocimiento, monitoreo, destinatarios de notificación
`synthetic`	Configuración de detectores de alarmas sintéticas
`vehicles`	Vehículos, fotos, conductores asignados, dashboard de flota
`vehicle-groups`	Grupos de vehículos y su membresía
`personal`	Personal/conductores y sus grupos
`workshops`	Talleres, personal de taller y mantenimientos
`projects`	Proyectos y sus vehículos
`crm`	Clientes y estado de cartera (mora)
`reports`	Reportes operativos y ejecutivos (solo `:read`)
`sms`	Envío e historial de SMS
`tenants`	Administración de tenants (keys globales)
`users`	Administración de usuarios (keys globales)

Las acciones son read y write. Pide solo los scopes que tu integración necesita: una key de solo lectura de flota funciona perfectamente con devices:read + vehicles:read.

403 sin el scope requerido

{
  "status": "ER",
  "payload": {
    "code": "E_FORBIDDEN",
    "message": "Missing scope devices:write"
  }
}

Convenciones

Envelope de respuesta

Toda respuesta viene envuelta en un objeto con status — "OK" en éxito, "ER" en error — y el resultado en payload.

Fechas

Los timestamps se aceptan y devuelven en ISO 8601 con zona horaria (2026-07-18T14:30:00Z). Los rangos usan los parámetros since / until; cuando se omiten, el default habitual es el día en curso en la zona horaria del tenant.

Paginación

Los listados aceptan limit y offset y devuelven total para que puedas paginar. El limit máximo típico es 200 (hasta 1 000 en tracking).

Filtro por tenant

Con una key Per-Tenant no necesitas hacer nada: todo queda acotado a tu tenant. Con una key Global, agrega ?tenant_id=<id> para acotar una consulta.

Paginación

curl "$BASE_URL/devices?limit=50&offset=100&sort_by=last_seen_at&sort_dir=desc" \
  -H "Authorization: Bearer rfsk_live_9f4K2…"

Envelope

// Éxito
{ "status": "OK", "payload": { "items": […], "total": 128, "limit": 50, "offset": 100 } }

// Error
{ "status": "ER", "payload": { "code": "E_VALIDATION", "message": "…" } }

Manejo de errores

Los errores usan códigos HTTP estándar y un código de máquina estable E_* en el payload. Maneja el código de máquina, no el mensaje (que puede cambiar).

HTTP	Código	Cuándo
400	`E_VALIDATION`	Parámetros o body inválidos
401	`E_UNAUTHORIZED`	Credencial ausente, inválida o revocada
403	`E_FORBIDDEN`	La credencial no tiene el scope requerido
404	`E_NOT_FOUND`	El recurso no existe o no pertenece a tu tenant
404	`E_SHARE_INVALID`	Token de ubicación compartida inválido o expirado
409	`E_MANAGED_BY_AUTH`	El recurso (vehículos/grupos) se gestiona desde la plataforma, no por este API
409	`E_PHOTO_LIMIT`	El vehículo ya tiene el máximo de fotos (3)
409	`E_PERSONAL_DUPLICATE_ID`	La cédula ya está asignada en el tenant
409	`E_PROJECT_DUPLICATE_CODE`	El código de proyecto ya existe en el tenant
409	`E_ALREADY_ASSIGNED`	La asignación ya existe (p. ej. personal en taller)
503	`E_STORAGE_DISABLED`	Almacenamiento de archivos no configurado en el nodo

Ejemplo de error

HTTP/1.1 409 Conflict

{
  "status": "ER",
  "payload": {
    "code": "E_MANAGED_BY_AUTH",
    "message": "Vehicles are managed by RemaFleet Auth"
  }
}

Model Context Protocol

Servidor MCP — agentes de IA

RemaFleet expone toda la plataforma como un servidor MCP: un agente de IA (Claude, Codex, Gemini, Grok…) se conecta y opera la flota en lenguaje natural — mapa en vivo, alarmas, geocercas, vehículos, comandos y reportes.

Endpoint MCP <BASE_URL sin /api/v1>/mcp — p. ej. $NODE_URL/mcp. Transporte Streamable HTTP (JSON-RPC 2.0 sobre POST). Tu URL base se entrega en el panel de cliente.

Seguridad: opera con los permisos del usuario

Cada llamada de una tool se ejecuta internamente contra el mismo API /api/v1 reenviando tu credencial, así que toda la autorización existente aplica sin excepción: scopes por recurso, aislamiento por tenant y allowlist de vehículos por usuario. El agente solo ve y ejecuta lo que el rol de esa credencial permite — la lista de tools se filtra por scopes.

Autenticación

Dos credenciales, ambas en el header Authorization: Bearer:

Token de usuario (recomendado para agentes) — un JWT de larga duración que el usuario genera desde la app (Configuración → Usuarios → llave Tokens de acceso). Actúa como ese usuario, con sus permisos.
API key rfsk_live_* — para integraciones M2M (PerTenant o Global), con sus scopes granulares.

Handshake MCP (JSON-RPC)

curl -X POST "$NODE_URL/mcp" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0", "id": 1,
    "method": "initialize",
    "params": { "protocolVersion": "2025-06-18",
                "capabilities": {},
                "clientInfo": { "name": "mi-agente", "version": "1.0" } }
  }'

Métodos soportados

# JSON-RPC 2.0 sobre POST
initialize      → handshake + versión
tools/list      → tools visibles (según scopes)
tools/call      → ejecuta una tool
ping            → keep-alive

Conectar tu agente

Genera un token desde la app y agrégalo a tu cliente con un solo comando. El token se muestra una vez; guárdalo como un secreto.

Un token = un usuario El agente hereda exactamente los permisos del usuario del token. Para un agente de solo lectura, genera el token desde un usuario con rol de solo lectura.

Cualquier cliente compatible con MCP sobre HTTP funciona. Abajo, los comandos actuales de los principales:

Claude Code

claude mcp add --transport http remafleet $NODE_URL/mcp --header "Authorization: Bearer <token>"

OpenAI Codex

export REMAFLEET_TOKEN="<token>"
codex mcp add remafleet --url $NODE_URL/mcp --bearer-token-env-var REMAFLEET_TOKEN

Gemini CLI

gemini mcp add --transport http remafleet $NODE_URL/mcp --header "Authorization: Bearer <token>"

Grok CLI

grok mcp add --transport http remafleet $NODE_URL/mcp --header "Authorization: Bearer <token>"

Config genérica (JSON)

{
  "type": "http",
  "url": "$NODE_URL/mcp",
  "headers": { "Authorization": "Bearer <token>" }
}

Catálogo de tools

26 herramientas cubren el flujo operativo completo. Cada una exige el mismo scope que su endpoint del API — si tu credencial no lo tiene, la tool ni siquiera aparece en tools/list.

Tool	Qué hace	Scope
`get_fleet_live`	Snapshot de toda la flota (posición, estado)	`devices:read`
`list_devices`	Lista dispositivos	`devices:read`
`get_device`	Detalle de un dispositivo	`devices:read`
`get_device_summary`	Resumen del rango (km, viajes, eventos)	`devices:read`
`get_device_tracking`	Puntos de recorrido	`devices:read`
`get_device_events`	Historial de eventos	`devices:read`
`get_device_trips`	Viajes agregados	`devices:read`
`get_event_types`	Catálogo de tipos de evento	`alarms:read`
`share_device_location`	Genera enlace público temporal	`devices:read`
`list_device_commands`	Comandos disponibles del dispositivo	`devices:read`
`send_device_command` acción	Ejecuta un comando (corte de motor…)	`commands:send`
`get_command_log`	Historial de comandos y ACKs	`multimedia:read`
`list_alarms`	Lista alarmas	`alarms:read`
`get_monitoring_summary`	Resumen del centro de monitoreo	`alarms:read`
`ack_alarm`	Reconoce una alarma	`alarms:write`
`ack_all_alarms` acción	Reconoce todas las alarmas	`alarms:write`
`list_geofences`	Lista geocercas	`geofences:read`
`get_geofence`	Detalle + geometría	`geofences:read`
`list_geofence_events`	Entradas/salidas de geocercas	`geofences:read`
`list_vehicles`	Lista vehículos	`vehicles:read`
`get_vehicle`	Ficha del vehículo	`vehicles:read`
`get_fleet_dashboard`	Estado agregado + rankings	`vehicles:read`
`list_vehicle_groups`	Grupos de vehículos	`vehicle-groups:read`
`list_personal`	Personal / conductores	`personal:read`
`list_maintenance`	Mantenimientos	`workshops:read`
`generate_report`	Genera reportes operativos	`reports:read`

tools/call — ejemplo

curl -X POST "$NODE_URL/mcp" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0", "id": 2,
    "method": "tools/call",
    "params": {
      "name": "generate_report",
      "arguments": {
        "type": "kilometraje",
        "group_id": "grp_…",
        "since": "2026-07-11T00:00:00Z",
        "until": "2026-07-18T00:00:00Z"
      }
    }
  }'

Comandos con efectos

# send_device_command y ack_all_alarms
# están anotados como destructivos:
# un buen agente pedirá confirmación
# antes de ejecutarlos.

Dispositivos

Un dispositivo es la unidad GPS o cámara instalada en el vehículo, identificada por su IMEI. Expone su protocolo, SIM (msisdn/iccid), modelo, estado de conexión y el vehículo asignado.

#GET/devices
Lista dispositivos (búsqueda, paginación, orden)
#GET/devices/{imei}
Detalle de un dispositivo
#PUT/devices/{imei}
Edita nombre, tenant, SIM, modelo y comentarios
#GET/devices/{imei}/state
Snapshot del estado runtime
#GET/device-models
Catálogo de modelos por marca
#GET/user-access/{userId}/devices
Acceso a dispositivos de un usuario
#PUT/user-access/{userId}/devices
Define el acceso (todos o lista de IMEIs)

Scopes: devices:read · devices:write

Buscar dispositivos

curl "$BASE_URL/devices?search=DEMO&limit=10" \
  -H "Authorization: Bearer rfsk_live_9f4K2…"

Respuesta

{
  "status": "OK",
  "payload": {
    "items": [
      {
        "imei": "860000000000000",
        "name": "DEMO-01",
        "protocolCode": "jimi_vl103",
        "model": "Jimi VL103",
        "msisdn": "+502…",
        "online": true,
        "lastSeenAt": "2026-07-18T14:29:41Z"
      }
    ],
    "total": 1, "limit": 10, "offset": 0
  }
}

Flota en vivo

El endpoint estrella para mapas y tableros: toda la flota en un solo request con posición, velocidad, rumbo, ignición, dirección en texto (reverse geocoding) y el vehículo asignado.

#GET/devices/live
Snapshot de todos los dispositivos
#GET/devices/{imei}/summary
Resumen del rango: distancia, viajes, velocidad y eventos

El campo motionState es el estado operativo calculado por el servidor — el mismo que colorea la consola:

Valor	Significado
`moving`	En movimiento
`idle`	Ralentí: motor encendido, detenido > 5 min
`off`	Motor apagado
`disconnected`	Sin reportar hace más de 3 h

Scope: devices:read

Resumen del día de un dispositivo

curl $BASE_URL/devices/860000000000000/summary \
  -H "Authorization: Bearer rfsk_live_9f4K2…"

Respuesta

{
  "imei": "860000000000000",
  "timezone": "America/Guatemala",
  "distanceKm": 142.7,
  "maxSpeed": 94,
  "trips": { "count": 6, "drivingTimeSeconds": 14520, "avgSpeed": 38 },
  "tracking": { "points": 2841 },
  "events": { "total": 12, "byType": { "overspeed": 2, "acc_on": 6 } }
}

Historial y viajes

Cada posición reportada queda almacenada en una base de series de tiempo. Sobre ese historial el servidor agrega viajes (recorridos entre encendido y apagado) y eventos del dispositivo.

#GET/devices/{imei}/tracking
Puntos de tracking del rango (hasta 1 000 por página)
#GET/devices/{imei}/trips
Viajes agregados
#GET/devices/{imei}/events
Historial de eventos (filtrable por tipo)
#GET/event-types
Catálogo de tipos de evento observados

Scope: devices:read

Tracking de un rango

curl "$BASE_URL/devices/860000000000000/tracking?since=2026-07-18T00:00:00Z&until=2026-07-18T23:59:59Z&limit=500" \
  -H "Authorization: Bearer rfsk_live_9f4K2…"

Compartir ubicación

Genera un enlace público temporal para compartir la ubicación en vivo de un vehículo — por ejemplo con un cliente que espera una entrega. El token expira solo (1 h por defecto, máximo 7 días) y el endpoint de consulta no requiere autenticación.

#POST/devices/{imei}/share
Genera el token temporal (?ttl= en segundos)
#GET/share/{token}
Público: ubicación, dirección, velocidad y estado

Scope: devices:read (solo para generar)

Generar enlace de 24 h

curl -X POST "$BASE_URL/devices/860000000000000/share?ttl=86400" \
  -H "Authorization: Bearer rfsk_live_9f4K2…"

Respuesta

{
  "token": "shr_x1B9…",
  "ttl": 86400,
  "expiresAt": "2026-07-19T14:30:00Z",
  "url": "/api/v1/share/shr_x1B9…"
}

Comandos

Envía comandos al dispositivo — corte de motor, reinicio, configuración — por GPRS (conexión en vivo) o por SMS como respaldo. El catálogo de comandos depende del protocolo de cada dispositivo; consúltalo antes de ejecutar.

#GET/devices/{imei}/commands
Comandos disponibles para el dispositivo
#POST/devices/{imei}/commands
Ejecuta un comando (GPRS o SMS, con cola si está offline)
#GET/devices/{imei}/command-log
Historial de comandos y respuestas (ACKs)

Scopes: devices:read · devices:write

Comandos críticos Un corte de motor mal aplicado es un riesgo de seguridad vial. Implementa confirmación de dos pasos en tu integración y consulta el command-log para verificar el ACK del dispositivo.

Ejecutar un comando

curl -X POST $BASE_URL/devices/860000000000000/commands \
  -H "Authorization: Bearer rfsk_live_9f4K2…" \
  -H "Content-Type: application/json" \
  -d '{
    "command": "engine_stop",
    "transport": "gprs",
    "queueIfOffline": true
  }'

Multimedia

Fotos, clips de video y audio capturados por las cámaras a bordo. Los archivos se almacenan en la nube y se sirven mediante URLs prefirmadas de corta duración (5 min) — pídelas al momento de mostrar el archivo.

#GET/devices/{imei}/multimedia
Lista assets del dispositivo (por canal, tipo y rango)
#GET/multimedia/{id}
Metadatos de un asset
#GET/multimedia/{id}/url
URL prefirmada de descarga (TTL 5 min)
#DELETE/multimedia/{id}
Borrado lógico del asset
#POST/devices/{imei}/multimedia/request
Pide a la cámara subir video de un canal/alarma
#GET/devices/{imei}/recordings
Lista de grabaciones en memoria de la cámara (día + canal)

Scopes: multimedia:read · multimedia:write

Videos de hoy del canal 1

curl "$BASE_URL/devices/860000000000000/multimedia?type=video&channel=1&since=2026-07-18T00:00:00Z" \
  -H "Authorization: Bearer rfsk_live_9f4K2…"

Respuesta

{
  "items": [
    {
      "id": "mm_01J8…",
      "deviceImei": "860000000000000",
      "mimeType": "video/mp4",
      "sizeBytes": 10485760,
      "channelId": 1,
      "alarmTime": "2026-07-18T09:14:02Z",
      "receivedAt": "2026-07-18T09:15:40Z"
    }
  ]
}

Video en vivo (HLS)

Las cámaras JT1078 transmiten al gateway, que transcodifica a HLS reproducible en cualquier navegador o player nativo. También puedes grabar la transmisión en curso y guardarla como asset multimedia.

#GET/devices/{imei}/hls/{channel}/index.m3u8
Playlist HLS del stream en vivo/playback
#GET/devices/{imei}/streams
Streams RTP activos del dispositivo
#POST/devices/{imei}/streams/teardown
Cierra el stream y el transcodificador de un canal
#POST/devices/{imei}/multimedia/recording/start
Empieza a grabar el stream activo
#POST/devices/{imei}/multimedia/recording/stop
Detiene y persiste la grabación
#GET/devices/{imei}/multimedia/recording/status
Estado de la grabación de un canal

Scopes: multimedia:read · multimedia:write

Players nativos Si tu player no puede enviar headers, pasa la credencial como query: index.m3u8?api_key=rfsk_live_…. El playlist responde 503 mientras el stream arranca — reintenta con backoff.

Reproducir en el navegador

// Con hls.js — BASE_URL es la URL base de tu panel de cliente
const hls = new Hls();
hls.loadSource(
  `${BASE_URL}/devices/860000000000000/hls/1/index.m3u8?api_key=rfsk_live_9f4K2…`
);
hls.attachMedia(document.querySelector("video"));

Alarmas

Las alarmas son los eventos que exigen atención: pánico, exceso de velocidad, geocerca violada, desconexión. Cada una tiene severidad (critical · high · normal · low) y un flujo de reconocimiento con auditoría de quién la atendió.

#GET/alarms
Lista alarmas (severidad, IMEI, ack, rango)
#GET/alarms/{time}/{id}
Detalle de una alarma
#POST/alarms/{time}/{id}/ack
Reconoce la alarma
#POST/alarms/{time}/{id}/unack
Revierte el reconocimiento
#GET/monitoring/summary
Resumen del centro de monitoreo (importantes, comunes, desconexiones)
#POST/monitoring/ack-all
Reconoce todas (opcionalmente por severidad)

Scopes: alarms:read · alarms:write

Alarmas críticas sin atender

curl "$BASE_URL/alarms?severity=critical&acknowledged=false" \
  -H "Authorization: Bearer rfsk_live_9f4K2…"

Respuesta

{
  "items": [
    {
      "time": "2026-07-18T13:58:11Z",
      "id": "alm_9t3…",
      "severity": "critical",
      "title": "Botón de pánico",
      "imei": "860000000000000",
      "acknowledgedAt": null
    }
  ]
}

Reglas de alarma

Las reglas convierten eventos crudos en alarmas: definen la fuente (device_event, geofence_event, trip), el tipo de evento, condiciones, severidad, canales de notificación y un cooldown para no inundar de alertas repetidas.

#GET/alarm-rules
Lista reglas (por fuente, tipo, activas)
#POST/alarm-rules
Crea una regla
#GET/alarm-rules/{id}
Detalle
#PUT/alarm-rules/{id}
Actualiza
#DELETE/alarm-rules/{id}
Elimina
#GET/event-types
Catálogo de tipos de evento para construir reglas

Scopes: alarms:read · alarms:write

Regla de exceso de velocidad

curl -X POST $BASE_URL/alarm-rules \
  -H "Authorization: Bearer rfsk_live_9f4K2…" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Exceso > 100 km/h",
    "source": "device_event",
    "eventType": "overspeed",
    "severity": "high",
    "channels": ["email", "push"],
    "cooldownSeconds": 600,
    "active": true
  }'

Alarmas sintéticas

Además de las alarmas que reporta el hardware, el servidor deriva alarmas de 32 detectores inteligentes que cruzan telemetría, geocercas y cartera: movimiento nocturno, ralentí excesivo, manipulación de GPS, unidades en mora que salen de zona, y más. Cada detector se activa y configura por tenant.

#GET/synthetic-alarms/catalog
Catálogo de los detectores y sus parámetros
#GET/synthetic-alarms
Configuración vigente del tenant
#PUT/synthetic-alarms/{detectorKey}
Activa/configura un detector

Scopes: synthetic:read · synthetic:write

Activar movimiento nocturno

curl -X PUT $BASE_URL/synthetic-alarms/night_movement \
  -H "Authorization: Bearer rfsk_live_9f4K2…" \
  -H "Content-Type: application/json" \
  -d '{ "enabled": true, "params": { "from": "22:00", "to": "05:00" } }'

Notificaciones

Los destinatarios definen a quién y por qué canal se entregan las alarmas: correo, SMS, Telegram o push. Cada destinatario puede llevar filtros por vehículo y tipo de alerta — sin filtros recibe todo; con reglas, solo lo que coincida con alguna.

#GET/recipients
Lista destinatarios (por canal, activos)
#POST/recipients
Crea destinatario (canal + target + filtros)
#PUT/recipients/{rid}
Actualiza label, target, filtros o estado
#DELETE/recipients/{rid}
Elimina
#POST/recipients/{rid}/test
Envía un mensaje de prueba por el canal

Scopes: alarms:read · alarms:write

Correo que solo recibe pánico

curl -X POST $BASE_URL/recipients \
  -H "Authorization: Bearer rfsk_live_9f4K2…" \
  -H "Content-Type: application/json" \
  -d '{
    "channel": "email",
    "target": { "email": "operaciones@empresa.com" },
    "label": "Turno de operaciones",
    "filters": { "rules": [{ "imei": null, "event_type": "sos" }] }
  }'

Geocercas

Polígonos GeoJSON — zonas seguras, zonas rojas, patios, rutas — que generan eventos de enter/exit por cada dispositivo asignado. Esos eventos alimentan reglas de alarma y reportes.

#GET/geofences
Lista geocercas
#POST/geofences
Crea (GeoJSON Polygon/MultiPolygon/Feature)
#GET/geofences/{id}
Detalle con geometría
#PUT/geofences/{id}
Actualiza
#DELETE/geofences/{id}
Archiva (borrado permanente: /permanent)
#POST/geofences/{id}/assignments
Asigna dispositivos por IMEI
#DELETE/geofences/{id}/assignments/{imei}
Desasigna (emite salida sintética si estaba dentro)
#GET/geofence-events
Feed global de eventos enter/exit

Scopes: geofences:read · geofences:write

Crear una geocerca

curl -X POST $BASE_URL/geofences \
  -H "Authorization: Bearer rfsk_live_9f4K2…" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Patio central",
    "geom": {
      "type": "Polygon",
      "coordinates": [[[-90.51,14.63],[-90.50,14.63],[-90.50,14.64],[-90.51,14.64],[-90.51,14.63]]]
    }
  }'

Eventos recientes

curl "$BASE_URL/geofence-events?event_type=exit&since=2026-07-18T00:00:00Z" \
  -H "Authorization: Bearer rfsk_live_9f4K2…"

Vehículos

El vehículo es la ficha de negocio del activo: placa, marca, modelo, VIN, tipo, grupos y los dispositivos que lo reportan (con uno principal). El detalle incluye fotos con URLs prefirmadas y los conductores asignados con horario.

Lectura por este API; altas y ediciones desde la plataforma El catálogo de vehículos se administra centralmente en RemaFleet (consola/app). Las escrituras de vehículos y grupos por este API devuelven 409 E_MANAGED_BY_AUTH. Fotos, conductores y dashboard sí se gestionan aquí.

#GET/vehicles
Lista vehículos (búsqueda por nombre/placa/código)
#GET/vehicles/{id}
Detalle: fotos, devices y device principal
#GET/vehicles/dashboard
Dashboard de flota: estado + rankings del día
#GET/vehicle-types
Catálogo de tipos (iconos)
#GET/vehicles/{id}/photos
Fotos (máx 3, presigned URLs)
#POST/vehicles/{id}/photos
Sube foto (multipart, máx 10 MB)
#GET/vehicles/{id}/drivers
Conductores asignados con horario
#POST/vehicles/{id}/drivers
Asigna conductor (cíclico semanal o fecha única)

Scopes: vehicles:read · vehicles:write

Dashboard de flota

curl $BASE_URL/vehicles/dashboard \
  -H "Authorization: Bearer rfsk_live_9f4K2…"

Respuesta

{
  "fleet": {
    "total": 114,
    "moving": 20,
    "blocked": 14,
    "engineOn": 22,
    "connected": 50
  },
  "rankings": {
    "distance": [ { "name": "Camión 4", "plate": "P-123ABC", "km": 212.4 } ],
    "maxSpeed": [ { "name": "Panel 2", "maxSpeed": 108 } ]
  },
  "timezone": "America/Guatemala"
}

Grupos de vehículos

Agrupaciones N:M para organizar la flota — por región, cliente o tipo de operación. Son el alcance típico de los reportes (group_id).

Solo lectura por este API Igual que los vehículos, los grupos se administran desde la plataforma; las escrituras devuelven 409 E_MANAGED_BY_AUTH.

#GET/vehicle-groups
Lista grupos con conteo de vehículos
#GET/vehicle-groups/{id}
Detalle
#GET/vehicle-groups/{id}/vehicles
Vehículos del grupo

Scope: vehicle-groups:read

Vehículos de un grupo

curl $BASE_URL/vehicle-groups/grp_01J9…/vehicles \
  -H "Authorization: Bearer rfsk_live_9f4K2…"

Personal y conductores

El registro de personal: conductores, mecánicos y personal operativo, con cédula (única por tenant), licencias con vencimiento, foto y grupos. Se enlaza con la flota mediante la asignación conductor↔vehículo con horario.

#GET/personal
Lista personal (búsqueda por nombre/cédula/teléfono)
#POST/personal
Crea (409 si la cédula ya existe)
#GET/personal/{id}
Detalle con foto prefirmada
#PUT/personal/{id}
Actualiza
#DELETE/personal/{id}
Baja lógica
#POST/personal/{id}/photo
Sube/reemplaza la foto (multipart)
#GET/personal/dashboard
Totales, licencias por vencer y ranking por grupo
#GET/personal-groups
Grupos de personal (CRUD + miembros)

Scopes: personal:read · personal:write

Crear un conductor

curl -X POST $BASE_URL/personal \
  -H "Authorization: Bearer rfsk_live_9f4K2…" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Juan Pérez",
    "national_id": "2547 89632 0101",
    "phone": "+502 5555 1234",
    "email": "jperez@empresa.com"
  }'

Talleres y mantenimiento

Talleres físicos (opcionalmente ligados a una geocerca), su personal con rol (responsable, jefe de taller, mecánico) y la bitácora de mantenimientos por vehículo: 19 tipos de servicio, costo, mecánico y programación del próximo servicio por fecha u odómetro.

#GET/workshops
Lista talleres
#POST/workshops
Crea taller
#GET/workshops/dashboard
Resumen: talleres, vehículos, mantenimientos
#POST/workshops/{id}/vehicles
Asigna vehículos (M:N)
#POST/workshops/{id}/personnel
Asigna personal con rol
#GET/maintenance
Lista mantenimientos (por estado, vehículo, tipo)
#POST/maintenance
Registra un mantenimiento
#PUT/maintenance/{id}
Actualiza (p. ej. cierra con status: "fin")

Scopes: workshops:read · workshops:write

Registrar cambio de aceite

curl -X POST $BASE_URL/maintenance \
  -H "Authorization: Bearer rfsk_live_9f4K2…" \
  -H "Content-Type: application/json" \
  -d '{
    "vehicle_id": "veh_01J9…",
    "type": "aceite",
    "date_ini": "2026-07-18T08:00:00Z",
    "next_mode": "both",
    "next_date": "2026-10-18T08:00:00Z",
    "next_odo": "185000",
    "cost": "85.00",
    "status": "fin"
  }'

Proyectos

Agrupa vehículos por obra o contrato, con fechas y geocerca opcional. El dashboard del proyecto entrega kilómetros y horas por vehículo en el rango — ideal para facturar maquinaria por uso real.

#GET/projects
Lista proyectos
#POST/projects
Crea (código único por tenant)
#GET/projects/next-code
Autosugerencia del siguiente código
#POST/projects/{id}/vehicles
Asigna vehículos (M:N)
#GET/projects/{id}/dashboard
Km + horas por vehículo en el rango

Scopes: projects:read · projects:write

Dashboard del proyecto

curl "$BASE_URL/projects/prj_01J9…/dashboard?date_from=2026-07-01T00:00:00Z&date_to=2026-07-18T23:59:59Z" \
  -H "Authorization: Bearer rfsk_live_9f4K2…"

CRM y cartera

Sincroniza tu CRM con la flota: clientes y su estado de cartera (mora) cruzados con los vehículos por placa normalizada (minúsculas, sin espacios extra). Con la cartera al día, los detectores de mora pueden alertar cuando una unidad morosa sale de zona o circula de noche.

#GET/clients
Lista clientes
#POST/clients
Crea cliente
#PUT/clients/{id}
Actualiza
#GET/business-status
Estado de cartera de todas las placas
#PUT/business-status/{plate}
Actualiza el estado de una placa
#POST/business-status/bulk
Carga masiva — el webhook para tu CRM

Scopes: crm:read · crm:write

Webhook de cartera (bulk)

curl -X POST $BASE_URL/business-status/bulk \
  -H "Authorization: Bearer rfsk_live_9f4K2…" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      { "plate": "P-123ABC", "status": "mora", "days_overdue": 45 },
      { "plate": "P-456DEF", "status": "al_dia" }
    ]
  }'

Reportes

Los mismos reportes de la consola, por API: el servidor calcula y devuelve filas listas para renderizar o exportar. El alcance se define por vehicle_ids (CSV) o group_id, con rango de 1 día a 1 mes.

#GET/reports/{type}
Genera el reporte del tipo indicado

Tipos disponibles:

alertasrecorridosdetenciones horas-motorkilometrajegeocercas consolidadoslamora rankingmapa-calor

Scope: reports:read

Kilometraje del grupo, últimos 7 días

curl "$BASE_URL/reports/kilometraje?group_id=grp_01J9…&date_from=2026-07-11T00:00:00Z&date_to=2026-07-18T23:59:59Z" \
  -H "Authorization: Bearer rfsk_live_9f4K2…"

SMS

El gateway integra proveedores de SMS para despertar dispositivos, enviar comandos fuera de cobertura GPRS o notificar. Puedes enviar mensajes arbitrarios y consultar el historial con su estado de entrega.

#POST/sms
Envía un SMS
#GET/sms
Historial (por teléfono, IMEI, estado, rango)
#GET/sms/{id}
Detalle de un envío
#GET/sms-providers
Proveedores visibles para la key

Scopes: sms:read · sms:write

Enviar SMS

curl -X POST $BASE_URL/sms \
  -H "Authorization: Bearer rfsk_live_9f4K2…" \
  -H "Content-Type: application/json" \
  -d '{ "phone": "+50255551234", "text": "RESET#", "imei": "860000000000000" }'

Tenants y usuarios

Endpoints de administración de la plataforma, pensados para partners white-label. La creación y el borrado de tenants, y toda la gestión de usuarios, exigen una key Global; una key Per-Tenant solo lee su propio tenant.

#GET/tenants
Lista tenants
#POST/tenants
Crea tenant (Global)
#GET/tenants/{id}/devices
Dispositivos del tenant
#GET/users
Lista usuarios (Global)
#POST/users
Crea usuario (Global)
#POST/users/{id}/password
Cambia contraseña (Global)

Scopes: tenants:* · users:*

Documentación del API de RemaFleet

Autenticación

API keys rfsk_live_*

JWT de RemaFleet Auth

Scopes y permisos

Convenciones

Envelope de respuesta

Fechas

Paginación

Filtro por tenant

Manejo de errores

Servidor MCP — agentes de IA

Seguridad: opera con los permisos del usuario

Autenticación

Conectar tu agente

Catálogo de tools

Dispositivos

Flota en vivo

Historial y viajes

Compartir ubicación

Comandos

Multimedia

Video en vivo (HLS)

Alarmas

Reglas de alarma

Alarmas sintéticas

Notificaciones

Geocercas

Vehículos

Grupos de vehículos

Personal y conductores

Talleres y mantenimiento

Proyectos

CRM y cartera

Reportes

SMS

Tenants y usuarios

API keys `rfsk_live_*`