Flujo completo para proveedores de telemetría

Tutorial de integración para proveedores de telemetría

Esta guía explica el flujo operativo recomendado para integrar un proveedor de telemetría con OTIF por medio de in.otif.mx.

• URL de documentación técnica: https://in.otif.mx/docs/v1
• Base URL productiva: https://in.otif.mx/api/v1
• Autenticación requerida en todos los endpoints: header X-API-Key

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

Flujo general

• Paso 1: consultar embarques activos con GET /shipments.
• Paso 2: elegir el shipment_id del embarque que se va a monitorear.
• Paso 3: vincular el dispositivo físico con POST /devices.
• Paso 4: guardar el telemetry_device_id que regresa OTIF.
• Paso 5: reportar ubicaciones y eventos usando ese telemetry_device_id.
• Paso 6: consultar eventos guardados cuando se necesite validar la integración.
• Paso 7: desvincular el dispositivo con DELETE /devices/{telemetry_device_id} antes de reutilizarlo en otro embarque.

Conceptos clave

• provider_device_id: identificador del dispositivo físico en el sistema del proveedor. Normalmente es IMEI, número de serie o ID interno del proveedor.
• telemetry_device_id: identificador generado por OTIF al vincular el dispositivo. Este ID se usa en los endpoints de reporte.
• reporting_interval: frecuencia esperada de reporte, en minutos. Si OTIF no recibe datos dentro de este intervalo, puede disparar alertas de falta de señal.
• Un dispositivo físico solo puede estar vinculado a un embarque activo a la vez.
• Para reutilizar un dispositivo en otro embarque, primero hay que desvincularlo del embarque anterior.

Paso 1: Obtener embarques activos

• Llamar GET /shipments para obtener los embarques activos asignados al proveedor.
• Tomar el shipment_id del embarque correcto.
• Usar vehicle_plate y fleet_number para validar que el embarque corresponde a la unidad esperada.

curl --request GET 'https://in.otif.mx/api/v1/shipments' \
  --header 'X-API-Key: <API_KEY_DEL_PROVEEDOR>'

Respuesta esperada:

{
  "success": true,
  "data": [
    {
      "shipment_id": "S-1234567890",
      "vehicle_plate": "ABC123A",
      "fleet_number": "FLEET01"
    }
  ],
  "status_code": 200
}

Paso 2: Vincular el dispositivo físico al embarque

• Llamar POST /devices con el shipment_id obtenido en el paso anterior.
• Enviar el ID físico del dispositivo como provider_device_id.
• Definir reporting_interval en minutos.
• Guardar el telemetry_device_id de la respuesta. Es obligatorio para reportar telemetría.

curl --request POST 'https://in.otif.mx/api/v1/devices' \
  --header 'X-API-Key: <API_KEY_DEL_PROVEEDOR>' \
  --header 'Content-Type: application/json' \
  --data '{
    "shipment_id": "S-1234567890",
    "provider_device_id": "PROVIDER-DEVICE-001",
    "reporting_interval": 15
  }'

Respuesta esperada:

{
  "success": true,
  "data": {
    "telemetry_device_id": "550e8400-e29b-41d4-a716-446655440000"
  },
  "status_code": 201
}

Paso 3: Verificar dispositivos vinculados

• Llamar GET /devices para consultar los dispositivos actualmente vinculados y activos.
• Confirmar que el provider_device_id, shipment_id y telemetry_device_id correspondan al embarque esperado.

curl --request GET 'https://in.otif.mx/api/v1/devices' \
  --header 'X-API-Key: <API_KEY_DEL_PROVEEDOR>'

Paso 4: Reportar ubicación del dispositivo

• Llamar POST /devices/{telemetry_device_id}/localization.
• Usar el telemetry_device_id que regresó OTIF en el paso 2.
• Enviar position_date en formato ISO 8601 UTC.
• Enviar latitud y longitud reales del dispositivo.
• Incluir is_motor_on con el estado reportado por el proveedor.

curl --request POST 'https://in.otif.mx/api/v1/devices/550e8400-e29b-41d4-a716-446655440000/localization' \
  --header 'X-API-Key: <API_KEY_DEL_PROVEEDOR>' \
  --header 'Content-Type: application/json' \
  --data '{
    "device_type": "gps",
    "position_date": "2026-01-01T10:00:00.000Z",
    "latitude": 19.432608,
    "longitude": -99.133209,
    "altitude": 2240,
    "speed_kmh": 42.5,
    "angle": 180,
    "temperature_celsius": 4.2,
    "odometer_km": 10524.7,
    "is_motor_on": true,
    "battery_percentage": 87,
    "battery_voltage": 12.4,
    "accuracy_meters": 8
  }'

