Listar Recorrido/Eventos GPS

Permite obtener el listado de registros de recorrido y eventos GPS (rastreo de ubicación, eventos de dispositivo, entre otros) asociados a los vendedores registrados en el sistema de forma paginada. Este endpoint soporta filtros por vendedor y fecha de creación, así como ordenamiento configurable.

Método: GET

Endpoint

https://api.ventasremotas.com/v1/gps

Nota

Es necesario el envío del token de acceso Subscription-Key para hacer uso de este endpoint. Para ver cómo generar el token, vea Activación Suscripción a RSales API.

Encabezados de la solicitud

Header	Valor	Descripción	Requerido
Accept	application/json	Indica que la respuesta debe estar en formato JSON	No
Subscription-Key	{subscription_key}	Clave de suscripción para acceder a la API	Sí
Authorization	Bearer {access_token}	Token de acceso obtenido del endpoint /token	Sí

---

Parámetros de Consulta (Query Parameters)

Todos los parámetros son opcionales. Si no se especifican, se retornan todos los registros de recorrido GPS con la paginación por defecto.

Filtros

Parámetro	Tipo	Descripción
seller_id	String	Filtra por código exacto de vendedor. Longitud máxima: 18 caracteres.
created_from	Date	Retorna registros cuya fecha de creación es mayor o igual a este valor. Formato: YYYY-MM-DD.

Ordenamiento

Parámetro	Tipo	Descripción
sort	String	Campo y dirección de ordenamiento. Por defecto: fecha de creación descendente.

Campos de ordenamiento disponibles

Valor	Descripción
created_at	Ordena por fecha de creación ascendente (ASC)
-created_at	Ordena por fecha de creación descendente (DESC)

Ordenamiento por defecto

Si no se especifica el parámetro sort, los resultados se ordenan por fecha de creación descendente (más recientes primero).

Paginación

Parámetro	Tipo	Por defecto	Restricciones	Descripción
page	Number	1	Mínimo: 1	Número de página (1-indexed)
limit	Number	100	Mínimo: 1, Máximo: 1000	Cantidad de resultados por página

---

Ejemplo de Solicitud

Petición básica (sin filtros)

curl -X GET "https://api.ventasremotas.com/v1/gps" \
  -H "Accept: application/json" \
  -H "Subscription-Key: tu-subscription-key" \
  -H "Authorization: Bearer tu-access-token"

Petición con filtro por vendedor

curl -X GET "https://api.ventasremotas.com/v1/gps?seller_id=V001" \
  -H "Accept: application/json" \
  -H "Subscription-Key: tu-subscription-key" \
  -H "Authorization: Bearer tu-access-token"

Petición con filtro de fecha y paginación

curl -X GET "https://api.ventasremotas.com/v1/gps?created_from=2024-01-01&page=1&limit=50" \
  -H "Accept: application/json" \
  -H "Subscription-Key: tu-subscription-key" \
  -H "Authorization: Bearer tu-access-token"

Petición con múltiples filtros y ordenamiento

curl -X GET "https://api.ventasremotas.com/v1/gps?seller_id=V001&created_from=2024-06-01&sort=-created_at&limit=200" \
  -H "Accept: application/json" \
  -H "Subscription-Key: tu-subscription-key" \
  -H "Authorization: Bearer tu-access-token"

---

Ejemplo de Respuesta

200 - OK

{
    "data": [
        {
            "seller_id": "V001",
            "created_at": "2025-03-15T08:30:00",
            "transmitted_at": "2025-03-15T08:30:05",
            "transaction_type": "RASTREO GPS [INICIO SESION]",
            "latitude": 4.710989,
            "longitude": -74.072092,
            "address": "Calle 100 #15-20, Bogotá",
            "precision": 12.5,
            "battery": 85.0,
            "speed": null,
            "transmitted": "Y",
            "imei": "354912094578623"
        },
        {
            "seller_id": "V001",
            "created_at": "2025-03-15T09:15:30",
            "transmitted_at": "2025-03-15T09:15:35",
            "transaction_type": "RASTREO GPS [ACTUALIZACION]",
            "latitude": 4.685742,
            "longitude": -74.054831,
            "address": "Carrera 7 #45-10, Bogotá",
            "precision": 8.3,
            "battery": 78.0,
            "speed": null,
            "transmitted": "Y",
            "imei": "354912094578623"
        },
        {
            "seller_id": "V001",
            "created_at": "2025-03-15T10:45:00",
            "transmitted_at": "2025-03-15T10:45:02",
            "transaction_type": "Evento [BATERÍA INSUFICIENTE]",
            "latitude": 4.694712,
            "longitude": -74.061523,
            "address": "Avenida Caracas #30-15, Bogotá",
            "precision": 5.1,
            "battery": 15.0,
            "speed": null,
            "transmitted": "Y",
            "imei": "354912094578623"
        }
    ],
    "meta": {
        "totalItems": 245,
        "itemCount": 3,
        "itemsPerPage": 100,
        "totalPages": 3,
        "currentPage": 1
    },
    "links": {
        "self": "https://api.ventasremotas.com/v1/gps?page=1&limit=100",
        "first": "https://api.ventasremotas.com/v1/gps?page=1&limit=100",
        "prev": null,
        "next": "https://api.ventasremotas.com/v1/gps?page=2&limit=100",
        "last": "https://api.ventasremotas.com/v1/gps?page=3&limit=100"
    }
}

