Listar Visitas

Permite obtener el listado de visitas registradas en el sistema de forma paginada. Las visitas son los registros que inicia un usuario móvil al abrir un cliente desde la agenda o desde la sección de clientes; se denominan Agendadas (cuando provienen de una cita en agenda) o Extraruta (cuando se abre el cliente sin cita previa) y pueden o no contener transacciones asociadas. No se incluyen visitas en modo consulta. Con esta información se realiza el reporte web llamado Control de tiempos. Este endpoint soporta filtros por código de gestión, vendedor, cliente y fechas (inicio y transmisión), así como ordenamiento configurable.

Método: GET

Endpoint

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

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 todas las visitas con la paginación por defecto.

Filtros

Parámetro	Tipo	Descripción
code	String	Filtra por código exacto de la gestión/visita.
seller_id	String	Filtra por código exacto de vendedor. Longitud máxima: 18 caracteres.
client_id	String	Filtra por código exacto de cliente. Longitud máxima: 18 caracteres.
start_date_from	Date	Retorna visitas cuya fecha de inicio es mayor o igual a este valor. Formato: YYYY-MM-DD.
transmitted_from	Date	Retorna visitas cuya fecha de transmisión es mayor o igual a este valor. Formato: YYYY-MM-DD.

Filtros de fecha

Los filtros start_date_from y transmitted_from se agrupan con un operador OR cuando se usan juntos. Esto significa que al enviar ambos, se retornarán visitas que cumplan cualquiera de las dos condiciones (con fecha de inicio desde esa fecha o transmitidas desde esa fecha).

Ordenamiento

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

Campos de ordenamiento disponibles

Valor	Descripción
start_date	Ordena por fecha de inicio ascendente (ASC)
-start_date	Ordena por fecha de inicio descendente (DESC)

Ordenamiento por defecto

Si no se especifica el parámetro sort, los resultados se ordenan por fecha de inicio 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/managements" \
  -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/managements?seller_id=V001" \
  -H "Accept: application/json" \
  -H "Subscription-Key: tu-subscription-key" \
  -H "Authorization: Bearer tu-access-token"

Petición con filtro por cliente

curl -X GET "https://api.ventasremotas.com/v1/managements?client_id=CLI-001" \
  -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/managements?start_date_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

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

---

Ejemplo de Respuesta

200 - OK

{
    "data": [
        {
            "code": "1771539538892",
            "seller_id": "V001",
            "client_id": "CLI-001",
            "start_date": "2025-03-15T10:30:00",
            "end_date": "2025-03-15T11:45:00",
            "transmitted_at": "2025-03-15T11:46:00",
            "start_latitude": 4.710989,
            "start_longitude": -74.072092,
            "initial_precision": 12.5,
            "end_latitude": 4.711012,
            "end_longitude": -74.072105,
            "final_precision": 8.3,
            "appointment_code": 1542,
            "transactions": "PEDIDO, RECAUDO",
            "total_transactions": 3,
            "movement_time": 900,
            "permanence_time": 3600,
            "typing_time": 420,
            "waiting_time": 120,
            "worked_time": 4140,
            "appointment_start_time": "2025-03-15T10:30:00",
            "initial_time_difference": 0,
            "appointment_end_time": "2025-03-15T11:30:00",
            "final_time_difference": 900,
            "appointment_duration": 3600,
            "appointment_real_duration": 4500,
            "management_order": 1,
            "transmitted": "Y"
        }
    ],
    "meta": {
        "totalItems": 95,
        "itemCount": 1,
        "itemsPerPage": 100,
        "totalPages": 1,
        "currentPage": 1
    },
    "links": {
        "self": "https://api.ventasremotas.com/v1/managements?page=1&limit=100",
        "first": "https://api.ventasremotas.com/v1/managements?page=1&limit=100",
        "prev": null,
        "next": null,
        "last": "https://api.ventasremotas.com/v1/managements?page=1&limit=100"
    }
}

Descripción de campos de respuesta

Objeto data[] (Visita / Gestión)

Cada elemento del array data contiene los siguientes campos:

