Invoices

Manage accounts receivable invoices.

Accounts receivable invoices issued to customers.

Dependency: Requires Customers to be uploaded first.

Endpoint

POST /full-csv-integration/upload-invoices

Form Field: invoicesFile

Required Fields

Field	Type	Description	Validations
`erp_customer_id`	String	Customer ID in ERP	Cannot be empty. Must exist in Customers — see the warning below
`erp_invoice_id`	String	Invoice ID in ERP	Cannot be empty
`currency`	String	Currency code	e.g., `COP`, `USD`, `EUR`. Cannot be empty and must be 3 letters: a longer one passes validation but makes processing fail
`original_amount`	Float	Original invoice amount	Decimal number, greater than or equal to 0
`pending_amount`	Float	Pending/outstanding amount	Decimal number
`status`	String	Invoice status	`OPEN` or `CLOSED`. Write it in uppercase: in lowercase the response confirms the upload, but processing of the whole file fails afterwards
`issue_date`	Date	Invoice issue date	If it carries a value it must be `YYYY-MM-DD`; other formats are rejected. An empty cell is accepted and the date is left empty
`due_date`	Date	Payment due date	If it carries a value it must be `YYYY-MM-DD`; other formats are rejected. An empty cell is accepted and the date is left empty

Optional Fields

Field	Type	Description	Validations	Default
`advance_amount`	Float	Advance payment applied	Decimal number. If omitted or left empty it is stored as `0.00`	`0.00`
`allow_collection`	Boolean	Allow collection	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`
`invoice_type`	Enum	Invoice commercial term	`CREDIT` or `CASH`. Case and surrounding whitespace are ignored. Any other nonblank value rejects the upload	`CREDIT` on create; blank or omitted preserves the existing value on update
`invoice_url`	String	URL to invoice document	-	null
`cost_center_1_erp_id`	String	Cost center 1 ID	Must provide matching `_pct`	null
`cost_center_1_pct`	Float	Cost center 1 percentage	Number between 0 and 100. Only values greater than 0 are recorded	null
`cost_center_2_erp_id`	String	Cost center 2 ID	Must provide matching `_pct`	null
`cost_center_2_pct`	Float	Cost center 2 percentage	Number between 0 and 100. Only values greater than 0 are recorded	null
`cost_center_3_erp_id`	String	Cost center 3 ID	Must provide matching `_pct`	null
`cost_center_3_pct`	Float	Cost center 3 percentage	Number between 0 and 100. Only values greater than 0 are recorded	null
`cost_center_4_erp_id`	String	Cost center 4 ID	Must provide matching `_pct`	null
`cost_center_4_pct`	Float	Cost center 4 percentage	Number between 0 and 100. Only values greater than 0 are recorded	null
`cost_center_5_erp_id`	String	Cost center 5 ID	Must provide matching `_pct`	null
`cost_center_5_pct`	Float	Cost center 5 percentage	Number between 0 and 100. Only values greater than 0 are recorded	null

Cost center allocations

Up to 5 cost center pairs are accepted. For each pair i:

If you send either cost_center_i_erp_id or cost_center_i_pct, you must send both columns, otherwise the upload fails.
Each percentage must be between 0 and 100; outside that range the upload is rejected. The sum per invoice is not validated: it does not need to add up to 100.
Only rows with a percentage greater than 0 produce an allocation.
cost_center_i_erp_id is stored as given — it is not verified against Cost Centers.
Allocations are replaced per invoice, but only if the invoice carries at least one pair with a percentage greater than 0. An invoice that carries no cost centers keeps the allocation it already had: send all of an invoice’s cost centers together.

Invoice type and metrics

CREDIT means a sale with deferred payment terms; it does not mean a credit note or payment method.
A CASH invoice may remain OPEN, retain an outstanding balance, and stay in collection workflows. In that case the response carries a warning (CASH_WITH_PENDING_BALANCE), but the row is accepted.
Financial metrics —sales, balances, aging, DSO, turnover, collection effectiveness, behavior, projections, and derived executive metrics— use CREDIT invoices only.
Operational collections, statements, and campaign attribution continue to include both types.
Changing an existing invoice’s type also reclassifies its financial history.

Repeated rows and dropped rows

If the same erp_invoice_id appears in several rows, the last one is kept.
Rows whose erp_customer_id does not exist in Customers are dropped while the file is processed, and this is not reflected in the response, which had already confirmed the upload. If no customer in the file exists, nothing is processed.

Example CSV

erp_customer_id,erp_invoice_id,currency,original_amount,pending_amount,status,issue_date,due_date,advance_amount,allow_collection,invoice_type,cost_center_1_erp_id,cost_center_1_pct,cost_center_2_erp_id,cost_center_2_pct
CUST001,INV001,COP,1000000.00,500000.00,OPEN,2024-01-15,2024-02-15,0.00,1,CREDIT,CC001,60.0,CC002,40.0
CUST002,INV002,COP,500000.00,0.00,CLOSED,2024-01-20,2024-02-20,0.00,1,CASH,CC001,100.0,,