Descripción de campos de respuesta

Objeto data[] (Registro GPS)

Cada elemento del array data contiene los siguientes campos:

Campo	Tipo	Descripción
seller_id	String	Código del vendedor asociado al registro GPS
created_at	DateTime	Fecha y hora de creación del registro. Formato: yyyy-MM-ddTHH:mm:ss
transmitted_at	DateTime	Fecha y hora de transmisión del registro. Formato: yyyy-MM-ddTHH:mm:ss
transaction_type	String	Tipo de transacción o evento GPS (ver tabla de tipos de transacción)
latitude	Number	Latitud de la ubicación registrada (puede ser null)
longitude	Number	Longitud de la ubicación registrada (puede ser null)
address	String	Dirección asociada a la ubicación (puede ser null)
precision	Number	Precisión de la señal GPS en metros (puede ser null)
battery	Number	Nivel de batería del dispositivo en porcentaje (puede ser null)
speed	String	Velocidad registrada al momento de la captura (puede ser null)
transmitted	String	Indica si el recorrido/evento fue descargado a la interfaz (puede ser null)
imei	String	Código IMEI del dispositivo móvil (puede ser null)

Tipos de transacción (transaction_type)

El campo transaction_type es un valor calculado que describe el tipo de evento GPS registrado. Los posibles valores son:

Rastreo GPS:

Valor	Descripción
RASTREO GPS [INICIO SESION]	El vendedor inició sesión en la aplicación móvil
RASTREO GPS [FIN SESION]	El vendedor cerró sesión en la aplicación móvil
RASTREO GPS [MANUAL]	Registro de ubicación realizado manualmente
RASTREO GPS [ACTUALIZACION]	Actualización automática de ubicación
RASTREO GPS [GPS ENCENDIO]	El GPS del dispositivo fue activado
RASTREO GPS [GPS APAGADO]	El GPS del dispositivo fue desactivado
RASTREO GPS [RESTAURAR DATOS (MOVIL)]	Restauración de datos desde el dispositivo móvil
RASTREO GPS [RESTAURAR DATOS (WEB)]	Restauración de datos desde la plataforma web
RASTREO GPS	Registro de rastreo GPS genérico

Eventos de dispositivo:

Valor	Descripción
Evento [DISPOSITIVO ENCENDIO]	El dispositivo móvil fue encendido
Evento [DISPOSITIVO APAGADO]	El dispositivo móvil fue apagado
Evento [SIN PERMISOS DE UBICACIÓN]	El dispositivo no tiene permisos de ubicación activados
Evento [MODO AVIÓN ENCENDIDO]	El modo avión fue activado
Evento [MODO AVIÓN APAGADO]	El modo avión fue desactivado
Evento [CARGADOR CONECTADO]	El cargador fue conectado al dispositivo
Evento [CARGADOR DESCONECTADO]	El cargador fue desconectado del dispositivo
Evento [BATERÍA CON SUFICIENTE CARGA]	La batería del dispositivo tiene carga suficiente
Evento [BATERÍA INSUFICIENTE]	La batería del dispositivo tiene carga insuficiente
Evento [FECHA/HORA MODIFICADA]	La fecha u hora del dispositivo fue modificada
Evento [ZONA HORARIA MODIFICADA]	La zona horaria del dispositivo fue modificada

Eventos de alertas:

Valor	Descripción
Evento [EXCESO DE VELOCIDAD]	Se detectó exceso de velocidad en el dispositivo
Evento [ALERTA DE ALEJAMIENTO (SALIDA)]	El vendedor salió del rango de distancia permitido
Evento [ALERTA DE ALEJAMIENTO (REGRESO)]	El vendedor regresó al rango de distancia permitido
Evento [ALERTA DE GEOCERCA (ENTRADA)]	El vendedor ingresó a una zona de geocerca
Evento [ALERTA DE GEOCERCA (SALIDA)]	El vendedor salió de una zona de geocerca
Evento [ALERTA DE GEOCERCA (SIN SALIDA)]	Alerta de que el vendedor no ha salido de la geocerca
Evento [ALERTA DE GEOCERCA (SIN INGRESO)]	Alerta de que el vendedor no ha ingresado a la geocerca

