Assignment by File

Besides inserting asset by asset through the API, you can assign a whole batch by sending a single file through the manager or consultant portal — or, for the manager, also through the API. The file is validated line by line, converted into assets and follows exactly the same eligibility, approval, assignment term and payment flow described in the Introduction.

Sending by file: portal or manager API

In the manager and consultant portal, the submission is done through the screen described below. The manager can also send the file through the API (manager-api, Write permission), in three calls:

1. POST /trade_receivables_files/fund_class/{fund_class_key}/assignment_configuration/{assignment_configuration_key}/assignment with external_id, filename (extension .rem, .txt or .csv), assignment_type (assignment or substitution_assignment) and assignment_date (the fund's open accounting date). The response returns in bucket_link the url and the fields of a form upload (multipart POST), valid for 10 minutes.
2. Upload of the file to the bucket_link url, with the fields returned.
3. PUT /trade_receivables_files/fund_class/{fund_class_key}/assignment_configuration/{assignment_configuration_key}/assignment/{assignment_external_id}/file_uploaded, with no body, which triggers the file validation.

This flow does not have a reference page yet; for details, talk to integracao.dtvm@qitech.com.br. The consultant and the assignor assign through the API asset by asset, through the batch creation + asset insertion flow.

	Sending by file	Insertion through the API
How it works	One file with all the assets of the batch	One request per asset
Formats	CNAB 444 (duplicatas, CT-e, checks and promissory notes) and CSV (CCB, legal fees and installment contracts)	JSON
Suitable for	Those who already generate CNAB for banks/FIDCs and want to reuse the layout	Those who want control and a return per asset, in real time
Error return	Consolidated at the end of the file validation	Immediate, in the response of each asset
Available on	Manager and consultant portal; manager API	Integration API

Both paths produce the same batch and the same result. Choose one per batch — it is not possible to mix file and API in the same batch.

Accepted formats

The format is determined by the asset type of the assignment configuration you select on the screen.

Asset type of the configuration	File format	Extension	Template
duplicata_mercantil	CNAB 444, instrument kind 01	.rem · .txt	Example
duplicata_servicos	CNAB 444, instrument kind 14	.rem · .txt	Example
cte	CNAB 444, instrument kind 53	.rem · .txt	Example
check (check) and promissory_note (promissory note)	CNAB 444, instrument kinds 51, 52 and 87 (check) and 02 and 06 (promissory note)	.rem · .txt	—
ccb and structured_cci	CSV	.csv	Template
legal_fees (legal fees)	CSV	.csv	Template
contract (installment contracts)	CSV	.csv	Template

In substitution batches, the repurchase lines go into the same CSV, with the repurchase columns: substitution template.

Each format serves specific types

CSV is accepted only for ccb, structured_cci, legal_fees and contract. For the assignment of duplicatas, CT-e, checks and promissory notes the format is CNAB 444 — the same collection remittance layout used in the market, described in CNAB 444 Layout — Assignment. The layout of the installment contract CSV is in CSV Layout — Installment Contracts.

Other asset types, such as discounted_contract, are assigned through the API, asset by asset — there is no file format for them today.

Flow of the submission

You, in the portalQI Tech

1Batch data

You, in the portal

Assignor, assignment configuration, substitution and means of payment to the assignor.

2File upload

You, in the portal

Drag the .rem, .txt or .csv file to the upload area and confirm the submission.

File validation

QI Tech

Structure, positions, domains and documents are checked line by line.

File refused

QI Tech

A single invalid line refuses the whole file. The portal shows the lines and the reasons.

Batch created with the assets

QI Tech

Each line becomes an asset and the batch enters the standard assignment flow.

Ver documentação →

Eligibility, approval, term and payment

QI Tech

From here on the flow is identical to the assignment through the API.

Ver documentação →

Step by step through the screen

In the manager portal and in the consultant portal:

1. Go to Assets › Assignments and click New assignment.
2. Provide the assignor (CPF/CNPJ) and select the assignment configuration — it is what defines the fund, the asset type and, therefore, the accepted file format.
3. Provide the batch identifier and the assignment date, which must be the fund's open accounting date — normally the current business day.
4. Check Substitution if the batch has repurchase assets.
5. Choose the means of payment to the assignor (Pix or TED), when applicable.
6. Drag the file (.rem, .txt or .csv) to the upload area and confirm.

The batch then appears in the assignment listing, with the status updated in real time as the validation advances.

Permissions

The user needs the permission to create an assignment by file in the fund in question. It is granted by the portal administrator in Users › Fund associations.

Tracking and error return

The assignment listing shows the progress of the file batch:

Stage	What it means	What to do
Awaiting file	Batch created, file not sent yet	Upload it and confirm the submission
Validation in progress	File received, being checked line by line	Wait
Creating the batch	File valid, batch being created	Wait
Inserting the assets	Each line is becoming an asset	Wait
Completed	All the assets inserted	Track the batch through the assignment flow
Refused	File refused in the validation	Fix the file and send a new batch, with a new identifier

When the file is refused, the portal lists the invalid lines and, for each one, the field, the positions in the record and the description of the error in Portuguese — for example:

Linha 1, posições 218–234: o CNPJ do sacado '45678912000199' é inválido. Verifique o número do documento e tente novamente.

Validation is all or nothing

A single invalid line refuses the whole file — there is no partial processing. The analysis stops after 50 errors found, so fix the errors reported and resend: there may be others further ahead.

Rules that apply to any file

• The batch identifier is unique and definitive. A refused batch cannot be resent with the same identifier.
• The assignment date must be the fund's open accounting date. Another date returns an error when the batch is created.
• The file is immutable. To change any information, send a new batch.
• Each line becomes an asset, identified by the document number (positions 111–120 in CNAB). In duplicata and CT-e files, two lines with the same document number bring down the whole assignment — each instrument needs its own number. In CCB and installment contract CSVs, on the contrary, several lines with the same identifier are read as the installments of the same contract.
• The assignor and the originator must be registered beforehand and linked to the assignment configuration — see Assignor Onboarding.

Submission by SFTP

For high-volume operations, QI DTVM also provides the remittance pipeline by SFTP, with a dedicated directory per fund and assignor and a return file with the errors. It is an on-demand configuration — talk to integracao.dtvm@qitech.com.br.