Crear Clientes

Permite crear uno o múltiples clientes en el sistema mediante una única petición. Este endpoint está diseñado para operaciones en lote (batch), permitiendo insertar hasta 10,000 registros por petición.

Método: POST

Endpoint

https://api.ventasremotas.com/v1/customers/batch-create

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
Content-Type	application/json	Indica que los datos se envían en formato JSON
Accept	application/json	Indica que la respuesta debe estar en formato JSON
Subscription-Key	{subscription_key}	Clave de suscripción para acceder a la API
Authorization	Bearer {access_token}	Token de acceso obtenido del endpoint /token

---

Parámetros del Cuerpo (Body)

El body debe ser un array de objetos, donde cada objeto representa un cliente a crear.

Límites

Parámetro	Valor	Descripción
Mínimo de items	1	El array no puede estar vacío
Máximo de items	10,000	Número máximo de clientes por petición

Campos

El cuerpo (Body) de la solicitud debe enviarse en formato JSON y debe incluir un array con los siguientes parámetros.

Importante

Todos los campos requeridos deben estar presentes en cada objeto del array, incluso los campos que admiten nulo (Nulo: Sí). Si un campo no aplica para un cliente, envíelo con valor null.

Campos opcionales

Los campos marcados como Opcional pueden omitirse completamente del objeto. Al crear un cliente, si el campo opcional no se envía, se asignará automáticamente su valor por defecto indicado en la columna de restricciones. Para discount_base el valor por defecto es 0.

Campo	Tipo	Nulo	Restricciones	Descripción
code	string (max 18)	No	No permite: espacio, #, %, &, *, {, }, \, :, <, >, ?, /, +, .	Código único del cliente
type	string (max 30)	No		Tipo de cliente o clasificación definida en el ERP (ej: “DISTRIBUIDOR”, “MINORISTA”)
name	string (max 150)	No		Nombre completo o razón social del cliente
contact	string (max 150)	No		Nombre de la persona de contacto
phone	string (max 100)	No		Teléfono o móvil de contacto
email	string (max 150)	Sí		Correo electrónico principal del cliente
address	string (max 300)	No		Dirección física del cliente
city	string (max 50)	No		Ciudad donde se ubica el cliente
country	string (max 50)	Sí		País donde se ubica el cliente
region	string (max 50)	Sí		Región o departamento del cliente
quota	decimal (18, 2)	No		Capacidad de crédito del cliente
term	decimal (3, 0)	No		Plazo de pago del cliente (ej: 30, 60, 90)
payment_method	string (max 50)	No		Forma de pago (ej: “CONTADO”, “CRÉDITO”)
price_list	string (max 20)	Sí		Código de la lista de precios asignada al cliente desde el ERP
location	string (max 20)	Sí		Código de bodega asignado al cliente para la venta
nit	string (max 20)	Sí		NIT o RUT del cliente
discount	decimal (10, 2)	Sí		Porcentaje de descuento que aplica al cliente
discount_list	string (max 20)	Sí		Código de lista de descuentos
observations	string (max 500)	Sí		Observaciones o notas adicionales
name_est	string (max 200)	Sí		Nombre del establecimiento
short_name	string (max 200)	Sí		Nombre corto o alias del cliente
operation_center	string (max 10)	Sí		Centro de operación asignado
block_sales	string (max 1)	Sí	Valores permitidos: Y, N	Bloquear ventas al cliente
commercial_discount	decimal (18, 2)	Sí		Descuento asignado al cliente para ser aplicado de forma automática al momento de tomar un pedido
discount_base	decimal (18, 2)	Sí	Opcional · mínimo 0 · máximo 2 decimales	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. Si se omite, es null o vacío, se guarda 0.
withholding_base	decimal (18, 2)	Sí		Base de retención
withholding	decimal (18, 2)	Sí		Valor de retención
corporate_client	string (max 18)	Sí		NIT del cliente corporativo (utilizado para la cartera)
real_quota	decimal (18, 2)	Sí		Cupo real disponible del cliente
state	string (max 1)	No	Valores permitidos: Y, N	Estado del cliente (Activo/Inactivo)
email2	string (max 150)	Sí		Correo electrónico secundario
parent_client	string (max 18)	Sí		Código del cliente padre (utilizado para determinar una sucursal de una cuenta principal)
latitude	decimal (24, 18)	Sí		Latitud de la ubicación geográfica del cliente
longitude	decimal (24, 18)	Sí		Longitud de la ubicación geográfica del cliente
visit_priority	string (max 10)	Sí	Valores permitidos: high, low, regular	Prioridad de visita del cliente
time_window_start	string (max 5)	Sí	Formato: HH:MM (ej: 08:30, 14:00)	Hora de inicio de la ventana de atención
time_window_end	string (max 5)	Sí	Formato: HH:MM (ej: 08:30, 17:00)	Hora de fin de la ventana de atención
service_duration_minutes	integer	Sí	Rango: 0 a 1440	Tiempo promedio de atención en minutos
seller_can_edit	string (max 1)	Sí	Valores permitidos: Y, N	Permite al vendedor editar datos del cliente
seller_can_inactivate	string (max 1)	Sí	Valores permitidos: Y, N	Permite al vendedor inactivar al cliente
tax_exempt	string (max 1)	Sí	Valores permitidos: Y, N	Exento de impuesto
apply_associated_scales	string (max 1)	Sí	Valores permitidos: Y, N	Aplicar sólo escalas asociadas (aplica para escalas de descuento y bonificación)
apply_associated_surveys	string (max 1)	Sí	Valores permitidos: Y, N	Permitir diligenciar solo formularios asociados

