Customers

Manage your customer base.

Base entity representing your clients/buyers. Must be uploaded first as other entities depend on it.

Endpoint

POST /full-csv-integration/upload-customers

Form Field: customersFile

Required Fields

Field	Type	Description	Validations
`nit`	String	Tax identification number	Cannot be empty
`erp_customer_id`	String	Unique customer ID in your ERP	Cannot be empty
`company_name`	String	Company or business name	Cannot be empty

Optional Fields

Field	Type	Description	Default
`email`	String	Company email address. Valid email format	null
`city_name`	String	Headquarters city	null
`state_name`	String	State/Province	null
`postal_code`	String	Postal/ZIP code	null
`country_code`	String	Country code	null
`credit_limit`	Float	Current credit limit. Finite decimal number; `0` is valid	null on create; see updates below
`current_term`	Integer	Payment term in days. Finite whole number; `0` is valid	null on create; see updates below
`allow_collection`	Boolean	Allow automated collection campaigns. Only `1` or `0`. The default applies only if you omit the column; an empty cell stores `0`, both on create and on update	`1` (true)
`advance_balance`	Float	Customer advance balance	null
`erp_branch_id`	String	Branch ID in ERP	null
`branch_name`	String	Branch name	null
`document_type`	String	Identification document type. Accepts canonical values or DIAN numeric codes — see mapping below	null

Updating credit limits and payment terms

Input	Effect on an existing customer
Valid `credit_limit` number, including `0`	Replace the previous credit limit
`credit_limit` column present, empty cell	Clear the previous credit limit to `null`
`credit_limit` column omitted	Preserve the previous credit limit
Valid `current_term` number, including `0`	Replace the previous payment term
`current_term` column present, empty cell	Clear the previous payment term (`null`)
`current_term` column omitted	Preserve the previous payment term

New customers without a value start with null. A credit limit must be a finite decimal number; a payment term must be a finite whole number. Use a decimal point and do not include thousands separators. Zero is valid for both fields. Only an empty cell or whitespace counts as empty: text such as null, NaN or N/A, and invalid numbers, reject the file instead of clearing data.

These rules apply only to credit_limit and current_term.

Document Type Mapping

Canonical accepted values: cc, ce, nit, ext_nit, te, pp, die, pep, ppt. Values are matched case-insensitively (e.g. NIT and nit are both accepted).

You may also submit the equivalent DIAN numeric code instead of the text value:

DIAN Code	`document_type` value
13	`cc`
22	`ce`
31	`nit`
50	`ext_nit`
21	`te`
41	`pp`
42	`die`
47	`pep`
48	`ppt`

pasaporte and passport are also accepted and both map to pp. If a submitted value doesn’t match any of these, the upload is not rejected: the response carries a warning and the row is imported with document_type set to unrecognized — this is a system-assigned fallback, not a value you should type into the CSV. If the field is left empty or omitted entirely, document_type is simply not set (null).

Repeated rows

If the same erp_customer_id appears in several rows, the last one is kept. That is why a customer with several branches ends up with only one: upload one row per erp_customer_id.

Example 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