CSV import — Receivables

Import batches of receivables from a CSV file.

Where it lives

There is no "Import" in the menu, and no import screen. The way in is:

Receivables → the Import pill, on the listing itself.

You need a specific company selected in the header. Under "all companies", the panel only warns: "Select a specific company to import receivables."

The Download template button hands you a sample CSV with the right header — the safest place to start, because it already comes in the right encoding.

CSV columns

Column	Required	Description
description	✅	Receivable description
amount	✅	Amount in reais (e.g. 299,00)
due_date	✅	Due date (dd/MM/yyyy)
competence_date	—	Competence date (dd/MM/yyyy)
document	—	Document identifier
document_date	—	Issue date (dd/MM/yyyy)
document_number	—	Invoice number
person_name	—	Customer name (created if it doesn't exist)
category_name	—	Category name (must already exist — it is not created; an unmatched name is ignored)
cost_center_name	—	Classification center name (must already exist — it is not created; an unmatched name is ignored)
payment_method	—	Method: pix, boleto, dinheiro, cartao_credito, etc.
notes	—	Notes
ir_relevant	—	true or false

The names above are the canonical ones, but every header also accepts its Portuguese equivalent — descricao, valor, vencimento, cliente, categoria, observacao and so on. Columns the system doesn't know are ignored silently.

The receivables file accepts the same columns as payables, except the payment ones (barcode, PIX, bank details, tax, scheduling) — those exist only on the payables side, which is the one that sends money to the bank.

Format

The parser is more forgiving than it looks. You don't have to normalize the file first:

• Header — case, accents and spaces don't matter: Descrição, DESCRICAO and descricao are the same column.
• Separator — , or ;, detected from the header line. On a tie, ;.
• Dates — 31/12/2026, 31-12-2026 or 2026-12-31.
• Amounts — 1234.56, 1.234,56, 1234,56, with or without R$. The amount has to be greater than zero.
• ir_relevant — true/false, sim/nao, yes/no, 1/0, s/y/n. Accents and case don't matter. Empty leaves the field blank.

warning

The encoding has to be UTF-8, and this is where most files trip up. Excel in Portuguese saves CSV as Windows-1252 by default, and the system refuses it with a message that stays in Portuguese: "Arquivo não está em UTF-8. Salve novamente em UTF-8 e tente novamente." ("The file is not UTF-8. Save it again as UTF-8 and try once more.") In Excel, use Save As → CSV UTF-8; or start from the downloaded template.

Other whole-file rejections: an extension other than .csv, a size above 5 MB, an empty file, and a missing required column — "Colunas obrigatórias ausentes: amount" ("Missing required columns: amount"). In those cases there is no preview: the problem is the file, not a row.

Importing

1. Upload the file. The system reads it and shows the preview.
2. Valid rows come pre-selected. Click a row to deselect it.
3. Click Import N lines.

Rows with errors

Invalid rows show up in the preview with a red marker, and can't be selected or edited there. There is no fixing them inside the system. The screen itself tells you the way out: "Uncheck the rows with errors or fix them in the file and upload again."

The number in Row N is the line number in the file, counting the header — the first data line is 2.

Writing happens in the background

On confirmation you get "Import started in the background" and a progress dialog. You can close the dialog — the import keeps going, and progress stays visible in the lower-right corner.

Links to other records

The customer is created automatically when the name doesn't exist. Category and classification center are not created: an unmatched name leaves the field blank, with no error and no warning.

Automatic rules are applied to the imported records.

History

Below the panel, the History section lists the imports with date, file, status (Queued, Running, Completed, Failed, Cancelled), how many rows went in out of the total, and who asked for it.

Authorization

note

Imported receivables don't go through authorization. The payment authorization gate exists only on the payables side, because that's where money leaves. An imported receivable lands straight in the normal list and in the totals.