CSV Layout — CCB

Layout of the CCB assignment file (asset_type equal to ccb) and of the structured CCI file (structured_cci) 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 note 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. The layout is different from the installment contract one: do not use the descriptions of one to fill in the other.

📄 Download the CSV template

The template already comes with two example lines — a pre-fixed CCB for a natural person with two installments. 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 CCB 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
Percentages and rates	Always as a decimal fraction, never in percentage points: 0.02 means 2%
Documents	CPF as 000.000.000-00 and CNPJ as 00.000.000/0000-00, always with the punctuation

The header is closed

The mandatory columns must be in the header, and any column outside the template rejects the whole file before any line is checked. The optional columns can be left blank or out of the header; the simplest is to keep the complete header of the template.

Columns

Identification and contract

Column	Required	Description
asset_type	mandatory	ccb or structured_cci, equal to the type of the assignment configuration, on every line
external_id	mandatory	Identifier of the CCB in your system, up to 50 characters. It is the key of the asset: the installments of the same CCB 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	CCB number, up to 20 characters
contract_issue_date	mandatory	Issue date of the CCB, in YYYY-MM-DD
contract_issue_value	mandatory	Issue value of the CCB. It cannot be lower than principal_value
contract_disbursement_date	optional	Date the credit was disbursed to the borrower, in YYYY-MM-DD
contract_signature_date	optional	Signature date of the CCB, in YYYY-MM-DD
external_registry_code	optional	Accepted, but not carried over to the asset. Leave it blank

Values and interest

Column	Required	Description
total_purchase_value	mandatory	Value the fund pays for the whole CCB
principal_value	mandatory	Financed principal, with a dot and 1 or 2 decimal places (1500.00; 1500 is rejected)
amortization_type	mandatory	sac, price or price_days
interest_rate_type	mandatory	pre_fixed or post_fixed
pre_fixed_calendar_base	mandatory	Day-count base of the pre-fixed rate: workdays, calendar_360 or calendar_365. Also mandatory in a post-fixed CCB
pre_fixed_monthly_rate	mandatory	Pre-fixed monthly rate, as a fraction lower than 1 and with up to 8 decimal places: 0.015 means 1.5% per month
post_fixed_calendar_base	conditional	Only workdays. Mandatory when interest_rate_type is post_fixed
post_fixed_indexer	conditional	di, selic or ipca. Mandatory when interest_rate_type is post_fixed
post_fixed_rate	conditional	Multiplier of the index, with up to 8 decimal places: 1 is 100% of the index, 1.2 is 120%. Mandatory when interest_rate_type is post_fixed
post_fixed_lag_reference	conditional	daily or monthly; with ipca, only monthly. Mandatory when interest_rate_type is post_fixed
post_fixed_lag_amount	conditional	Lag as an integer starting at 1. Mandatory when interest_rate_type is post_fixed

All the columns in this section belong to the CCB, not to the installment: repeat the same value on every line of the note.

Late payment fine and interest

Column	Required	Description
delay_fine_type	mandatory	percentage (fraction of the installment value) or fixed (fixed value)
delay_fine_percentage_value	conditional	Fine as a fraction of the installment value, with a dot and 1 or 2 decimal places: 0.02 is 2% — 2.00 would be 200%. Mandatory when delay_fine_type is percentage
delay_fine_amount	conditional	Fine in reais, with a dot and 1 or 2 decimal places (15.00). Mandatory when delay_fine_type is fixed
delay_interest_method	mandatory	simple or compound
delay_interest_pre_fixed_monthly_rate	mandatory	Late payment interest per month, as a fraction: 0.01 is 1% per month
delay_interest_pre_fixed_calendar_base	mandatory	workdays, calendar_360 or calendar_365

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 borrower pays at maturity. 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, not repeated in the file. It is the value to use in the participant's control number of the CNAB 444 settlement

Borrower