Respuesta esperada:

{
  "success": true,
  "data": {
    "telemetry_device_id": "550e8400-e29b-41d4-a716-446655440000",
    "event_id": "123"
  },
  "status_code": 201
}

Paso 5: Reportar botón de pánico

• Llamar POST /devices/{telemetry_device_id}/panic-button cuando el dispositivo o conductor active una alerta de pánico.
• Enviar la misma estructura base de ubicación para que OTIF registre dónde ocurrió el evento.
• Incluir is_motor_on.

curl --request POST 'https://in.otif.mx/api/v1/devices/550e8400-e29b-41d4-a716-446655440000/panic-button' \
  --header 'X-API-Key: <API_KEY_DEL_PROVEEDOR>' \
  --header 'Content-Type: application/json' \
  --data '{
    "device_type": "gps",
    "position_date": "2026-01-01T10:05:00.000Z",
    "latitude": 19.432608,
    "longitude": -99.133209,
    "altitude": 2240,
    "speed_kmh": 0,
    "angle": 180,
    "temperature_celsius": 4.2,
    "odometer_km": 10525.1,
    "is_motor_on": true
  }'

Paso 6: Reportar solicitudes de apagado o encendido de motor

Estos endpoints no son para reportar el estado automático del motor en cada posición. Son para reportar solicitudes del centro de control al conductor o a la unidad.

• Usar POST /devices/{telemetry_device_id}/motor-off cuando el centro de control solicite apagar motor.
• Usar POST /devices/{telemetry_device_id}/motor-on cuando el centro de control solicite encender motor.
• Enviar is_motor_on con el estado solicitado en el evento.

Ejemplo de solicitud de apagado:

curl --request POST 'https://in.otif.mx/api/v1/devices/550e8400-e29b-41d4-a716-446655440000/motor-off' \
  --header 'X-API-Key: <API_KEY_DEL_PROVEEDOR>' \
  --header 'Content-Type: application/json' \
  --data '{
    "device_type": "gps",
    "position_date": "2026-01-01T10:10:00.000Z",
    "latitude": 19.432608,
    "longitude": -99.133209,
    "altitude": 2240,
    "speed_kmh": 0,
    "angle": 180,
    "temperature_celsius": 4.2,
    "odometer_km": 10525.2,
    "is_motor_on": false
  }'

Paso 7: Consultar eventos guardados

• Llamar GET /devices/{telemetry_device_id}/events para revisar eventos persistidos en OTIF.
• Usar este endpoint para validar que la integración esté reportando correctamente.

curl --request GET 'https://in.otif.mx/api/v1/devices/550e8400-e29b-41d4-a716-446655440000/events' \
  --header 'X-API-Key: <API_KEY_DEL_PROVEEDOR>'

Paso 8: Desvincular el dispositivo antes de reutilizarlo

• Si el mismo dispositivo físico se usará en otro embarque, primero llamar DELETE /devices/{telemetry_device_id}.
• Después de desvincularlo, volver a ejecutar POST /devices con el nuevo shipment_id.
• Si el dispositivo no se usará en otro embarque, puede permanecer vinculado al embarque actual.

curl --request DELETE 'https://in.otif.mx/api/v1/devices/550e8400-e29b-41d4-a716-446655440000' \
  --header 'X-API-Key: <API_KEY_DEL_PROVEEDOR>'

Checklist de implementación

• El proveedor ya tiene su X-API-Key activa.
• El proveedor puede consultar GET /shipments y ver embarques activos.
• El proveedor vincula cada dispositivo con POST /devices.
• El proveedor guarda el telemetry_device_id de OTIF.
• El proveedor reporta ubicaciones a /localization usando telemetry_device_id.
• El proveedor reporta botón de pánico solo cuando ocurra una alerta real.
• El proveedor reporta motor-on y motor-off solo como solicitudes del centro de control.
• El proveedor desvincula el dispositivo antes de usarlo en otro embarque.

Errores comunes

• Usar provider_device_id en la URL de eventos. La URL debe usar telemetry_device_id.
• Intentar vincular el mismo dispositivo físico a dos embarques al mismo tiempo.
• No guardar el telemetry_device_id que devuelve OTIF.
• Enviar eventos sin X-API-Key.
• Enviar fechas locales sin zona horaria. Preferir UTC: 2026-01-01T10:00:00.000Z.
• Usar motor-on o motor-off para reportar estado automático del motor en cada posición.