Skip to main content

Flujo completo para proveedores de telemetria

Flujo completo para proveedores de telemetria

Esta guia explica el flujo correcto para que un proveedor de telemetria integre sus dispositivos con OTIF usando in.otif.mx.

Documentacion tecnica base: https://in.otif.mx/docs/v1

Antes de empezar

  • Solicita a OTIF tu API Key.
  • Usa la API Key en todos los requests con el header X-API-Key.
  • Usa la base URL de API: https://in.otif.mx/api/v1.
  • Ten identificado el ID fisico de cada dispositivo del proveedor, por ejemplo IMEI, numero de serie o identificador interno.

Conceptos clave

  • provider_device_id: ID fisico del dispositivo del proveedor. Lo define el proveedor.
  • telemetry_device_id: ID generado por OTIF al vincular un dispositivo con un embarque. Este ID se usa para reportar telemetria.
  • shipment_id: ID del embarque en OTIF. Se obtiene desde GET /shipments.
  • reporting_interval: intervalo esperado de reportes. Si OTIF no recibe datos dentro de ese intervalo, puede generar alertas por falta de senal.

Regla critica: un dispositivo fisico solo puede estar vinculado a un embarque a la vez. Para reutilizarlo en otro embarque, primero debe desvincularse.

Flujo general

  • Obtener embarques activos con GET /shipments.
  • Elegir el shipment_id al que se le instalara el dispositivo.
  • Vincular el dispositivo fisico con POST /devices.
  • Guardar el telemetry_device_id que devuelve OTIF.
  • Reportar ubicacion y eventos usando el telemetry_device_id.
  • Desvincular el dispositivo con DELETE /devices/{telemetry_device_id} antes de usarlo en otro embarque.

Paso 1. Obtener embarques disponibles

Haz una llamada a:

GET https://in.otif.mx/api/v1/shipments

Headers:

X-API-Key: <API_KEY_DEL_PROVEEDOR>

Objetivo:

  • Obtener la lista de embarques disponibles para tu integracion.
  • Identificar el shipment_id del embarque donde se instalara el dispositivo.

Ejemplo:

curl -X GET "https://in.otif.mx/api/v1/shipments" -H "X-API-Key: <API_KEY_DEL_PROVEEDOR>"

Del response, guarda el shipment_id del embarque que vas a rastrear.

Paso 2. Vincular el dispositivo al embarque

Haz una llamada a:

POST https://in.otif.mx/api/v1/devices

Headers:

X-API-Key: <API_KEY_DEL_PROVEEDOR> Content-Type: application/json

Body de ejemplo:

{
  "shipment_id": "<SHIPMENT_ID>",
  "provider_device_id": "<IMEI_O_ID_FISICO>",
  "reporting_interval": 15
}

Resultado esperado:

  • OTIF crea la relacion entre el embarque y el dispositivo fisico.
  • OTIF devuelve un telemetry_device_id.

Guarda ese telemetry_device_id. Es el identificador que debes usar en los siguientes reportes.

Paso 3. Reportar ubicacion del dispositivo

Con el telemetry_device_id, reporta la ubicacion del dispositivo:

POST https://in.otif.mx/api/v1/devices/{telemetry_device_id}/localization

Headers:

X-API-Key: <API_KEY_DEL_PROVEEDOR> Content-Type: application/json

Body de ejemplo:

{
  "latitude": 25.6866,
  "longitude": -100.3161,
  "event_timestamp": "2026-08-21T19:00:00Z"
}

Recomendacion:

  • Envia la ubicacion con la frecuencia acordada en reporting_interval.
  • Usa timestamps en formato ISO 8601 con zona horaria, preferentemente UTC.

Paso 4. Reportar boton de panico, si aplica

Cuando el dispositivo o el operador genere un evento de panico:

POST https://in.otif.mx/api/v1/devices/{telemetry_device_id}/panic-button

Headers:

X-API-Key: <API_KEY_DEL_PROVEEDOR> Content-Type: application/json

Incluye la informacion del evento segun el contrato del endpoint.

Paso 5. Reportar solicitudes de motor encendido/apagado, si aplica

Los endpoints de motor no son para reportar automaticamente si el motor esta encendido o apagado.

Se usan para reportar solicitudes hechas por el centro de control al conductor, por ejemplo:

  • El centro de control solicita apagar motor.
  • El proveedor reporta esa solicitud a OTIF con el endpoint correspondiente.

Endpoints:

  • POST /devices/{telemetry_device_id}/motor-off
  • POST /devices/{telemetry_device_id}/motor-on

Usalos solo cuando exista una solicitud explicita del centro de control.

Paso 6. Consultar eventos del dispositivo

Para revisar eventos asociados al dispositivo:

GET https://in.otif.mx/api/v1/devices/{telemetry_device_id}/events

Headers:

X-API-Key: <API_KEY_DEL_PROVEEDOR>

Esto sirve para validar que OTIF este recibiendo y registrando los eventos del dispositivo.

Paso 7. Desvincular el dispositivo antes de reutilizarlo

Si el dispositivo fisico se va a usar en otro embarque, primero desvinculalo del embarque actual:

DELETE https://in.otif.mx/api/v1/devices/{telemetry_device_id}

Headers:

X-API-Key: <API_KEY_DEL_PROVEEDOR>

Despues de desvincularlo, puedes repetir el Paso 2 para ligar el mismo provider_device_id a otro shipment_id.

Si el dispositivo no se necesita en otro embarque, puede permanecer vinculado indefinidamente.

Errores comunes

  • Usar el provider_device_id para reportar ubicacion. Para reportar telemetria debes usar el telemetry_device_id generado por OTIF.
  • Intentar ligar el mismo dispositivo fisico a dos embarques al mismo tiempo. Primero hay que desvincularlo.
  • Reportar motor encendido/apagado como estado automatico del motor. Esos endpoints son para solicitudes del centro de control.
  • No respetar el reporting_interval, lo que puede generar alertas por falta de reporte.

Checklist de implementacion

  • API Key configurada en el header X-API-Key.
  • GET /shipments implementado.
  • shipment_id seleccionado desde la respuesta de OTIF.
  • POST /devices implementado para vincular dispositivo.
  • telemetry_device_id guardado en el sistema del proveedor.
  • POST /devices/{telemetry_device_id}/localization implementado.
  • Eventos adicionales implementados solo si aplican.
  • DELETE /devices/{telemetry_device_id} implementado para reutilizar dispositivos.
  • Validacion completa hecha contra el ambiente real de in.otif.mx.
Back to top