Formato de tipos de dato

• string (max N): Cadena de texto con longitud máxima de N caracteres.
• decimal (p, s): Número decimal donde p es la precisión total (dígitos enteros + decimales) y s es la escala (dígitos decimales).
  • Ejemplo: decimal (18, 2) permite hasta 16 dígitos enteros y 2 decimales (ej: 9999999999999999.99)
  • Ejemplo: decimal (3, 0) permite hasta 3 dígitos enteros sin decimales (ej: 999)
  • Ejemplo: decimal (24, 18) permite hasta 6 dígitos enteros y 18 decimales
• integer: Número entero.

---

Ejemplo de Solicitud

Aquí tienes un ejemplo de cómo debería quedar el cuerpo de la solicitud en formato JSON:

[
  {
    "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,
    "payment_method": "CRÉDITO",
    "nit": "900123456-1",
    "discount": 5.0,
    "discount_list": "DESC-PREMIUM",
    "observations": "Cliente preferencial - Zona norte",
    "price_list": "LP-001",
    "location": "LOC-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"
  }
]

---

Ejemplo de Respuesta

201 - OK

{
    "statusCode": 201,
    "message": "Customers created successfully"
}

Importante

Los clientes que ya existan en el sistema (mismo code) serán ignorados sin generar error. Solo se insertarán los clientes nuevos.

Status 400

{
    "statusCode": 400,
    "errors": [
        {
            "message": "Invalid JSON in request body"
        }
    ]
}

Status 415

{
    "statusCode": 415,
    "errors": [
        {
            "message": "Content-Type: application/json is required"
        }
    ]
}

Status 422

Errores globales (estructura del body)

Si el body no es un array:

{
    "statusCode": 422,
    "errors": [
        {
            "message": "Request body must be an array"
        }
    ]
}

Si el array está vacío:

{
    "statusCode": 422,
    "errors": [
        {
            "message": "Request body cannot be empty"
        }
    ]
}

Si excede el límite de 10,000 items:

{
    "statusCode": 422,
    "errors": [
        {
            "message": "Array exceeds maximum limit of 10000 items"
        }
    ]
}

Errores por item (validación de campos)

Los errores se agrupan por el índice del item en el array:

{
    "statusCode": 422,
    "errors": [
        {
            "index": 0,
            "errors": [
                {
                    "field": "name",
                    "message": "Field is required"
                },
                {
                    "field": "quota",
                    "message": "Field must be of type decimal"
                }
            ]
        },
        {
            "index": 2,
            "errors": [
                {
                    "field": "code",
                    "message": "Field exceeds maximum length of 18 characters"
                }
            ]
        }
    ]
}

Tipos de Errores de Validación por Campo

Errores de presencia y nulidad:

Error	Descripción
Field is required	El campo no fue enviado en el objeto (la clave no existe)
Field cannot be null or empty	El campo fue enviado con valor null o vacío y no acepta nulos
Unknown field	Se envió un campo que no existe en la configuración
Item must be an object	Un elemento del array no es un objeto JSON

Errores de tipo de dato:

Error	Descripción
Field must be a string	El valor no es una cadena de texto
Field must be of type integer	El valor no es un número entero válido
Field must be of type decimal	El valor no es un número decimal válido
Field must be a valid decimal (e.g., 1.5, 10.25)	El formato del decimal es inválido
Field must be a valid decimal number	El valor no es un número decimal válido (NaN, Infinity)
Field must be a valid date (YYYY-MM-DD)	El valor no es una fecha válida en formato YYYY-MM-DD

Errores de longitud y precisión:

Error	Descripción
Field exceeds maximum length of X characters	La cadena excede la longitud máxima permitida
Field exceeds maximum of X integer digits (precision: P, scale: S)	El número excede los dígitos enteros permitidos
Field exceeds maximum of X decimal places	El número excede los decimales permitidos

Errores de valores permitidos:

Error	Descripción
Value must be one of: X, Y	El valor no está en la lista de valores permitidos

Errores de formato:

Error	Descripción
Field contains forbidden characters. The following are not allowed: space, #, %, &, *, {, }, \, :, <, >, ?, /, +, .	El campo code contiene caracteres prohibidos
Field must match format HH:MM (e.g., '08:30', '14:00')	El formato de hora es inválido (campos time_window_start, time_window_end)
Hours must be between 00 and 23	Las horas del formato HH:MM están fuera de rango
Minutes must be between 00 and 59	Los minutos del formato HH:MM están fuera de rango

Errores de rango (campos enteros y decimales):

Error	Descripción
Field must be greater than or equal to 0	El valor del campo service_duration_minutes o discount_base es menor a 0
Field must be less than or equal to 1440	El valor del campo service_duration_minutes es mayor a 1440

Status 423

{
    "statusCode": 423,
    "errors": [
        {
            "message": "Resource is locked and cannot be accessed."
        }
    ]
}

Recurso bloqueado

Este error ocurre cuando otra operación de creación o actualización de clientes con la misma Subscription-Key está en progreso. Espere a que la operación anterior finalice e intente nuevamente.

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 Redis

{
    "statusCode": 500,
    "errors": [
        {
            "message": "Redis 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, la base de datos o el servicio de cache. Si persisten, contacta al equipo de soporte.