Layout CSV — Contratos Parcelados

Layout do arquivo de cessão de contratos parcelados (asset_type igual a contract) aceito pela QI CTVM. É um CSV com uma linha por parcela: as linhas que compartilham o mesmo external_id são as parcelas de um mesmo contrato e formam um único ativo.

Onde este arquivo é usado

Este é o arquivo enviado no fluxo descrito em Cessão por Arquivo, pelo portal do gestor ou do consultor. Para ceder contrato parcelado ativo a ativo pela API, veja Criação de Ativo — Contrato Parcelado.

📄 Baixar modelo CSV

O modelo já vem com linhas de exemplo preenchidas — dois contratos, um pré-fixado de pessoa física com duas parcelas e um pós-fixado de pessoa jurídica com uma parcela. Apague as linhas de exemplo antes de colocar os seus dados.

Estrutura do arquivo

Item	Regra
Cabeçalho	1 linha, sempre a primeira, com os nomes das colunas exatamente como no modelo
Linhas de dados	1 por parcela. Um contrato com 12 parcelas ocupa 12 linhas
Agrupamento	Linhas com o mesmo `external_id` são o mesmo ativo. O lote é contado em ativos, não em linhas
Extensão	`.csv`
Separador	Vírgula (`,`) ou ponto e vírgula (`;`) — detectado a partir da linha de cabeçalho
Codificação	UTF-8 (com ou sem BOM)
Datas	Formato `AAAA-MM-DD`
Valores	Ponto como separador decimal, sem separador de milhar. `R$ 900,00` → `900.00`
Documentos	CPF em `000.000.000-00` e CNPJ em `00.000.000/0000-00`, sempre com a pontuação

O cabeçalho é fechado

Use o cabeçalho do modelo sem alterações: não traduza, não renomeie e não acrescente colunas. Qualquer coluna fora do modelo, ou a falta de uma coluna obrigatória, recusa o arquivo inteiro antes de qualquer linha ser conferida.

Colunas

Identificação

Coluna	Obrigatoriedade	Descrição
`asset_type`	obrigatória	Tipo do ativo. Para contrato parcelado, o único valor aceito é `contract`, em todas as linhas
`external_id`	obrigatória	Identificador do contrato no seu sistema, até 50 caracteres. É a chave do ativo: as parcelas do mesmo contrato repetem o mesmo valor
`originator_document_number`	obrigatória	CPF ou CNPJ do originador, com pontuação. Precisa estar cadastrado e vinculado à configuração de cessão, e ser o mesmo em todas as linhas do arquivo
`contract_number`	obrigatória	Número do contrato, até 50 caracteres. Enviado exatamente como escrito, sem normalização
`contract_issue_date`	opcional	Data de emissão do contrato, em `AAAA-MM-DD`

Valores e juros

Coluna	Obrigatoriedade	Descrição
`total_purchase_value`	obrigatória	Valor que o fundo paga pelo contrato inteiro. Repita o mesmo valor em todas as linhas do contrato
`interest_rate_type`	obrigatória	`pre_fixed` ou `post_fixed`. Define quais colunas de taxa passam a ser obrigatórias
`calendar_base`	opcional	Base de contagem de dias do contrato: `workdays`, `calendar_360` ou `calendar_365`. Em branco, é assumido `workdays`
`pre_fixed_calendar_base`	condicional	Base de contagem de dias da taxa pré-fixada. Obrigatória quando `interest_rate_type` é `pre_fixed`
`pre_fixed_monthly_rate`	condicional	Taxa mensal pré-fixada, em fração decimal menor que 1 e com até 8 casas: `0.015` significa 1,5% ao mês. Obrigatória quando `interest_rate_type` é `pre_fixed`
`post_fixed_calendar_base`	condicional	Base de contagem de dias da correção pós-fixada. Obrigatória quando `interest_rate_type` é `post_fixed`
`post_fixed_indexer`	condicional	Índice que corrige o contrato: `di`, `selic` ou `ipca`. Obrigatória quando `interest_rate_type` é `post_fixed`
`post_fixed_rate`	condicional	Taxa aplicada sobre o indexador. `1` significa 100% do índice. Obrigatória quando `interest_rate_type` é `post_fixed`
`post_fixed_lag_reference`	condicional	Unidade da defasagem do índice: `daily` ou `monthly`. Obrigatória quando `interest_rate_type` é `post_fixed`
`post_fixed_lag_amount`	condicional	Quantidade de defasagem, em número inteiro (ex.: `2` com `monthly` usa o índice de dois meses antes). Obrigatória quando `interest_rate_type` é `post_fixed`

Ágio e dedução não entram no arquivo

O CSV de contrato parcelado não tem colunas de ágio ou dedução — elas não se aplicam a este tipo de ativo. O valor de aquisição é sempre o total_purchase_value.

Parcelas

Coluna	Obrigatoriedade	Descrição
`installment_number`	obrigatória	Número da parcela, inteiro começando em 1. Uma linha por parcela
`installment_maturity_date`	obrigatória	Data de vencimento da parcela, em `AAAA-MM-DD`. As datas precisam crescer junto com o número da parcela
`installment_face_value`	obrigatória	Valor de face da parcela — quanto o sacado paga no vencimento. Ponto como separador decimal, até 8 casas
`installment_principal_value`	opcional	Parte do principal amortizada nesta parcela
`installment_external_id`	opcional	Identificador da parcela no seu sistema, até 50 caracteres

