Guía para integración de telemetría con OTIF

Flujo completo para proveedores de telemetría

Esta guía explica el flujo correcto para que un proveedor de telemetría integre sus dispositivos con OTIF usando in.otif.mx.

Documentación técnica base: 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 físico de cada dispositivo del proveedor, por ejemplo IMEI o numero de serie.

Conceptos clave

• provider_device_id: ID físico 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 telemetría.
• 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 físico 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 integración.
• 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 físico.
• OTIF devuelve un telemetry_device_id.

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

Paso 3. Reportar ubicación del dispositivo

Con el telemetry_device_id, reporta la ubicación 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"
}

Recomendación:

• Envía la ubicación con la frecuencia acordada en reporting_interval.
• Usa timestamps en formato ISO 8601 con zona horaria, preferentemente UTC.

Paso 4. Reportar botón de pánico, si aplica

Cuando el dispositivo o el operador genere un evento de pánico:

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 información del evento según el contrato del endpoint.

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

Los endpoints de motor no son para reportar automáticamente 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

Úsalos 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 físico se va a usar en otro embarque, primero desvinculado del embarque actual:

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

Headers:

X-API-Key: <API_KEY_DEL_PROVEEDOR>

Después 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 ubicación. Para reportar telemetría debes usar el telemetry_device_id generado por OTIF.
• Intentar ligar el mismo dispositivo físico a dos embarques al mismo tiempo. Primero hay que desvincularlo.
• Reportar motor encendido/apagado como estado automático 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 implementación

• 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.
• Validación completa hecha contra el ambiente real de in.otif.mx.