Listar Clientes

Permite obtener el listado de clientes registrados en el sistema de forma paginada. 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/customers

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

Filtros

Parámetro	Tipo	Descripción
code	String	Filtra por código exacto de cliente. Longitud máxima: 18 caracteres.
created_from	Date	Retorna clientes cuya fecha de creación es mayor o igual a este valor. Formato: YYYY-MM-DD.
modified_from	Date	Retorna clientes 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 clientes que cumplan cualquiera de las dos condiciones (creados desde esa fecha o modificados desde esa fecha).

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/customers" \
  -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/customers?code=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/customers?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/customers?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/customers?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": "CLI-001",
            "type": "DISTRIBUIDOR",
            "name": "Distribuidora ABC S.A.S",
            "contact": "Juan Pérez",
            "phone": "3001234567",
            "email": "contacto@distribuidoraabc.com",
            "email2": "ventas@distribuidoraabc.com",
            "address": "Calle 100 #15-25 Oficina 301",
            "city": "Bogotá",
            "country": "Colombia",
            "region": "Cundinamarca",
            "quota": 50000000.0,
            "term": 30.0,
            "payment_method": "CRÉDITO",
            "price_list": "LP-001",
            "location": "LOC-NORTE",
            "nit": "900123456-1",
            "discount": 5.0,
            "discount_list": "DESC-PREMIUM",
            "observations": "Cliente preferencial - Zona norte",
            "name_est": "Distribuidora ABC Sede Principal",
            "short_name": "Dist ABC",
            "operation_center": "CO-001",
            "block_sales": "N",
            "commercial_discount": 2500.0,
            "discount_base": 100000.0,
            "withholding_base": 500000.0,
            "withholding": 15000.0,
            "corporate_client": "CORP-001",
            "real_quota": 45000000.0,
            "state": "Y",
            "parent_client": null,
            "latitude": 4.7109886,
            "longitude": -74.072092,
            "visit_priority": "high",
            "time_window_start": "08:00",
            "time_window_end": "17:00",
            "service_duration_minutes": 45,
            "seller_can_edit": "Y",
            "seller_can_inactivate": "N",
            "tax_exempt": "N",
            "apply_associated_scales": "N",
            "apply_associated_surveys": "N",
            "transmitted": null,
            "created_at": "2024-06-15T10:30:00",
            "created_user_code": "USR-003",
            "updated_at": "2024-09-20T14:15:00",
            "updated_user_code": "USR-001",
            "inactivation_at": null,
            "georeferenced_at": "2024-08-10T09:45:00",
            "georeferenced_source": "Android",
            "georeferenced_user_code": "USR-001",
            "creation_source": 1,
            "is_prospect": "N",
            "prospect_code": null,
            "approval_state": null,
            "approver_user_code": null,
            "rejection_reason": null,
            "rejection_observations": null,
            "reactivation_at": null,
            "reactivation_user_code": null,
            "reactivation_reason": null,
            "reactivation_observations": null
        }
    ],
    "meta": {
        "totalItems": 1250,
        "itemCount": 100,
        "itemsPerPage": 100,
        "totalPages": 13,
        "currentPage": 1
    },
    "links": {
        "self": "https://api.ventasremotas.com/v1/customers?page=1&limit=100",
        "first": "https://api.ventasremotas.com/v1/customers?page=1&limit=100",
        "prev": null,
        "next": "https://api.ventasremotas.com/v1/customers?page=2&limit=100",
        "last": "https://api.ventasremotas.com/v1/customers?page=13&limit=100"
    }
}

Descripción de campos de respuesta

Objeto data[] (Cliente)

Cada elemento del array data contiene los siguientes campos:

