Listar Contactos

Permite obtener el listado de contactos de clientes registrados en el sistema de forma paginada. Cada contacto es una persona asociada a un cliente (por ejemplo, el jefe de compras o el encargado de recibir mercancía) e incluye el detalle de sus medios de contacto: correos electrónicos, teléfonos, direcciones y fechas relevantes. La respuesta tiene estructura maestro-detalle: el contacto aparece una sola vez y sus medios de contacto viajan en el array details. Este endpoint soporta filtros por código de cliente, fecha de creación y fecha de modificación, así como ordenamiento configurable.

Método: GET

Endpoint

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

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 contactos de la empresa con la paginación por defecto.

Filtros

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

Filtros de fecha

Los filtros created_from y modified_from se agrupan con un operador OR cuando se usan juntos. Esto significa que al enviar ambos, se retornarán contactos que cumplan cualquiera de las dos condiciones (creados desde esa fecha o modificados desde esa fecha).

Los filtros de fecha se evalúan sobre el contacto (maestro). Cuando se agrega o modifica un medio de contacto desde la aplicación móvil, la fecha de modificación del contacto también se actualiza, por lo que modified_from permite detectar cambios en los detalles.

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/contacts" \
  -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/contacts?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/contacts?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 ordenamiento ascendente

curl -X GET "https://api.ventasremotas.com/v1/contacts?sort=created_at&page=2&limit=100" \
  -H "Accept: application/json" \
  -H "Subscription-Key: tu-subscription-key" \
  -H "Authorization: Bearer tu-access-token"

Petición con múltiples filtros de fecha

curl -X GET "https://api.ventasremotas.com/v1/contacts?client_id=CLI-001&created_from=2024-01-01&modified_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": [
        {
            "code": 1024,
            "client_id": "CLI-001",
            "first_name": "María",
            "second_name": "Fernanda",
            "first_last_name": "Gómez",
            "second_last_name": "Ríos",
            "position": "Jefe de Compras",
            "department": "Compras",
            "company_name": "Distribuciones El Norte S.A.S.",
            "relation": "Cliente",
            "observations": "Atiende de lunes a viernes en la mañana",
            "state": "Y",
            "erp_code": "ERP-CT-001",
            "created_at": "2024-06-15T10:30:00",
            "updated_at": "2024-09-20T14:15:00",
            "details": [
                {
                    "type": 2,
                    "value": "+573001234567",
                    "label": "",
                    "state": "Y",
                    "latitude": null,
                    "longitude": null,
                    "created_at": "2024-06-15T10:30:00",
                    "updated_at": null
                },
                {
                    "type": 2,
                    "value": "6013456789",
                    "label": "",
                    "state": "Y",
                    "latitude": null,
                    "longitude": null,
                    "created_at": "2024-06-15T10:30:00",
                    "updated_at": null
                },
                {
                    "type": 1,
                    "value": "maria.gomez@elnorte.com",
                    "label": "",
                    "state": "Y",
                    "latitude": null,
                    "longitude": null,
                    "created_at": "2024-06-15T10:30:00",
                    "updated_at": "2024-09-20T14:15:00"
                },
                {
                    "type": 3,
                    "value": "Calle 100 #15-25 Oficina 302",
                    "label": "",
                    "state": "Y",
                    "latitude": 4.7109886,
                    "longitude": -74.072092,
                    "created_at": "2024-06-15T10:30:00",
                    "updated_at": null
                },
                {
                    "type": 4,
                    "value": "1985-03-14",
                    "label": "Cumpleaños",
                    "state": "Y",
                    "latitude": null,
                    "longitude": null,
                    "created_at": "2024-06-15T10:30:00",
                    "updated_at": null
                }
            ]
        }
    ],
    "meta": {
        "totalItems": 134,
        "itemCount": 1,
        "itemsPerPage": 100,
        "totalPages": 2,
        "currentPage": 1
    },
    "links": {
        "self": "https://api.ventasremotas.com/v1/contacts?page=1&limit=100",
        "first": "https://api.ventasremotas.com/v1/contacts?page=1&limit=100",
        "prev": null,
        "next": "https://api.ventasremotas.com/v1/contacts?page=2&limit=100",
        "last": "https://api.ventasremotas.com/v1/contacts?page=2&limit=100"
    }
}

Descripción de campos de respuesta

Objeto data[] (Contacto)

Cada elemento del array data contiene los siguientes campos:

Campo	Tipo	Descripción
code	Number	Código único del contacto en la base de datos. Es inmutable y sirve como clave de identificación al actualizar
client_id	String	Código del cliente al que pertenece el contacto
first_name	String	Primer nombre del contacto
second_name	String	Segundo nombre del contacto (puede ser null)
first_last_name	String	Primer apellido del contacto
second_last_name	String	Segundo apellido del contacto (puede ser null)
position	String	Cargo que ocupa el contacto (puede ser null)
department	String	Departamento o área a la que pertenece (puede ser null)
company_name	String	Nombre de la empresa del contacto, cuando difiere del cliente (puede ser null)
relation	String	Relación del contacto con el cliente (puede ser null)
observations	String	Observaciones generales del contacto (puede ser null)
state	String	Estado del contacto: Y (activo) o N (inactivo)
erp_code	String	Código del contacto en el sistema ERP (puede ser null)
created_at	DateTime	Fecha de creación del contacto. Formato: yyyy-MM-ddTHH:mm:ss
updated_at	DateTime	Fecha de última modificación del contacto. Formato: yyyy-MM-ddTHH:mm:ss (puede ser null)
details	Array	Lista de medios de contacto del contacto. Ver detalle en la tabla siguiente

Objeto details[] (Medio de contacto)

Cada elemento del array details dentro de un contacto contiene:

Campo	Tipo	Descripción
type	Number	Tipo de medio de contacto: 1 (Correo electrónico), 2 (Teléfono), 3 (Dirección), 4 (Fecha)
value	String	Valor según el tipo: el correo, el número telefónico completo (con indicativo si es WhatsApp), la dirección o la fecha en formato YYYY-MM-DD. Ver la nota siguiente
label	String	Solo tiene valor para fechas (type: 4): el nombre de la fecha (por ejemplo: Cumpleaños, Aniversario). Para los demás tipos siempre es una cadena vacía
state	String	Estado del medio de contacto: Y (activo) o N (inactivo)
latitude	Number	Coordenada de latitud, solo aplica para direcciones (type: 3) georreferenciadas (puede ser null)
longitude	Number	Coordenada de longitud, solo aplica para direcciones (type: 3) georreferenciadas (puede ser null)
created_at	DateTime	Fecha de creación del medio de contacto. Formato: yyyy-MM-ddTHH:mm:ss
updated_at	DateTime	Fecha de última modificación del medio de contacto. Formato: yyyy-MM-ddTHH:mm:ss (puede ser null)

Objeto meta (Metadatos de paginación)

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