Layout CSV — Duplicatas, CT-e, Cheques e Notas Promissórias

Layout do arquivo CSV de cessão de duplicatas, CT-e, cheques e notas promissórias (asset_type igual a duplicata_mercantil, duplicata_servicos, cte, check ou promissory_note) aceito pela QI DTVM. É um CSV com uma linha por título: cada linha é um ativo do lote. É uma alternativa à remessa CNAB 444, que continua aceita para os mesmos títulos.

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. Para ceder duplicata ativo a ativo pela API, veja Criação de Ativo — Duplicata.

📄 Baixar modelo CSV: duplicata mercantil · duplicata de serviços · CT-e · cheque · nota promissória

Todos os modelos têm o mesmo cabeçalho; cada um vem com uma linha de exemplo do seu tipo. Apague a linha 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 título. Cada linha é um ativo do lote
Um tipo por arquivo	Todas as linhas têm o asset_type da configuração de cessão selecionada. Para ceder duplicatas e cheques, por exemplo, envie um lote para cada configuração
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$ 960,00 → 960.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 que não se aplicam ao título da linha (por exemplo, nota fiscal em um cheque) ficam no cabeçalho e em branco na linha.

Colunas

Identificação

Coluna	Obrigatoriedade	Descrição
asset_type	obrigatória	Tipo do título: duplicata_mercantil, duplicata_servicos, cte, check ou promissory_note. Precisa ser igual ao tipo da configuração de cessão, em todas as linhas
external_id	obrigatória	Identificador do título no seu sistema, até 25 caracteres. É a chave do ativo e não pode se repetir no arquivo
order_number	obrigatória	Número do título (seu número), até 45 caracteres. No cheque e na nota promissória é o número do próprio título, com até 20 caracteres
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

Datas e valores

Coluna	Obrigatoriedade	Descrição
issue_date	obrigatória	Data de emissão, em AAAA-MM-DD. Nas duplicatas e no CT-e é a data de emissão da nota; no cheque e na nota promissória, a do título
maturity_date	obrigatória	Data de vencimento do título, em AAAA-MM-DD
face_value	obrigatória	Valor de face — quanto o sacado paga no vencimento. Ponto como separador decimal, até 8 casas
total_purchase_value	obrigatória	Valor que o fundo paga pelo título (preço de aquisição). Não pode ser maior que o face_value

Nota fiscal

Coluna	Obrigatoriedade	Descrição
invoice_access_key	condicional	Chave de acesso da NF-e ou do CT-e, exatamente 44 dígitos, sem espaços. O modelo (posições 21–22 da chave) precisa ser 55 na duplicata mercantil e 57 ou 67 no CT-e. Obrigatória para duplicata_mercantil e cte; opcional para duplicata_servicos; em branco para cheque e nota promissória
invoice_number	condicional	Número da nota fiscal, até 9 dígitos. Obrigatória para duplicata_mercantil, duplicata_servicos e cte
invoice_serie	opcional	Série da nota fiscal, até 3 caracteres. Em branco, é assumida a série 1

Cheque

Coluna	Obrigatoriedade	Descrição
bank_code	opcional	Código do banco do cheque, 3 dígitos
agency	opcional	Agência do cheque, até 5 dígitos

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_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	obrigatória	CEP no formato 00000-000. Os demais campos de endereço em branco são completados pelo CEP
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). Em branco, é assumido BRA

Regras do arquivo

• Uma linha por título. O external_id não pode se repetir no arquivo, e o contador de ativos do lote é o número de linhas.
• Um tipo por arquivo. O asset_type de todas as linhas precisa ser o da configuração de cessão; uma linha de outro tipo recusa o arquivo.
• Nota fiscal conforme o tipo. duplicata_mercantil exige invoice_access_key de modelo 55 e cte exige modelo 57 ou 67, ambos com invoice_number; duplicata_servicos exige só invoice_number.
• Cheque e nota promissória não têm nota fiscal. O order_number é o número do título e a issue_date é a data de emissão. Banco e agência valem apenas para cheque.
• O face_value não pode ser menor que o total_purchase_value.
• Todas as linhas precisam ter o mesmo originator_document_number, e esse originador precisa estar cadastrado e vinculado à configuração de cessão.
• Lote de substituição: as linhas de recompra entram no mesmo CSV, com as colunas de recompra (assignor_document_number, settlement_type e repurchase_value) e as demais colunas em branco.
• 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
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 de outro modelo (CCB, contrato) ou nome traduzido
O campo Chave de acesso da nota fiscal é obrigatório	Duplicata mercantil ou CT-e sem invoice_access_key
O campo Chave de acesso da nota fiscal deve ter 44 dígitos, com o modelo 55 (NF-e) …	Chave com espaços, pontuação, tamanho errado ou modelo que não é o do tipo (NF-e numa linha de CT-e, por exemplo)
O tipo de ativo … não é o da configuração da cessão	Linha com asset_type diferente do tipo da configuração selecionada
O identificador … está duplicado	Duas linhas com o mesmo external_id
O 'face_value' não pode ser menor que o 'total_purchase_value'	Preço de aquisição acima do valor de face

Exemplo

modelo_cessao_duplicata_mercantil.csv (colunas principais)

asset_type,external_id,order_number,issue_date,maturity_date,face_value,total_purchase_value,invoice_access_key,invoice_number
duplicata_mercantil,DUPLICATA_0001,000123-1,2026-11-01,2026-12-25,1000.00,960.00,35261153020654000143550010000001231000001230,000000123
duplicata_mercantil,DUPLICATA_0002,000124-1,2026-11-01,2027-01-25,1000.00,940.00,35261153020654000143550010000001241000001240,000000124

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 do seu tipo: duplicata mercantil · duplicata de serviços · CT-e · cheque · nota promissória.

Checklist antes de enviar

• Cabeçalho igual ao do modelo, sem colunas extras nem faltando
• asset_type de todas as linhas igual ao tipo da configuração de cessão
• Um external_id diferente por linha, com até 25 caracteres
• Chave de acesso (44 dígitos) e número da nota nas duplicatas mercantis e CT-e
• Colunas de nota fiscal em branco nos cheques e notas promissórias
• face_value maior ou igual ao total_purchase_value
• 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