raffbot sonarAbrir dashboard →
Developer-first

Referencia de la API

Todos los endpoints REST de raffbot. Autenticación Bearer, errores estilo Stripe y paginación por cursor. Genera una clave en el dashboard para empezar a enviar posiciones y recibir eventos.

Base URL /v1

Autenticación Bearer con tu API key (sk_test_ / sk_live_). El prefijo determina el entorno: las claves de prueba y de producción ven datos aislados. Genera tus claves en la sección Claves.

Errores estilo Stripe: { "error": { "type", "message", "param" } }. type es invalid_request_error o api_error.

ingest Enviar posiciones (POST /positions).read Consultas GET de recursos.write Crear, actualizar y borrar recursos.

Posiciones

POST /positions Ingerir una posición o un lote ingest

Acepta un objeto único o un arreglo (máx. 1.000). Cada posición se normaliza y pasa por el pipeline: persiste, evalúa geocercas y encola entregas en una sola transacción. Si el dispositivo no existe, se auto-aprovisiona (salvo Teltonika). Responde 202 con el número de posiciones aceptadas.

Cuerpo

device_external_idstringrequeridoIdentificador del dispositivo (IMEI en Teltonika).
timestring (RFC 3339)requeridoTimestamp del fix. Es el único reloj que usa la lógica de geocercas.
latnumberrequeridoLatitud (-90 a 90).
lngnumberrequeridoLongitud (-180 a 180).
speed_kmhnumberopcionalVelocidad en km/h.
headingnumberopcionalRumbo en grados.
altitudenumberopcionalAltitud en metros.
accuracy_mnumberopcionalPrecisión horizontal en metros.
ignitionbooleanopcionalEstado de la ignición.
attributesobjectopcionalAtributos libres del fabricante.

Respuesta de ejemplo

{
  "accepted": 1
}
Pruébalo en el dashboard →

Dispositivos

GET /devices Listar dispositivos read

Devuelve hasta 200 dispositivos del entorno.

Respuesta de ejemplo

{
  "data": [
    {
      "id": "dev_...",
      "external_id": "vehicle-001",
      "label": "Camioneta 1",
      "protocol": "http"
    }
  ]
}
Pruébalo en el dashboard →

POST /devices Registrar un dispositivo write

Para HTTP/MQTT basta el auto-aprovisionamiento; para Teltonika es obligatorio porque el handshake resuelve la org por IMEI antes de que el dispositivo conecte. external_id duplicado responde 409.

Cuerpo

external_idstringrequeridoIdentificador único en el entorno (IMEI para Teltonika).
labelstringopcionalNombre legible.
protocolstringopcionalhttp | mqtt | teltonika.
metadataobjectopcionalMetadatos libres.

Respuesta de ejemplo

{
  "id": "dev_...",
  "external_id": "vehicle-001",
  "label": "Camioneta 1",
  "protocol": "http"
}
Pruébalo en el dashboard →

GET /devices/{id}/positions Histórico de posiciones read

Posiciones de un dispositivo ordenadas en el tiempo, con paginación por cursor (next_cursor si la página viene llena).

Parámetros de ruta

idstringrequeridoID del dispositivo (dev_...).

Parámetros de query

fromstring (RFC 3339)opcionalLímite inferior del rango.
tostring (RFC 3339)opcionalLímite superior del rango.
cursorstring (RFC 3339)opcionalCursor de la página siguiente (next_cursor).
limitintopcionalEntre 1 y 1000 (default 100).

Respuesta de ejemplo

{
  "data": [
    {
      "time": "2026-06-13T12:00:00Z",
      "lat": 19.4326,
      "lng": -99.1332,
      "speed_kmh": 42.5
    }
  ],
  "next_cursor": "2026-06-13T12:00:00Z"
}
Pruébalo en el dashboard →

Geocercas

GET /geofences Listar geocercas read

Hasta 500 geocercas del entorno.

Respuesta de ejemplo

{
  "data": [
    {
      "id": "gf_...",
      "name": "Almacén central",
      "type": "polygon",
      "metadata": {},
      "created_at": "2026-06-13T12:00:00Z",
      "updated_at": "2026-06-13T12:00:00Z"
    }
  ]
}
Pruébalo en el dashboard →

POST /geofences Crear geocerca write

Dos tipos. type=polygon requiere geometry (GeoJSON Polygon). type=circle requiere center y radius_m. El type es inmutable tras la creación.

Cuerpo

namestringrequeridoNombre de la geocerca.
typestringrequeridopolygon | circle (inmutable).
geometryGeoJSON PolygonopcionalRequerido si type=polygon.
center{ lat, lng }opcionalRequerido si type=circle.
radius_mnumberopcionalRadio en metros (>0). Requerido si type=circle.
metadataobjectopcionalMetadatos libres.

Respuesta de ejemplo

