CSV Layout — Installment Contracts

Layout of the installment contract assignment file (asset_type equal to contract) accepted by QI DTVM. It is a CSV with one line per installment: the lines that share the same external_id are the installments of the same contract and form a single asset.

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 an installment contract asset by asset through the API, see Asset Creation — Installment Contract.

📄 Download the CSV template

The template already comes with example lines filled in — two contracts, a pre-fixed one for a natural person with two installments and a post-fixed one for a legal entity with one installment. Delete the example lines 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 installment. A contract with 12 installments takes up 12 lines
Grouping	Lines with the same `external_id` are the same asset. The batch is counted in assets, not in lines
Extension	`.csv`
Separator	Comma (`,`) or semicolon (`;`) — detected from the header line
Encoding	UTF-8 (with or without BOM)
Dates	`YYYY-MM-DD` format
Values	Dot as the decimal separator, without a thousands separator. `R$ 900,00` → `900.00`
Documents	CPF as `000.000.000-00` and CNPJ as `00.000.000/0000-00`, always with the punctuation

The header is closed

Use the header of the template without changes: do not translate, do not rename and do not add columns. Any column outside the template, or a missing mandatory column, rejects the whole file before any line is checked.

Columns

Identification

Column	Required	Description
`asset_type`	mandatory	Asset type. For an installment contract, the only accepted value is `contract`, on every line
`external_id`	mandatory	Identifier of the contract in your system, up to 50 characters. It is the key of the asset: the installments of the same contract repeat the same value
`originator_document_number`	mandatory	CPF or CNPJ of the originator, with punctuation. It must be registered and linked to the assignment configuration, and be the same on every line of the file
`contract_number`	mandatory	Contract number, up to 50 characters. Sent exactly as written, without normalization
`contract_issue_date`	optional	Issue date of the contract, in `YYYY-MM-DD`

Values and interest

Column	Required	Description
`total_purchase_value`	mandatory	Value the fund pays for the whole contract. Repeat the same value on every line of the contract
`interest_rate_type`	mandatory	`pre_fixed` or `post_fixed`. It defines which rate columns become mandatory
`calendar_base`	optional	Day-count base of the contract: `workdays`, `calendar_360` or `calendar_365`. When blank, `workdays` is assumed
`pre_fixed_calendar_base`	conditional	Day-count base of the pre-fixed rate. Mandatory when `interest_rate_type` is `pre_fixed`
`pre_fixed_monthly_rate`	conditional	Pre-fixed monthly rate, as a decimal fraction lower than 1 and with up to 8 decimal places: `0.015` means 1.5% per month. Mandatory when `interest_rate_type` is `pre_fixed`
`post_fixed_calendar_base`	conditional	Day-count base of the post-fixed adjustment. Mandatory when `interest_rate_type` is `post_fixed`
`post_fixed_indexer`	conditional	Index that adjusts the contract: `di`, `selic` or `ipca`. Mandatory when `interest_rate_type` is `post_fixed`
`post_fixed_rate`	conditional	Rate applied over the indexer. `1` means 100% of the index. Mandatory when `interest_rate_type` is `post_fixed`
`post_fixed_lag_reference`	conditional	Unit of the index lag: `daily` or `monthly`. Mandatory when `interest_rate_type` is `post_fixed`
`post_fixed_lag_amount`	conditional	Amount of the lag, as an integer (e.g. `2` with `monthly` uses the index from two months earlier). Mandatory when `interest_rate_type` is `post_fixed`

Premium and deduction are not in the file

The installment contract CSV has no premium or deduction columns — they do not apply to this asset type. The acquisition value is always the total_purchase_value.

Installments

Column	Required	Description
`installment_number`	mandatory	Installment number, an integer starting at 1. One line per installment
`installment_maturity_date`	mandatory	Maturity date of the installment, in `YYYY-MM-DD`. The dates must increase along with the installment number
`installment_face_value`	mandatory	Face value of the installment — how much the drawee pays at maturity. Dot as the decimal separator, up to 8 decimal places
`installment_principal_value`	optional	Part of the principal amortized in this installment
`installment_external_id`	optional	Identifier of the installment in your system, up to 50 characters

