Layout CSV — CCB

Layout do arquivo de cessão de CCB (asset_type igual a ccb) e de CCI estruturada (structured_cci) aceito pela QI DTVM. É um CSV com uma linha por parcela: as linhas que compartilham o mesmo external_id são as parcelas de uma mesma cédula 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, ou pela API da gestora. O leiaute é diferente do de contrato parcelado: não use as descrições de um para preencher o outro.

📄 Baixar modelo CSV

O modelo já vem com duas linhas de exemplo — uma CCB pré-fixada de pessoa física com duas parcelas. 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. Uma CCB 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
Percentuais e taxas	Sempre em fração decimal, nunca em pontos percentuais: 0.02 significa 2%
Documentos	CPF em 000.000.000-00 e CNPJ em 00.000.000/0000-00, sempre com a pontuação

O cabeçalho é fechado

As colunas obrigatórias precisam estar no cabeçalho, e qualquer coluna fora do modelo recusa o arquivo inteiro antes de qualquer linha ser conferida. As colunas opcionais podem ficar em branco ou fora do cabeçalho; o mais simples é manter o cabeçalho completo do modelo.

Colunas

Identificação e contrato

Coluna	Obrigatoriedade	Descrição
asset_type	obrigatória	ccb ou structured_cci, igual ao tipo da configuração de cessão, em todas as linhas
external_id	obrigatória	Identificador da CCB no seu sistema, até 50 caracteres. É a chave do ativo: as parcelas da mesma CCB 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 da CCB, até 20 caracteres
contract_issue_date	obrigatória	Data de emissão da CCB, em AAAA-MM-DD
contract_issue_value	obrigatória	Valor de emissão da CCB. Não pode ser menor que principal_value
contract_disbursement_date	opcional	Data de desembolso do crédito ao tomador, em AAAA-MM-DD
contract_signature_date	opcional	Data de assinatura da CCB, em AAAA-MM-DD
external_registry_code	opcional	Aceita, mas não é levada ao ativo. Deixe em branco

Valores e juros

Coluna	Obrigatoriedade	Descrição
total_purchase_value	obrigatória	Valor que o fundo paga pela CCB inteira
principal_value	obrigatória	Principal financiado, com ponto e 1 ou 2 casas decimais (1500.00; 1500 é recusado)
amortization_type	obrigatória	sac, price ou price_days
interest_rate_type	obrigatória	pre_fixed ou post_fixed
pre_fixed_calendar_base	obrigatória	Base de dias da taxa pré-fixada: workdays, calendar_360 ou calendar_365. Obrigatória também em CCB pós-fixada
pre_fixed_monthly_rate	obrigatória	Taxa mensal pré-fixada, em fração menor que 1 e com até 8 casas: 0.015 significa 1,5% ao mês
post_fixed_calendar_base	condicional	Só workdays. Obrigatória quando interest_rate_type é post_fixed
post_fixed_indexer	condicional	di, selic ou ipca. Obrigatória quando interest_rate_type é post_fixed
post_fixed_rate	condicional	Multiplicador do índice, com até 8 casas: 1 é 100% do índice, 1.2 é 120%. Obrigatória quando interest_rate_type é post_fixed
post_fixed_lag_reference	condicional	daily ou monthly; com ipca, só monthly. Obrigatória quando interest_rate_type é post_fixed
post_fixed_lag_amount	condicional	Defasagem em número inteiro a partir de 1. Obrigatória quando interest_rate_type é post_fixed

Todas as colunas desta seção são da CCB, não da parcela: repita o mesmo valor em todas as linhas da cédula.

Multa e juros de mora

Coluna	Obrigatoriedade	Descrição
delay_fine_type	obrigatória	percentage (fração do valor da parcela) ou fixed (valor fixo)
delay_fine_percentage_value	condicional	Multa em fração do valor da parcela, com ponto e 1 ou 2 casas: 0.02 é 2% — 2.00 seria 200%. Obrigatória quando delay_fine_type é percentage
delay_fine_amount	condicional	Multa em reais, com ponto e 1 ou 2 casas (15.00). Obrigatória quando delay_fine_type é fixed
delay_interest_method	obrigatória	simple ou compound
delay_interest_pre_fixed_monthly_rate	obrigatória	Juros de mora ao mês, em fração: 0.01 é 1% ao mês
delay_interest_pre_fixed_calendar_base	obrigatória	workdays, calendar_360 ou calendar_365

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	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 tomador paga no vencimento. 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, sem repetir no arquivo. É o valor a usar no nº de controle do participante da baixa em CNAB 444

Tomador

