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	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	null
`current_term`	Integer	Payment term in days	null
`allow_collection`	Boolean	Allow automated collection campaigns. The default applies only when the customer is created; a blank cell is read as `0`, and on updates the existing value is kept	`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

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 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).

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