Drawee

Column	Required	Description
`borrower_name`	mandatory	Full name of the drawee, up to 255 characters
`borrower_document_number`	mandatory	CPF or CNPJ of the drawee, with punctuation and consistent with the `borrower_person_type`
`borrower_person_type`	mandatory	`natural_person` or `legal_person`
`borrower_gender`	conditional	`male` or `female`. Mandatory when `borrower_person_type` is `natural_person`; leave it blank for a legal entity
`borrower_mother_name`	optional	Mother's name of the drawee. Used only for a natural person
`borrower_birthdate`	optional	Date of birth of the drawee, in `YYYY-MM-DD`. Used only for a natural person
`borrower_email`	optional	E-mail of the drawee
`borrower_phone_area_code`	optional	Area code of the phone, exactly 2 digits. If you provide the area code, provide the number as well
`borrower_phone_number`	optional	Phone of the drawee, 8 or 9 digits, without the area code and without punctuation
`borrower_address_postal_code`	optional	Postal code in the `00000-000` format. If you fill in any other address field, the postal code becomes mandatory
`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	2-letter state abbreviation, in uppercase (e.g. `SP`)
`borrower_address_country`	optional	Country in 3 letters (e.g. `BRA`)

File rules

One line per installment, one external_id per contract. The asset counter of the batch uses the distinct external_id values.
The lines of the same contract must be identical outside the installment columns. Every column whose name does not contain installment is checked across the lines that share the external_id; any divergence points out the differing fields and rejects the file.
The payment flow must be increasing. A higher installment with a maturity earlier than that of a lower installment rejects the file.
installment_number must form the sequence 1, 2, 3, … within each contract, ordered by maturity. Numbering with a gap or a repetition makes the asset be rejected with the code TRC000174, without bringing down the other assets of the file.
Every line must have the same originator_document_number, and that originator must be registered and linked to the assignment configuration.
Do not include the repurchase columns (assignor_document_number and settlement_type): with them, the file is read as a substitution and is rejected. An installment contract substitution batch is not accepted by file today.
The batch identifier is unique and definitive. A rejected batch cannot be resubmitted with the same identifier — submit a new batch.
The 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
Mandatory column missing in the header	The header was edited or saved from an old template
Lines with the same identifier have inconsistent data in the fields: …	Some column that is not an installment column changed between the lines of the same contract
Invalid payment flow for the asset …	Maturities out of order in relation to the installment number
Installment number … invalid	`installment_number` with text, a decimal or blank
Contract … must have the installment numbers in a sequence starting at 1	Gap or repetition in the installment numbering (`TRC000174`)
Document number … is not valid	CPF or CNPJ without punctuation or with an invalid check digit
This batch cannot receive this asset type	The `asset_type` of the file is not the one of the selected assignment configuration

Example

modelo_cessao_contrato_parcelado.csv (main columns)
asset_type,external_id,contract_number,total_purchase_value,interest_rate_type,borrower_name,borrower_document_number,installment_number,installment_maturity_date,installment_face_value
contract,CONTRATO_0001,1144927986/XXX,900.00,pre_fixed,José de Souza,969.698.790-03,1,2026-12-25,500.46
contract,CONTRATO_0001,1144927986/XXX,900.00,pre_fixed,José de Souza,969.698.790-03,2,2027-01-25,500.46
contract,CONTRATO_0002,2244927986/XXX,450.00,post_fixed,Empresa Souza LTDA,11.222.333/0001-81,1,2026-12-25,500.46

The excerpt above shows only the main columns, for readability. The submitted file must have all the columns of the template in the header — download the complete template.

File structure​

Columns​

Identification​

Values and interest​

Installments​

Drawee​

File rules​

Most common errors​

Example​

Checklist before sending​