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.

Checklist antes de enviar

• Cabeçalho igual ao do modelo, sem colunas extras nem faltando
• asset_type igual a contract em todas as linhas, e igual ao tipo da configuração de cessão
• Uma linha por parcela, com o external_id repetido nas parcelas do mesmo contrato
• Colunas que não são de parcela idênticas entre as linhas do mesmo contrato
• installment_number em sequência de 1 a N, com vencimentos crescentes
• Colunas pre_fixed_* ou post_fixed_* preenchidas conforme o interest_rate_type
• borrower_gender preenchido para sacado pessoa física
• CPF/CNPJ com pontuação e dígito verificador válido
• Valores com ponto decimal e sem separador de milhar
• Arquivo salvo como CSV em UTF-8