Clientes

Administra tu base de clientes.

Entidad base que representa a sus clientes/compradores. Debe cargarse primero ya que otras entidades dependen de ella.

Endpoint

POST /full-csv-integration/upload-customers

Campo de Formulario: customersFile

Campos Requeridos

Campo	Tipo	Descripción	Validaciones
`nit`	String	Número de identificación tributaria	No puede estar vacío
`erp_customer_id`	String	ID único del cliente en su ERP	No puede estar vacío
`company_name`	String	Razón social o nombre de la empresa	No puede estar vacío

Campos Opcionales

Campo	Tipo	Descripción	Por Defecto
`email`	String	Correo electrónico de la empresa. Formato de email válido	null
`city_name`	String	Ciudad sede	null
`state_name`	String	Departamento/Provincia	null
`postal_code`	String	Código postal	null
`country_code`	String	Código de país	null
`credit_limit`	Float	Cupo de crédito actual. Número decimal	null
`current_term`	Integer	Plazo de pago en días. Número entero	null
`allow_collection`	Boolean	Permitir campañas de cobranza automática. Solo `1` o `0`. El valor por defecto aplica únicamente si omite la columna; una celda vacía guarda `0`, tanto al crear como al actualizar	`1` (true)
`advance_balance`	Float	Saldo a favor del cliente	null
`erp_branch_id`	String	ID de sucursal en ERP	null
`branch_name`	String	Nombre de la sucursal	null
`document_type`	String	Tipo de documento de identificación. Acepta valores canónicos o códigos numéricos DIAN — ver mapeo abajo	null

Mapeo de Tipos de Documento

Valores canónicos aceptados: cc, ce, nit, ext_nit, te, pp, die, pep, ppt. Los valores se comparan sin distinguir mayúsculas/minúsculas (por ejemplo, NIT y nit son ambos válidos).

También puede enviar el código numérico DIAN equivalente en lugar del valor de texto:

Código DIAN	Valor de `document_type`
13	`cc`
22	`ce`
31	`nit`
50	`ext_nit`
21	`te`
41	`pp`
42	`die`
47	`pep`
48	`ppt`

También se aceptan pasaporte y passport, que equivalen a pp. Si el valor enviado no coincide con ninguno de estos, la carga no se rechaza: la respuesta trae una advertencia y la fila se importa con document_type establecido en unrecognized — este es un valor de reserva asignado por el sistema, no un valor que deba escribirse en el CSV. Si el campo se deja vacío u omitido, document_type simplemente no se establece (null).

Filas repetidas

Si el mismo erp_customer_id aparece en varias filas, se conserva la última. Por eso un cliente con varias sucursales queda con una sola: cargue una fila por erp_customer_id.

Ejemplo CSV

nit,erp_customer_id,company_name,email,city_name,state_name,postal_code,country_code,credit_limit,current_term,allow_collection,advance_balance,erp_branch_id,branch_name,document_type
123456789-1,CUST001,ABC Company Inc.,contact@abc.com,Bogotá,Cundinamarca,110111,CO,1000000.00,30,1,50000.00,BR001,Sede Principal,cc
987654321-2,CUST002,XYZ Corporation Ltd.,info@xyz.com,Medellín,Antioquia,050001,CO,500000.00,15,1,0.00,BR002,Sucursal Norte,nit