Ingress Server

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.