{
  "id": "gf_...",
  "name": "Almacén central",
  "type": "polygon",
  "metadata": {
    "zona": "norte"
  },
  "created_at": "2026-06-13T12:00:00Z",
  "updated_at": "2026-06-13T12:00:00Z"
}
Pruébalo en el dashboard →

GET /geofences/{id} Obtener geocerca read

Parámetros de ruta

idstringrequeridoID de la geocerca (gf_...).

Respuesta de ejemplo

{
  "id": "gf_...",
  "name": "Almacén central",
  "type": "polygon",
  "metadata": {},
  "created_at": "2026-06-13T12:00:00Z",
  "updated_at": "2026-06-13T12:00:00Z"
}
Pruébalo en el dashboard →

PATCH /geofences/{id} Actualizar geocerca write

Campos opcionales; solo se actualiza lo enviado. No se puede cambiar el type. geometry solo en polígonos; center/radius_m solo en círculos.

Parámetros de ruta

idstringrequeridoID de la geocerca.

Cuerpo

namestringopcionalNuevo nombre.
geometryGeoJSON PolygonopcionalSolo si la geocerca es polygon.
center{ lat, lng }opcionalSolo si la geocerca es circle.
radius_mnumberopcionalSolo si la geocerca es circle.
metadataobjectopcionalReemplaza los metadatos.

Respuesta de ejemplo

{
  "id": "gf_...",
  "name": "Almacén central (sur)",
  "type": "polygon",
  "metadata": {
    "zona": "sur"
  },
  "created_at": "2026-06-13T12:00:00Z",
  "updated_at": "2026-06-13T12:05:00Z"
}
Pruébalo en el dashboard →

DELETE /geofences/{id} Borrar geocerca write

Borrado lógico (soft delete).

Parámetros de ruta

idstringrequeridoID de la geocerca.

Respuesta de ejemplo

{
  "deleted": true
}
Pruébalo en el dashboard →

Suscripciones

GET /subscriptions Listar suscripciones read

Hasta 500. El signing_secret se muestra enmascarado (solo se revela completo al crear).

Respuesta de ejemplo

{
  "data": [
    {
      "id": "sub_...",
      "name": "Alertas de entrada",
      "trigger": "both",
      "active": true
    }
  ]
}
Pruébalo en el dashboard →

POST /subscriptions Crear suscripción write

Define qué eventos de geocerca generan un webhook. geofence_ids y device_ids vacíos = todos. dwell_seconds exige permanencia antes de confirmar; cooldown_seconds suprime entregas repetidas; min_speed_kmh bloquea solo enters. Esta es la única respuesta que revela el signing_secret completo.

Cuerpo

namestringrequeridoNombre de la suscripción.
triggerstringrequeridoenter | exit | both.
geofence_idsstring[]opcionalGeocercas que aplican; vacío = todas.
device_idsstring[]opcionalDispositivos que aplican; vacío = todos.
dwell_secondsintopcionalSegundos de permanencia para confirmar la transición.
cooldown_secondsintopcionalSupresión de entregas repetidas por tipo de evento.
min_speed_kmhnumberopcionalVelocidad mínima para disparar enters.
deliveryobjectrequerido{ type: "webhook", url, signing_secret? }. Si omites el secret se genera uno.
activebooleanopcionalActiva la suscripción (default true).

Respuesta de ejemplo

{
  "id": "sub_...",
  "name": "Alertas de entrada",
  "trigger": "both",
  "delivery": {
    "type": "webhook",
    "url": "https://example.com/webhook",
    "signing_secret": "whsec_..."
  },
  "active": true
}
Pruébalo en el dashboard →

GET /subscriptions/{id} Obtener suscripción read

Parámetros de ruta

idstringrequeridoID de la suscripción (sub_...).

Respuesta de ejemplo

{
  "id": "sub_...",
  "name": "Alertas de entrada",
  "trigger": "both",
  "active": true
}
Pruébalo en el dashboard →

PATCH /subscriptions/{id} Actualizar suscripción write

Solo se actualiza lo enviado. Si reenvías delivery sin signing_secret, se conserva el actual.

Parámetros de ruta

idstringrequeridoID de la suscripción.

Cuerpo

namestringopcionalNuevo nombre.
triggerstringopcionalenter | exit | both.
geofence_idsstring[]opcionalGeocercas que aplican.
device_idsstring[]opcionalDispositivos que aplican.
dwell_secondsintopcionalPermanencia para confirmar.
cooldown_secondsintopcionalSupresión de repetidos.
min_speed_kmhnumberopcionalVelocidad mínima para enters.
deliveryobjectopcionalReemplaza la config de entrega.
activebooleanopcionalActiva/pausa la suscripción.

Respuesta de ejemplo

{
  "id": "sub_...",
  "active": false,
  "cooldown_seconds": 600
}
Pruébalo en el dashboard →