Column	Required	Description
borrower_name	mandatory	Full name of the borrower, up to 255 characters
borrower_document_number	mandatory	CPF or CNPJ of the borrower, with punctuation and consistent with the borrower_person_type
borrower_person_type	mandatory	natural_person (natural person) or legal_person (legal entity)
borrower_gender	conditional	male or female. Mandatory when borrower_person_type is natural_person
borrower_mother_name	optional	Mother's name. Used only for a natural person
borrower_birthdate	optional	Date of birth, in YYYY-MM-DD. Used only for a natural person
borrower_activity_code	optional	CNAE of a legal entity borrower, in the 00.00-0-00 format. For a natural person, leave it blank
borrower_email	optional	E-mail of the borrower
borrower_phone_area_code	optional	Area code, exactly 2 digits. If you provide the area code, provide the number as well
borrower_phone_number	optional	Phone, 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)

Payroll deduction and banking correspondent

Column	Required	Description
consignee_name	optional	Corporate name of the consignee entity — the employer or agency that deducts the installment from the payroll
consignee_document_number	conditional	CNPJ of the consignee entity. Mandatory when consignee_name or consignee_type is filled in
consignee_type	conditional	public (public agency), private (private employer, as in Crédito do Trabalhador) or inss. Mandatory when consignee_document_number is filled in
banking_correspondent_name	conditional	Corporate name of the banking correspondent (corban) that originated the operation. Mandatory when banking_correspondent_document_number is filled in
banking_correspondent_document_number	conditional	CNPJ of the banking correspondent. Mandatory when banking_correspondent_name is filled in
social_security_benefit_number	conditional	Benefit number (INSS payroll loan). Mandatory when social_security_benefit_status is filled in
social_security_assistence_type	conditional	Benefit type (INSS payroll loan). Mandatory when social_security_benefit_status is filled in
social_security_benefit_status	optional	Status of the benefit (e.g. reserved). Together with the two columns above, it registers the benefit as collateral of the asset

Consignee and collateral depend on the assignment configuration

If the modality of the assignment configuration requires a consignee entity (INSS payroll loan), a CCB without consignee_* is rejected; if the modality does not allow it, a CCB with consignee_* is rejected. The same applies to the social security benefit as collateral. If in doubt, confirm the modality of the configuration before sending.

File rules

• One line per installment, one external_id per CCB. The asset counter of the batch uses the distinct external_id values.
• The lines of the same CCB 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_external_id is not repeated in the file. Two installments with the same identifier reject the file.
• Every line must have the same originator_document_number, and that originator must be registered and linked to the assignment configuration.
• For substitution, add the repurchase columns in the same file: see the substitution template.
• 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.

Settlement of the CCBs assigned by this file

• CNAB 444: fill in installment_external_id in the assignment and send the same value in the participant's control number (positions 038–062) of each line of the settlement. Without this identifier, the installment is not found.
• Settlement CSV: identify the CCB by the contract_number and the installment by the installment_number, as described in Settlement by File.

Most common errors

Message	Cause
The mandatory column … is missing in the file	The header was edited or saved from an old template
The column … is not recognized	Column outside the template — for example, a column of the installment contract layout
The field … is mandatory when the field … is filled in	Consignee, correspondent or benefit half filled in
The field Late payment fine percentage must be a fraction …	Fine without a dot or with more than 2 decimal places
The installment identifier … was already used on line …	Repeated installment_external_id
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 CCB
The field Contract number must have at most 20 characters	contract_number longer than the CCB limit

Example

modelo_cessao_ccb.csv (main columns)

asset_type,external_id,contract_number,principal_value,delay_fine_type,delay_fine_percentage_value,installment_number,installment_maturity_date,installment_face_value,installment_external_id
ccb,ATIVO_0001,1144927986/XXX,380.00,percentage,0.02,1,2026-12-25,200.46,ATIVO_0001_P1
ccb,ATIVO_0001,1144927986/XXX,380.00,percentage,0.02,2,2027-01-25,200.46,ATIVO_0001_P2

The excerpt above shows only the main columns, for readability. Download the complete template to assemble the file.

Checklist before sending

• Template header, with no extra columns and with all the mandatory ones
• asset_type equal to the type of the assignment configuration on every line
• One line per installment, with the external_id repeated on the installments of the same CCB
• contract_number with up to 20 characters and contract_issue_date filled in
• Fine and rates as fractions (0.02 = 2%), with a decimal dot
• installment_external_id unique per installment, if the settlement is by CNAB 444
• Consignee and correspondent complete, or entirely blank
• CPF/CNPJ with punctuation and a valid check digit
• File saved as CSV in UTF-8