Sacado

Coluna	Obrigatoriedade	Descrição
`borrower_name`	obrigatória	Nome completo do sacado, até 255 caracteres
`borrower_document_number`	obrigatória	CPF ou CNPJ do sacado, com pontuação e compatível com o `borrower_person_type`
`borrower_person_type`	obrigatória	`natural_person` (pessoa física) ou `legal_person` (pessoa jurídica)
`borrower_gender`	condicional	`male` ou `female`. Obrigatória quando `borrower_person_type` é `natural_person`; deixe em branco para pessoa jurídica
`borrower_mother_name`	opcional	Nome da mãe do sacado. Usado apenas para pessoa física
`borrower_birthdate`	opcional	Data de nascimento do sacado, em `AAAA-MM-DD`. Usada apenas para pessoa física
`borrower_email`	opcional	E-mail do sacado
`borrower_phone_area_code`	opcional	DDD do telefone, exatamente 2 dígitos. Se informar o DDD, informe também o número
`borrower_phone_number`	opcional	Telefone do sacado, 8 ou 9 dígitos, sem DDD e sem pontuação
`borrower_address_postal_code`	opcional	CEP no formato `00000-000`. Se preencher qualquer outro campo de endereço, o CEP passa a ser obrigatório
`borrower_address_street`	opcional	Logradouro, até 255 caracteres
`borrower_address_number`	opcional	Número do endereço, até 40 caracteres
`borrower_address_neighborhood`	opcional	Bairro, até 255 caracteres
`borrower_address_city`	opcional	Cidade, até 255 caracteres
`borrower_address_uf`	opcional	Sigla de 2 letras do estado, em maiúsculas (ex.: `SP`)
`borrower_address_country`	opcional	País em 3 letras (ex.: `BRA`)

Regras do arquivo

Uma linha por parcela, um external_id por contrato. O contador de ativos do lote usa os external_id distintos.
As linhas do mesmo contrato precisam ser idênticas fora das colunas de parcela. Todas as colunas cujo nome não contém installment são conferidas entre as linhas que compartilham o external_id; qualquer divergência aponta os campos diferentes e recusa o arquivo.
O fluxo de pagamento precisa ser crescente. Parcela maior com vencimento anterior ao de uma parcela menor recusa o arquivo.
installment_number precisa formar a sequência 1, 2, 3, … dentro de cada contrato, ordenado por vencimento. Uma numeração com salto ou repetição faz o ativo ser recusado com o código TRC000174, sem derrubar os demais ativos do arquivo.
Todas as linhas precisam ter o mesmo originator_document_number, e esse originador precisa estar cadastrado e vinculado à configuração de cessão.
Não inclua as colunas de recompra (assignor_document_number e settlement_type): com elas o arquivo passa a ser lido como substituição e é recusado. Lote de substituição de contrato parcelado não é aceito por arquivo hoje.
O identificador do lote é único e definitivo. Um lote recusado não pode ser reenviado com o mesmo identificador — envie um lote novo.
A validação é tudo ou nada na etapa de arquivo. Uma linha inválida recusa o arquivo inteiro, e o relatório lista no máximo 50 erros por envio.

Erros mais comuns

Mensagem	Causa
Coluna obrigatória ausente no cabeçalho	O cabeçalho foi editado ou salvo de um modelo antigo
Linhas com o mesmo identificador possuem dados inconsistentes nos campos: …	Alguma coluna que não é de parcela mudou entre as linhas do mesmo contrato
Fluxo de pagamento inválido para o ativo …	Vencimentos fora de ordem em relação ao número da parcela
Número da parcela … inválido	`installment_number` com texto, decimal ou em branco
O contrato … deve ter os números das parcelas em sequência iniciando em 1	Salto ou repetição na numeração das parcelas (`TRC000174`)
O número de documento … não é válido	CPF ou CNPJ sem pontuação ou com dígito verificador inválido
Esse lote não pode receber esse tipo de ativo	O `asset_type` do arquivo não é o da configuração de cessão selecionada

Exemplo

modelo_cessao_contrato_parcelado.csv (colunas principais)
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,Jove de Souza,593.607.530-33,1,2026-12-25,500.46
contract,CONTRATO_0001,1144927986/XXX,900.00,pre_fixed,Jove de Souza,593.607.530-33,2,2027-01-25,500.46
contract,CONTRATO_0002,2244927986/XXX,450.00,post_fixed,Empresa Souza LTDA,53.020.654/0001-43,1,2026-12-25,500.46

O trecho acima mostra apenas as colunas principais, para leitura. O arquivo enviado precisa ter todas as colunas do modelo no cabeçalho — baixe o modelo completo.

Estrutura do arquivo​

Colunas​

Identificação​

Valores e juros​

Parcelas​

Sacado​

Regras do arquivo​

Erros mais comuns​

Exemplo​

Checklist antes de enviar​