Coluna	Obrigatoriedade	Descrição
borrower_name	obrigatória	Nome completo do tomador, até 255 caracteres
borrower_document_number	obrigatória	CPF ou CNPJ do tomador, 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
borrower_mother_name	opcional	Nome da mãe. Usado apenas para pessoa física
borrower_birthdate	opcional	Data de nascimento, em AAAA-MM-DD. Usada apenas para pessoa física
borrower_activity_code	opcional	CNAE do tomador pessoa jurídica, no formato 00.00-0-00. Para pessoa física, deixe em branco
borrower_email	opcional	E-mail do tomador
borrower_phone_area_code	opcional	DDD, exatamente 2 dígitos. Se informar o DDD, informe também o número
borrower_phone_number	opcional	Telefone, 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, 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)

Consignado e correspondente bancário

Coluna	Obrigatoriedade	Descrição
consignee_name	opcional	Razão social do ente consignante — o empregador ou órgão que desconta a parcela em folha
consignee_document_number	condicional	CNPJ do ente consignante. Obrigatória quando consignee_name ou consignee_type é preenchida
consignee_type	condicional	public (órgão público), private (empregador privado, como no Crédito do Trabalhador) ou inss. Obrigatória quando consignee_document_number é preenchida
banking_correspondent_name	condicional	Razão social do correspondente bancário (corban) que originou a operação. Obrigatória quando banking_correspondent_document_number é preenchida
banking_correspondent_document_number	condicional	CNPJ do correspondente bancário. Obrigatória quando banking_correspondent_name é preenchida
social_security_benefit_number	condicional	Número do benefício (consignado INSS). Obrigatória quando social_security_benefit_status é preenchida
social_security_assistence_type	condicional	Espécie do benefício (consignado INSS). Obrigatória quando social_security_benefit_status é preenchida
social_security_benefit_status	opcional	Situação do benefício (ex.: reserved). Com as duas colunas acima, registra o benefício como garantia do ativo

Consignante e garantia dependem da configuração de cessão

Se a modalidade da configuração de cessão exige ente consignante (consignado INSS), a CCB sem consignee_* é recusada; se a modalidade não admite, a CCB com consignee_* é recusada. O mesmo vale para o benefício previdenciário como garantia. Em caso de dúvida, confirme a modalidade da configuração antes do envio.

Regras do arquivo

• Uma linha por parcela, um external_id por CCB. O contador de ativos do lote usa os external_id distintos.
• As linhas da mesma CCB 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_external_id não se repete no arquivo. Duas parcelas com o mesmo identificador recusam o arquivo.
• Todas as linhas precisam ter o mesmo originator_document_number, e esse originador precisa estar cadastrado e vinculado à configuração de cessão.
• Para substituição, acrescente as colunas de recompra no mesmo arquivo: veja o modelo de substituição.
• 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.

Baixa das CCBs cedidas por este arquivo

• CNAB 444: preencha installment_external_id na cessão e envie o mesmo valor no nº de controle do participante (posições 038–062) de cada linha da baixa. Sem esse identificador, a parcela não é encontrada.
• CSV de baixa: identifique a CCB pelo contract_number e a parcela pelo installment_number, como descrito em Liquidação por Arquivo.

Erros mais comuns

Mensagem	Causa
A coluna obrigatória … está ausente no arquivo	O cabeçalho foi editado ou salvo de um modelo antigo
A coluna … não é reconhecida	Coluna fora do modelo — por exemplo, uma coluna do leiaute de contrato parcelado
O campo … é obrigatório quando o campo … é preenchido	Consignante, correspondente ou benefício preenchido pela metade
O campo Percentual da multa por atraso deve ser uma fração …	Multa sem ponto ou com mais de 2 casas decimais
O identificador da parcela … já foi usado na linha …	installment_external_id repetido
Linhas com o mesmo identificador possuem dados inconsistentes nos campos: …	Alguma coluna que não é de parcela mudou entre as linhas da mesma CCB
O campo Número do contrato deve ter no máximo 20 caracteres	contract_number maior que o limite da CCB

Exemplo

modelo_cessao_ccb.csv (colunas principais)

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

O trecho acima mostra apenas as colunas principais, para leitura. Baixe o modelo completo para montar o arquivo.

Checklist antes de enviar

• Cabeçalho do modelo, sem colunas extras e com todas as obrigatórias
• asset_type igual ao tipo da configuração de cessão em todas as linhas
• Uma linha por parcela, com o external_id repetido nas parcelas da mesma CCB
• contract_number com até 20 caracteres e contract_issue_date preenchida
• Multa e taxas em fração (0.02 = 2%), com ponto decimal
• installment_external_id único por parcela, se a baixa for por CNAB 444
• Consignante e correspondente completos, ou totalmente em branco
• CPF/CNPJ com pontuação e dígito verificador válido
• Arquivo salvo como CSV em UTF-8