Eventos de sesión:

Valor	Descripción
[INICIO SESION PRIMERA VEZ ACTIVADO]	Primer inicio de sesión activado en el dispositivo
[INTENTO INICIO SESION BLOQUEADO]	Intento de inicio de sesión fue bloqueado

Objeto meta (Metadatos de paginación)

Campo	Tipo	Descripción
totalItems	Number	Cantidad total de registros GPS que coinciden con los filtros
itemCount	Number	Cantidad de registros en la página actual
itemsPerPage	Number	Cantidad de items por página solicitados
totalPages	Number	Total de páginas disponibles
currentPage	Number	Número de la página actual

Objeto links (Enlaces de navegación)

Campo	Tipo	Descripción
self	String	URL de la página actual
first	String	URL de la primera página
prev	String	URL de la página anterior (null si es la primera página)
next	String	URL de la página siguiente (null si es la última página)
last	String	URL de la última página

Status 400

Los errores de validación de parámetros de consulta retornan un array de errores, donde cada error indica el parámetro problemático:

Filtro no válido

{
    "statusCode": 400,
    "errors": [
        {
            "param": "invalid_param",
            "message": "The field is not a valid filter parameter"
        }
    ]
}

Valor de filtro vacío

{
    "statusCode": 400,
    "errors": [
        {
            "param": "seller_id",
            "message": "Value must not be empty"
        }
    ]
}

Fecha con formato inválido

{
    "statusCode": 400,
    "errors": [
        {
            "param": "created_from",
            "message": "Value '15-01-2024' is not a valid date (expected format: YYYY-MM-DD)"
        }
    ]
}

Valor excede longitud máxima

{
    "statusCode": 400,
    "errors": [
        {
            "param": "seller_id",
            "message": "Value exceeds maximum length of 18"
        }
    ]
}

Campo de ordenamiento inválido

{
    "statusCode": 400,
    "errors": [
        {
            "param": "sort",
            "message": "The field 'invalid_field' is not a valid sort field."
        }
    ]
}

Parámetro sort vacío

{
    "statusCode": 400,
    "errors": [
        {
            "param": "sort",
            "message": "The parameter must not be empty"
        }
    ]
}

Parámetro de paginación inválido

{
    "statusCode": 400,
    "errors": [
        {
            "param": "page",
            "message": "The parameter must be a valid integer"
        }
    ]
}

Página menor al mínimo

{
    "statusCode": 400,
    "errors": [
        {
            "param": "page",
            "message": "The parameter must be greater than or equal to 1"
        }
    ]
}

Límite excede el máximo

{
    "statusCode": 400,
    "errors": [
        {
            "param": "limit",
            "message": "The parameter must be less than or equal to 1000"
        }
    ]
}

Límite vacío

{
    "statusCode": 400,
    "errors": [
        {
            "param": "limit",
            "message": "The parameter must not be empty"
        }
    ]
}

Errores múltiples

El endpoint puede retornar múltiples errores de validación en una sola respuesta. Por ejemplo, si se envía un filtro inválido y un parámetro de paginación incorrecto al mismo tiempo, ambos errores aparecerán en el array de errors.

Tabla resumen de errores de validación

Errores de filtros:

Error	Aplica a
The field is not a valid filter parameter	Cualquier parámetro no reconocido
Value must not be empty	seller_id
Value 'X' is not a valid date (expected format: YYYY-MM-DD)	created_from
Value exceeds maximum length of 18	seller_id

Errores de ordenamiento:

Error	Aplica a
The parameter must not be empty	sort
The field 'X' is not a valid sort field.	sort

Errores de paginación:

Error	Aplica a
The parameter must not be empty	page, limit
The parameter must be a valid integer	page, limit
The parameter must be greater than or equal to 1	page, limit
The parameter must be less than or equal to 1000	limit

Status 500

Error de conexión a base de datos

{
    "statusCode": 500,
    "errors": [
        {
            "message": "Error connecting to database"
        }
    ]
}

Error de operación en base de datos

{
    "statusCode": 500,
    "errors": [
        {
            "message": "Database operation failed"
        }
    ]
}

Error en validaciones

{
    "statusCode": 500,
    "errors": [
        {
            "message": "Unexpected error in the validations"
        }
    ]
}

Error inesperado

{
    "statusCode": 500,
    "errors": [
        {
            "message": "Unexpected error"
        }
    ]
}

Error del Servidor

Estos errores indican problemas internos en el servidor o la base de datos. Si persisten, contacta al equipo de soporte.