Skip to main content

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.
  • fleet_number: valor que identifica la unidad física donde está instalado el dispositivo. Se obtiene del mismo objeto de GET /shipments que el shipment_id seleccionado.
  • reporting_interval: intervalo esperado de reportes. Si OTIF no recibe datos dentro de ese intervalo, puede generar alertas por falta de señal.

Regla crítica: 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 y sus unidades con GET /shipments.
  • Elegir el objeto del embarque y la unidad física donde se instalará el dispositivo.
  • Tomar el shipment_id y el fleet_number correspondiente del mismo objeto.
  • Vincular el dispositivo físico con POST /devices, enviando ambos valores.
  • Guardar el telemetry_device_id que devuelve OTIF.
  • Reportar ubicación 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 objeto del embarque donde se instalará el dispositivo.
  • Elegir el campo de unidad de acuerdo con la ubicación física del dispositivo:
    • truck_fleet_number: si el dispositivo está instalado en el tractocamión.
    • trailer_fleet_number: si está instalado en el primer remolque.
    • trailer_fleet_number_2: si está instalado en el segundo remolque.
    • container: si está instalado en el primer contenedor.
    • container_2: si está instalado en el segundo contenedor.

El campo vehicle_plate se muestra únicamente como referencia y no debe usarse como fleet_number.

Ignora los campos cuyo valor sea null. Del mismo objeto seleccionado en la respuesta, guarda:

  • El valor de shipment_id.
  • El valor del campo de unidad elegido; ese valor será el fleet_number.

Ejemplo:

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

El shipment_id y el fleet_number deben salir siempre del mismo objeto del response.

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>",
  "fleet_number": "<VALOR_EXACTO_DE_LA_UNIDAD>",
  "provider_device_id": "<IMEI_O_ID_FISICO>",
  "reporting_interval": 15
}

En fleet_number, envía el valor exacto obtenido en el Paso 1, no el nombre del campo. Por ejemplo, envía el valor de truck_fleet_number, no el texto truck_fleet_number.

Resultado esperado:

  • OTIF crea la relación entre el embarque, la unidad 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.

Validaciones:

  • Si falta alguno de los campos requeridos (shipment_id, fleet_number, provider_device_id o reporting_interval), la API responde con 422.
  • Si el fleet_number no es válido para el shipment_id enviado, la API responde con 400.

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

Headers:

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

Úsalos solo cuando exista una solicitud explicita del centro de control.

Paso 6. Reportar detección de jammer, si aplica

Cuando el dispositivo genere un evento de jammer:

POST /devices/{telemetry_device_id}/jammer

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 7. 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 8. 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

  • Elegir el shipment_id de un objeto y el fleet_number de otro. Ambos valores deben salir del mismo objeto de GET /shipments.
  • Enviar el nombre del campo, como truck_fleet_number, en lugar de su valor exacto como fleet_number.
  • Usar vehicle_plate como fleet_number. Ese campo es únicamente una referencia.
  • Elegir un campo de unidad con valor null; esos campos deben ignorarse.
  • Elegir un fleet_number que no corresponde a la ubicación física del dispositivo.
  • Omitir alguno de los campos requeridos en POST /devices, lo que genera una respuesta 422.
  • Enviar un fleet_number inválido para el shipment_id, lo que genera una respuesta 400.
  • 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.
  • Objeto del embarque seleccionado según la ubicación física del dispositivo.
  • Campos con valor null ignorados.
  • vehicle_plate usado solo como referencia.
  • shipment_id y fleet_number obtenidos del mismo objeto de la respuesta de OTIF.
  • Valor exacto de la unidad enviado como fleet_number, no el nombre del campo.
  • POST /devices implementado con shipment_id, fleet_number, provider_device_id y reporting_interval.
  • Respuestas 422 por campos faltantes y 400 por fleet_number inválido contempladas.
  • 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.
No Comments
Back to top