Campo	Tipo	Descripción
code	String	Código único de la gestión/visita
seller_id	String	Código del vendedor que realizó la visita
client_id	String	Código del cliente visitado
start_date	DateTime	Fecha y hora de inicio de la visita. Formato: yyyy-MM-ddTHH:mm:ss
end_date	DateTime	Fecha y hora de fin de la visita. Formato: yyyy-MM-ddTHH:mm:ss. Si es null, se entiende que la visita continúa en curso por parte del usuario móvil.
transmitted_at	DateTime	Fecha y hora de transmisión del registro. Formato: yyyy-MM-ddTHH:mm:ss (puede ser null)
start_latitude	Number	Latitud del punto de inicio de la visita. Puede ser null o 0; en ese caso no se pudo obtener la coordenada desde el móvil.
start_longitude	Number	Longitud del punto de inicio de la visita. Puede ser null o 0; en ese caso no se pudo obtener la coordenada desde el móvil.
initial_precision	Number	Precisión GPS en el inicio de la visita en metros. Puede ser null o -1; en ese caso no se pudo obtener la precisión con la que se tomó la coordenada.
end_latitude	Number	Latitud del punto de fin de la visita. Puede ser null o 0; en ese caso no se pudo obtener la coordenada desde el móvil.
end_longitude	Number	Longitud del punto de fin de la visita. Puede ser null o 0; en ese caso no se pudo obtener la coordenada desde el móvil.
final_precision	Number	Precisión GPS al final de la visita en metros. Puede ser null o -1; en ese caso no se pudo obtener la precisión con la que se tomó la coordenada.
appointment_code	Number	Si es null o -1, la visita fue Extraruta. Si contiene un número, la visita fue Agendada y es el código de la agenda asociada.
transactions	String	Detalle textual de las transacciones realizadas dentro de la visita. Puede ser null si la visita no tuvo transacciones.
total_transactions	Number	Cantidad de transacciones realizadas dentro de la visita al cliente. null o 0 indica que la visita no tuvo transacciones.
movement_time	Number	Tiempo de Desplazamiento. Tiempo en segundos entre el cierre/desplazamiento de una visita y la apertura de la siguiente. Si es la primera visita del día, el valor es 0 o null.
typing_time	Number	Tiempo de Digitación. Tiempo en segundos que el usuario dedicó a realizar o digitalizar las transacciones al cliente dentro de la visita. Puede ser null o 0.
waiting_time	Number	Tiempo de Espera. Tiempo en segundos que pasó sin realizar ninguna transacción al cliente dentro de la visita. Puede ser null o 0.
permanence_time	Number	Tiempo de Permanencia. Sumatoria del tiempo de digitación más el tiempo de espera; representa el tiempo en segundos que permaneció en la visita con el cliente. Puede ser null o 0.
worked_time	Number	Tiempo Laborado. Sumatoria del tiempo de permanencia más el tiempo de desplazamiento, en segundos. Puede ser null o 0.
appointment_start_time	DateTime	Fecha y hora; puede ser null. Si la visita es Extraruta, coincide con la fecha de inicio de la visita. Si es Agendada, es la fecha y hora programada para la agenda. Formato: yyyy-MM-ddTHH:mm:ss.
initial_time_difference	Number	Diferencia en segundos (positiva o negativa) entre la fecha real de inicio de la visita y la referencia: en visita Agendada, la hora programada de la agenda; en Extraruta, la misma fecha de inicio (valor 0). Puede ser null o 0.
appointment_end_time	DateTime	Fecha y hora; puede ser null. Si la visita es Extraruta, coincide con la fecha de fin de la visita. Si es Agendada, es la fecha y hora de fin programada para la agenda. Formato: yyyy-MM-ddTHH:mm:ss.
final_time_difference	Number	Diferencia en segundos (positiva o negativa) entre la fecha real de fin de la visita y la referencia: en visita Agendada, la hora de fin programada de la agenda; en Extraruta, la misma fecha de fin (valor 0). Puede ser null o 0.
appointment_duration	Number	Duración en segundos calculada entre la fecha de inicio programada de la agenda y la fecha de fin programada de la agenda. Puede ser null o 0.
appointment_real_duration	Number	Duración en segundos que tomó la visita; prácticamente coincide con el tiempo de permanencia. Puede ser null o 0.
management_order	Number	Orden de la gestión en la ruta o secuencia del día (puede ser null)
transmitted	String	Indica si la visita fue descargada a la interfaz (puede ser null)

Objeto meta (Metadatos de paginación)

Campo	Tipo	Descripción
totalItems	Number	Cantidad total de visitas que coinciden con los filtros
itemCount	Number	Cantidad de visitas 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": "start_date_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	code, seller_id, client_id
Value 'X' is not a valid date (expected format: YYYY-MM-DD)	start_date_from, transmitted_from
Value exceeds maximum length of 18	seller_id, client_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.