CSV Layout — Duplicatas, CT-e, Checks and Promissory Notes

Layout of the CSV file for the assignment of duplicatas, CT-e, checks and promissory notes (asset_type equal to duplicata_mercantil, duplicata_servicos, cte, check or promissory_note) accepted by QI DTVM. It is a CSV with one line per receivable: each line is an asset of the batch. It is an alternative to the CNAB 444 remittance, which is still accepted for the same receivables.

Where this file is used

This is the file submitted in the flow described in Assignment by File, through the manager's or the consultant's portal, or through the manager API. To assign a duplicata asset by asset through the API, see Asset Creation — Duplicata.

📄 Download the CSV template: trade duplicata · service duplicata · CT-e · check · promissory note

All templates share the same header; each one comes with an example line of its type. Delete the example line before putting in your data.

File structure

Item	Rule
Header	1 line, always the first, with the column names exactly as in the template
Data lines	1 per receivable. Each line is an asset of the batch
One type per file	Every line carries the asset type of the selected assignment configuration. To assign duplicatas and checks, for instance, send one batch per configuration
Extension	.csv
Separator	Comma (,) or semicolon (;) — detected from the header line
Encoding	UTF-8 (with or without BOM)
Dates	YYYY-MM-DD format
Amounts	Dot as decimal separator, no thousands separator. R$ 960,00 → 960.00
Documents	CPF as 000.000.000-00 and CNPJ as 00.000.000/0000-00, always with punctuation

The header is closed

Use the template header unchanged: do not translate, rename or add columns. Any column outside the template, or a missing required column, rejects the whole file before any line is checked. Columns that do not apply to the receivable of the line (for instance, invoice columns on a check) stay in the header and blank in the line.

Columns

Identification

Column	Requirement	Description
asset_type	required	Receivable type: duplicata_mercantil, duplicata_servicos, cte, check or promissory_note. It must equal the assignment configuration type, in every line
external_id	required	Receivable identifier in your system, up to 25 characters. It is the asset key and cannot repeat in the file
order_number	required	Receivable number, up to 45 characters. For checks and promissory notes it is the instrument number, up to 20 characters
originator_document_number	required	Originator CPF or CNPJ, with punctuation. It must be registered, bonded to the assignment configuration, and the same in every line of the file

Dates and amounts

Column	Requirement	Description
issue_date	required	Issue date, in YYYY-MM-DD. For duplicatas and CT-e it is the invoice issue date; for checks and promissory notes, the instrument's
maturity_date	required	Maturity date, in YYYY-MM-DD
face_value	required	Face value — what the debtor pays at maturity. Dot as decimal separator, up to 8 decimal places
total_purchase_value	required	Amount the fund pays for the receivable (purchase price). It cannot exceed face_value

Invoice

Column	Requirement	Description
invoice_access_key	conditional	NF-e or CT-e access key, exactly 44 digits, no spaces. The model (key positions 21–22) must be 55 for trade duplicata and 57 or 67 for CT-e. Required for duplicata_mercantil and cte; optional for duplicata_servicos; blank for checks and promissory notes
invoice_number	conditional	Invoice number, up to 9 digits. Required for duplicata_mercantil, duplicata_servicos and cte
invoice_serie	optional	Invoice series, up to 3 characters. Defaults to 1 when blank

Check

Column	Requirement	Description
bank_code	optional	Check bank code, 3 digits
agency	optional	Check branch, up to 5 digits

Debtor

Column	Requirement	Description
borrower_name	required	Debtor full name, up to 255 characters
borrower_document_number	required	Debtor CPF or CNPJ, with punctuation and consistent with borrower_person_type
borrower_person_type	required	natural_person or legal_person
borrower_email	optional	Debtor e-mail
borrower_phone_area_code	optional	Phone area code, exactly 2 digits. If you fill in the area code, fill in the number too
borrower_phone_number	optional	Debtor phone, 8 or 9 digits, without area code or punctuation
borrower_address_postal_code	required	ZIP code as 00000-000. Blank address fields are filled from the ZIP code
borrower_address_street	optional	Street, up to 255 characters
borrower_address_number	optional	Address number, up to 40 characters
borrower_address_neighborhood	optional	Neighborhood, up to 255 characters
borrower_address_city	optional	City, up to 255 characters
borrower_address_uf	optional	Two-letter state code, uppercase (e.g. SP)
borrower_address_country	optional	Three-letter country code (e.g. BRA). Defaults to BRA when blank

File rules

• One line per receivable. external_id cannot repeat in the file, and the batch asset count is the number of lines.
• One type per file. The asset_type of every line must be the assignment configuration type; a line of another type rejects the file.
• Invoice according to the type. duplicata_mercantil requires a model 55 invoice_access_key and cte a model 57 or 67 key, both with invoice_number; duplicata_servicos requires only invoice_number.
• Checks and promissory notes have no invoice. order_number is the instrument number and issue_date is its issue date. Bank and branch apply to checks only.
• face_value cannot be lower than total_purchase_value.
• Every line must have the same originator_document_number, and that originator must be registered and bonded to the assignment configuration.
• Substitution batch: the repurchase lines go into the same CSV, with the repurchase columns (assignor_document_number, settlement_type and repurchase_value) and the other columns blank.
• The batch identifier is unique and final. A rejected batch cannot be resent with the same identifier — send a new batch.
• Validation is all or nothing at the file stage. One invalid line rejects the whole file, and the report lists at most 50 errors per submission.

Most common errors

Message	Cause
A coluna obrigatória … está ausente no arquivo	The header was edited or saved from an old template
A coluna … não é reconhecida	Column from another template (CCB, contract) or a translated name
O campo Chave de acesso da nota fiscal é obrigatório	Trade duplicata or CT-e without invoice_access_key
O campo Chave de acesso da nota fiscal deve ter 44 dígitos, com o modelo 55 (NF-e) …	Key with spaces, punctuation, wrong length or a model that does not match the type (an NF-e key on a CT-e line, for instance)
O tipo de ativo … não é o da configuração da cessão	Line whose asset_type differs from the selected configuration type
O identificador … está duplicado	Two lines with the same external_id
O 'face_value' não pode ser menor que o 'total_purchase_value'	Purchase price above the face value

Example

modelo_cessao_duplicata_mercantil.csv (main columns)

asset_type,external_id,order_number,issue_date,maturity_date,face_value,total_purchase_value,invoice_access_key,invoice_number
duplicata_mercantil,DUPLICATA_0001,000123-1,2026-11-01,2026-12-25,1000.00,960.00,35261153020654000143550010000001231000001230,000000123
duplicata_mercantil,DUPLICATA_0002,000124-1,2026-11-01,2027-01-25,1000.00,940.00,35261153020654000143550010000001241000001240,000000124

The excerpt above shows only the main columns, for readability. The submitted file must have all template columns in the header — download the full template for your type: trade duplicata · service duplicata · CT-e · check · promissory note.

Checklist before sending

• Header identical to the template, with no extra or missing columns
• asset_type of every line equal to the assignment configuration type
• A different external_id per line, up to 25 characters
• Access key (44 digits) and invoice number on trade duplicatas and CT-e
• Invoice columns blank on checks and promissory notes
• face_value greater than or equal to total_purchase_value
• CPF/CNPJ with punctuation and a valid check digit
• Amounts with a decimal dot and no thousands separator
• File saved as CSV in UTF-8