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-sandbox.ventasremotas.com/v1/customers/batch-create

Nota

Es necesario el envío del token de acceso Ocp-Apim-Subscription-Key para hacer uso de este endpoint. Para ver cómo generar el token, vea Cómo generar un token de acceso.

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
Ocp-Apim-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:

Campo	Tipo	Descripción
code	string (max 18)	Código único del cliente
type	string (max 30)	Tipo de cliente (ej: “DISTRIBUIDOR”, “MINORISTA”)
name	string (max 150)	Nombre completo o razón social del cliente
contact	string (max 150)	Nombre de la persona de contacto
phone	string (max 100)	Número(s) de teléfono de contacto
address	string (max 300)	Dirección física del cliente
city	string (max 50)	Ciudad donde se ubica el cliente
quota	decimal (18, 2)	Cupo de crédito asignado al cliente
term	decimal (3, 0)	Plazo de pago en días (ej: 30, 60, 90)
payment_method	string (max 50)	Forma de pago (ej: “CONTADO”, “CRÉDITO”)
email	string (max 150)	Correo electrónico principal del cliente
email2	string (max 150)	Correo electrónico secundario
country	string (max 50)	País donde se ubica el cliente
region	string (max 50)	Región o departamento del cliente
price_list	string (max 20)	Código de lista de precios asignada
location	string (max 20)	Código de ubicación geográfica
nit	string (max 20)	Número de identificación tributaria
discount	decimal (10, 2)	Porcentaje de descuento general
discount_list	string (max 20)	Código de lista de descuentos
observations	string (max 500)	Observaciones o notas adicionales
name_est	string (max 200)	Nombre del establecimiento
short_name	string (max 200)	Nombre corto o alias del cliente
operation_center	string (max 10)	Centro de operación asignado
block_sales	string (max 1)	Bloquear ventas al cliente. Valores: Y (Sí), N (No)
commercial_discount	decimal (18, 2)	Descuento comercial en valor
discount_base	decimal (18, 2)	Base para cálculo de descuento
withholding_base	decimal (18, 2)	Base para cálculo de retención
withholding	decimal (18, 2)	Valor de retención
corporate_client	string (max 18)	Código del cliente corporativo padre
iva_exempt	string (max 1)	Exento de IVA. Valores: Y (Sí), N (No)
real_quota	decimal (18, 2)	Cupo real disponible del cliente
state	string (max 1)	Estado del cliente (Activo/Inactivo). Valores: Y, N

Formato de tipos de dato

• 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 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",
    "iva_exempt": "N",
    "real_quota": 45000000.0,
    "state": "Y"
  }
]

---

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

Global

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

Por Item

{
    "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

Error	Descripción
Field is required	El campo obligatorio no fue enviado o está vacío
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
Field must be a valid date (YYYY-MM-DD)	El valor no es una fecha válida en formato YYYY-MM-DD
Field exceeds maximum length of X characters	La cadena excede la longitud máxima permitida
Field exceeds maximum of X integer digits	El número excede los dígitos enteros permitidos
Field exceeds maximum of X decimal places	El número excede los decimales permitidos
Value must be one of: X, Y	El valor no está en la lista de valores permitidos
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

Status 423

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

Status 500

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