DELETE /subscriptions/{id} Borrar suscripción write

Parámetros de ruta

idstringrequeridoID de la suscripción.

Respuesta de ejemplo

{
  "deleted": true
}
Pruébalo en el dashboard →

Eventos

GET /events Listar eventos de geocerca read

Eventos enter/exit generados por el pipeline, con filtros y paginación por cursor.

Parámetros de query

device_idstringopcionalFiltra por dispositivo.
geofence_idstringopcionalFiltra por geocerca.
typestringopcionalenter | exit.
fromstring (RFC 3339)opcionalInicio del rango.
tostring (RFC 3339)opcionalFin del rango.
cursorstring (RFC 3339)opcionalnext_cursor de la página anterior.
limitintopcionalEntre 1 y 1000 (default 100).

Respuesta de ejemplo

{
  "data": [
    {
      "id": "evt_...",
      "device_id": "dev_...",
      "geofence_id": "gf_...",
      "type": "enter",
      "position_time": "2026-06-13T12:00:00Z"
    }
  ],
  "next_cursor": "2026-06-13T12:00:00Z"
}
Pruébalo en el dashboard →

Entregas (webhooks)

GET /deliveries Listar entregas read

Outbox de webhooks. Reintentos con backoff exponencial; DLQ (status=dead) tras 6 intentos.

Parámetros de query

statusstringopcionalpending | delivered | failed | dead.
limitintopcionalEntre 1 y 1000 (default 100).

Respuesta de ejemplo

{
  "data": [
    {
      "id": "whd_...",
      "event_id": "evt_...",
      "status": "delivered",
      "attempt": 1,
      "response_status": 200,
      "created_at": "2026-06-13T12:00:00Z"
    }
  ]
}
Pruébalo en el dashboard →

GET /deliveries/{id} Detalle de entrega read

Incluye payload firmado y el log de cada intento.

Parámetros de ruta

idstringrequeridoID de la entrega (whd_...).

Respuesta de ejemplo

{
  "id": "whd_...",
  "event_id": "evt_...",
  "status": "delivered",
  "request_body": {},
  "attempts": [
    {
      "attempt": 1,
      "response_status": 200,
      "duration_ms": 120,
      "created_at": "2026-06-13T12:00:00Z"
    }
  ]
}
Pruébalo en el dashboard →

POST /deliveries/{id}/retry Reintentar entrega write

Re-encola una entrega failed/dead; el dispatcher la toma en su próximo poll.

Parámetros de ruta

idstringrequeridoID de la entrega.

Respuesta de ejemplo

{
  "id": "whd_...",
  "status": "pending"
}
Pruébalo en el dashboard →

Uso

GET /usage Uso del mes en curso read

Conteos del mes actual (UTC) para el entorno.

Respuesta de ejemplo

{
  "positions": 12500,
  "events": 84,
  "deliveries": 84
}
Pruébalo en el dashboard →

Simulaciones

GET /simulations Listar simulaciones read

Hasta 100 simulaciones del entorno.

Respuesta de ejemplo

{
  "data": [
    {
      "id": "sim_...",
      "device_external_id": "sim-001",
      "status": "running",
      "speed_factor": 60,
      "total_points": 20,
      "sent_points": 5
    }
  ]
}
Pruébalo en el dashboard →

POST /simulations Crear simulación write

Solo en el entorno de prueba (sk_test_). Envía exactamente uno: gpx (track GPX) o route (ruta lineal entre dos puntos). El dispositivo lleva siempre prefijo sim-. speed_factor acelera el tiempo simulado.

Cuerpo

device_external_idstringopcionalSe le antepone sim- si falta el prefijo. Si se omite, se genera.
gpxstringopcionalContenido GPX. Exactamente uno entre gpx y route.
routeobjectopcional{ from:{lat,lng}, to:{lat,lng}, points, interval_seconds }.
speed_factornumberopcionalAceleración del tiempo (0.1 a 600, default 1).

Respuesta de ejemplo

{
  "id": "sim_...",
  "device_external_id": "sim-001",
  "status": "running",
  "speed_factor": 60,
  "total_points": 20,
  "sent_points": 0
}
Pruébalo en el dashboard →

GET /simulations/{id} Obtener simulación read

Parámetros de ruta

idstringrequeridoID de la simulación (sim_...).

Respuesta de ejemplo

{
  "id": "sim_...",
  "device_external_id": "sim-001",
  "status": "running",
  "total_points": 20,
  "sent_points": 5
}
Pruébalo en el dashboard →

DELETE /simulations/{id} Cancelar simulación write

Cancela una simulación en curso.

Parámetros de ruta

idstringrequeridoID de la simulación.

Respuesta de ejemplo

{
  "id": "sim_...",
  "status": "cancelled"
}
Pruébalo en el dashboard →