Flujo completo para proveedores de telemetria

Flujo completo para proveedores de telemetriatelemetría

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

DocumentacionDocumentación tecnicatécnica 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 fisicofísico de cada dispositivo del proveedor, por ejemplo IMEI,IMEI o numero de serie o identificador interno.serie.

Conceptos clave

• provider_device_id: ID fisicofí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 telemetria.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 fisicofí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 integracion.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 fisico.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 ubicacionubicación del dispositivo

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

Recomendacion:Recomendación:

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

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

Cuando el dispositivo o el operador genere un evento de panico: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 informacioninformación del evento segunsegún el contrato del endpoint.

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

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

UsalosÚ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 fisicofísico se va a usar en otro embarque, primero desvinculalodesvinculado del embarque actual:

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

Headers:

X-API-Key: <API_KEY_DEL_PROVEEDOR>

DespuesDespué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 ubicacion.ubicación. Para reportar telemetriatelemetría debes usar el telemetry_device_id generado por OTIF.
• Intentar ligar el mismo dispositivo fisicofísico a dos embarques al mismo tiempo. Primero hay que desvincularlo.
• Reportar motor encendido/apagado como estado automaticoautomá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 implementacionimplementació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.
• ValidacionValidación completa hecha contra el ambiente real de in.otif.mx.