Documentación oficial de la API de Telemetría para la ingesta e integración de dispositivos GPS en GOxT Cargo.

Documentación API de Telemetría

La API de Telemetría de GOxT Cargo permite integrar dispositivos GPS y enviar eventos de posicionamiento y sensores en tiempo real hacia la plataforma.

Información General

Base URL: https://telemetria.goxt.io
Endpoint: /api/v1/telemetry/ingest
Método HTTP: POST

Autenticación y Headers

La API requiere autenticación mediante una API Key enviada en los encabezados HTTP de la petición.

Header	Tipo	Descripción
`x-api-key`	`string`	Token de autenticación asignado a tu workspace

Obtener el Token de Autenticación (`x-api-key`)

Para obtener el token de autenticación, sigue estos pasos dentro de la plataforma:

Iniciar sesión

Accede a https://cargo.goxt.io/login con tus credenciales.

Ir a Configuraciones

Ingresa a la sección de Configuraciones desde el menú de navegación.

Sub-sección API

Navega a la sub-sección API.

Seleccionar Telemetría

Selecciona la opción Telemetría.

Copiar Key

Copia la API Key generada.

Obtención de API Key para Telemetría en GOxT Cargo

Estructura del Body (JSON)

Campos Obligatorios

¡IMPORTANTE!: Para cada país utilizar formato UTC en el campo de fecha. Ej. Chile: 2026-07-08T16:00:00Z.

Campo	Tipo	Descripción
`date`	`string (ISO 8601 UTC)`	Fecha y hora de la lectura en formato UTC
`plate`	`string`	Identificador único del dispositivo (Patente o patente del vehículo)
`lat`	`number`	Latitud geográfica
`lng`	`number`	Longitud geográfica

Campos Opcionales

Campo	Tipo	Descripción
`imei`	`string`	Identificador único del dispositivo GPS
`speed`	`number`	Velocidad en km/h
`direction`	`number`	Dirección u orientación en grados ($0^\circ - 360^\circ$)
`battery`	`number`	Nivel de batería
`temperature`	`number`	Temperatura sensor 1
`temperature2`	`number`	Temperatura sensor 2
`temperature3`	`number`	Temperatura sensor 3
`humidity`	`number`	Porcentaje de humedad (%)
`ignite`	`number`	Estado de encendido ($1 =$ encendido, $0 =$ apagado)
`ap`	`number`	Apertura de puertas ($1 =$ abierto, $0 =$ cerrado)
`panic`	`number`	Botón de pánico ($1 =$ activo, $0 =$ inactivo)
`activity_number`	`string`	Número de actividad o viaje asociado
`odometer`	`number`	Lectura del odómetro
`q_satellite`	`number`	Cantidad de satélites sintonizados
`quality_signal`	`number`	Calidad de la señal de red
`vdop`	`number`	Vertical Dilution of Precision
`pdop`	`number`	Position Dilution of Precision
`hdop`	`number`	Horizontal Dilution of Precision
`height`	`number`	Altitud sobre el nivel del mar
`eje_x`	`number`	Aceleración en eje X
`eje_y`	`number`	Aceleración en eje Y
`eje_z`	`number`	Aceleración en eje Z

Ejemplo de Petición

{
  "x-api-key": "123456789"
}

Body

{
  "date": "2026-03-31T19:50:00-05:00",
  "imei": "1234567890123",
  "plate": "ABCD-12",
  "lat": -33.456,
  "lng": -70.648,
  "speed": 89,
  "direction": 180,
  "battery": 12.4,
  "temperature": 4.5,
  "temperature2": 0.0,
  "temperature3": 0.0,
  "humidity": 60,
  "ignite": 1,
  "ap": 1,
  "panic": 0,
  "activity_number": "AC-9821",
  "odometer": 15420.5,
  "q_satellite": 14,
  "quality_signal": 99,
  "vdop": 1.2,
  "pdop": 1.5,
  "hdop": 0.8,
  "height": 540,
  "eje_x": 0.05,
  "eje_y": 0.02,
  "eje_z": 9.81
}

Respuestas de la API

Éxito — `200 OK`

Se retorna cuando los datos de telemetría son procesados y almacenados con éxito.

{
  "success": true,
  "message": "1 puntos guardados exitosamente"
}

Payload Inválido — `400 Bad Request`

Se retorna cuando el body no cumple con el esquema de validación esperado.

{
  "success": false,
  "message": "Formato de payload inválido",
  "errors": {
    "_errors": [],
    "imei": { "_errors": ["IMEI es requerido"] },
    "lat": { "_errors": ["Expected number, received string"] }
  }
}

No Autorizado — `401 Unauthorized`

Se retorna cuando no se provee la API Key o la key ingresada es inválida o se encuentra inactiva.

{
  "success": false,
  "message": "No autorizado. Se requiere API Key de Workspace."
}

{
  "success": false,
  "message": "No autorizado. Credenciales inválidas o inactivadas."
}

Acceso Denegado — `403 Forbidden`

Se retorna cuando el middleware de autenticación no puede extraer el workspace_id.

{
  "success": false,
  "message": "Acceso denegado: Workspace ID requerido"
}

Error Interno — `500 Internal Server Error`

Se retorna ante fallas no controladas en el servidor al consultar o guardar la telemetría.

{
  "success": false,
  "message": "Error interno consultando telemetría",
  "error": "Descripción del error técnico"
}

Integración GPS