Campo	Tipo	Descripción
code	String	Código único del cliente
type	String	Tipo de cliente o clasificación definida en el ERP (ej: “DISTRIBUIDOR”, “MINORISTA”)
name	String	Nombre completo o razón social del cliente
contact	String	Nombre de la persona de contacto
phone	String	Teléfono o móvil de contacto
email	String	Correo electrónico principal del cliente (puede ser null)
email2	String	Correo electrónico secundario (puede ser null)
address	String	Dirección física del cliente
city	String	Ciudad donde se ubica el cliente
country	String	País donde se ubica el cliente (puede ser null)
region	String	Región o departamento del cliente (puede ser null)
quota	Number	Capacidad de crédito del cliente
term	Number	Plazo de pago del cliente (ej: 30, 60, 90)
payment_method	String	Forma de pago (ej: “CONTADO”, “CRÉDITO”)
price_list	String	Código de la lista de precios asignada al cliente desde el ERP (puede ser null)
location	String	Código de bodega asignado al cliente para la venta (puede ser null)
nit	String	NIT o RUT del cliente (puede ser null)
discount	Number	Porcentaje de descuento que aplica al cliente (puede ser null)
discount_list	String	Código de lista de descuentos (puede ser null)
observations	String	Observaciones o notas adicionales (puede ser null)
name_est	String	Nombre del establecimiento (puede ser null)
short_name	String	Nombre corto o alias del cliente (puede ser null)
operation_center	String	Centro de operación asignado (puede ser null)
block_sales	String	Bloquear ventas al cliente: Y o N (puede ser null)
commercial_discount	Number	Descuento asignado al cliente para ser aplicado de forma automática al momento de tomar un pedido (puede ser null)
discount_base	Number	Valor mínimo de compra (antes de impuestos y con descuentos) a partir del cual se habilita el Descuento Comercial del cliente; 0 = el descuento aplica siempre (puede ser null, equivalente a 0)
withholding_base	Number	Base de retención (puede ser null)
withholding	Number	Valor de retención (puede ser null)
corporate_client	String	NIT del cliente corporativo (utilizado para la cartera) (puede ser null)
real_quota	Number	Cupo real disponible del cliente (puede ser null)
state	String	Estado del cliente (Activo/Inactivo): Y o N
parent_client	String	Código del cliente padre (utilizado para determinar una sucursal de una cuenta principal) (puede ser null)
latitude	Number	Latitud de la ubicación geográfica del cliente (puede ser null)
longitude	Number	Longitud de la ubicación geográfica del cliente (puede ser null)
visit_priority	String	Prioridad de visita del cliente: high, low, regular (puede ser null)
time_window_start	String	Hora de inicio de la ventana de atención en formato HH:MM (puede ser null)
time_window_end	String	Hora de fin de la ventana de atención en formato HH:MM (puede ser null)
service_duration_minutes	Number	Tiempo promedio de atención en minutos (puede ser null)
seller_can_edit	String	Permite al vendedor editar datos del cliente: Y o N (puede ser null)
seller_can_inactivate	String	Permite al vendedor inactivar al cliente: Y o N (puede ser null)
tax_exempt	String	Exento de impuesto: Y o N (puede ser null)
apply_associated_scales	String	Aplicar sólo escalas asociadas (aplica para escalas de descuento y bonificación): Y o N (puede ser null)
apply_associated_surveys	String	Permitir diligenciar solo formularios asociados: Y o N (puede ser null)
transmitted	String	Indica si el cliente fue descargado a la interfaz (puede ser null)
created_at	DateTime	Fecha y hora de creación del cliente. Formato: yyyy-MM-ddTHH:mm:ss
created_user_code	String	Código del usuario que creó el cliente (puede ser null)
updated_at	DateTime	Fecha y hora de última modificación. Formato: yyyy-MM-ddTHH:mm:ss (puede ser null)
updated_user_code	String	Código del usuario que realizó la última modificación (puede ser null)
inactivation_at	DateTime	Fecha y hora de inactivación del cliente. Formato: yyyy-MM-ddTHH:mm:ss (puede ser null)
georeferenced_at	DateTime	Fecha y hora de georeferenciación del cliente. Formato: yyyy-MM-ddTHH:mm:ss (puede ser null)
georeferenced_source	String	Origen de la georeferenciación: Android, Excel_web, LUPAP, P_RUTAS, SOPORTE, Web (puede ser null)
georeferenced_user_code	String	Código del usuario que georeferenció al cliente (puede ser null)
creation_source	Number	Origen de creación del cliente: 1 (WEB), 2 (MOVIL), 3 (INTERFAZ) (puede ser null)
is_prospect	String	Indica si el cliente es un prospecto: Y o N (puede ser null)
prospect_code	String	Código del cliente cuando era prospecto (puede ser null)
approval_state	Number	Estado de aprobación del cliente prospecto: 1 (En seguimiento), 2 (Pendiente por aprobar), 3 (Aprobado — se considera un cliente real), 4 (Rechazado desde web), 5 (Inactivado desde móvil) (puede ser null)
approver_user_code	String	Código del usuario que aprobó el cliente prospecto (puede ser null)
rejection_reason	String	Causal de rechazo del prospecto (puede ser null)
rejection_observations	String	Observaciones de rechazo del prospecto (puede ser null)
reactivation_at	DateTime	Fecha y hora de reactivación del cliente prospecto. Formato: yyyy-MM-ddTHH:mm:ss (puede ser null)
reactivation_user_code	String	Código del usuario que reactivó al cliente prospecto (puede ser null)
reactivation_reason	String	Causal de reactivación del cliente prospecto (puede ser null)
reactivation_observations	String	Observaciones de reactivación del cliente prospecto (puede ser null)

Objeto meta (Metadatos de paginación)

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

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.