Cessão por Arquivo

Além da inserção ativo a ativo pela API, é possível ceder um lote inteiro enviando um único arquivo pelo portal do gestor ou do consultor — ou, para a gestora, também pela API. O arquivo é validado linha a linha, convertido em ativos e segue exatamente o mesmo fluxo de elegibilidade, aprovação, termo de cessão e pagamento descrito na Introdução.

Envio por arquivo: portal ou API da gestora

No portal do gestor e do consultor, o envio é feito pela tela descrita abaixo. A gestora também pode enviar o arquivo pela API (manager-api, permissão de Escrita), em três chamadas:

1. POST /trade_receivables_files/fund_class/{fund_class_key}/assignment_configuration/{assignment_configuration_key}/assignment com external_id, filename (extensão .rem, .txt ou .csv), assignment_type (assignment ou substitution_assignment) e assignment_date (a data contábil aberta do fundo). A resposta traz em bucket_link a url e os fields de um upload por formulário (POST multipart), válido por 10 minutos.
2. Upload do arquivo para a url de bucket_link, com os fields devolvidos.
3. PUT /trade_receivables_files/fund_class/{fund_class_key}/assignment_configuration/{assignment_configuration_key}/assignment/{assignment_external_id}/file_uploaded, sem body, que dispara a validação do arquivo.

Esse fluxo ainda não tem página de referência; para detalhes, fale com integracao.dtvm@qitech.com.br. Consultoria e cedente cedem pela API ativo a ativo, pelo fluxo de criação de lote + inserção de ativos.

	Envio por arquivo	Inserção pela API
Como funciona	Um arquivo com todos os ativos do lote	Uma requisição por ativo
Formatos	CNAB 444 (duplicatas, CT-e, cheques e notas promissórias) e CSV (CCB, honorários e contratos parcelados)	JSON
Indicado para	Quem já gera CNAB para bancos/FIDCs e quer reaproveitar o layout	Quem quer controle e retorno por ativo, em tempo real
Retorno de erro	Consolidado ao final da validação do arquivo	Imediato, na resposta de cada ativo
Disponível em	Portal do gestor e do consultor; API da gestora	API de integração

Os dois caminhos produzem o mesmo lote e o mesmo resultado. Escolha um por lote — não é possível misturar arquivo e API no mesmo lote.

Formatos aceitos

O formato é determinado pelo tipo de ativo da configuração de cessão que você seleciona na tela.

Tipo de ativo da configuração	Formato do arquivo	Extensão	Modelo
duplicata_mercantil	CNAB 444, espécie 01	.rem · .txt	Exemplo
duplicata_servicos	CNAB 444, espécie 14	.rem · .txt	Exemplo
cte	CNAB 444, espécie 53	.rem · .txt	Exemplo
check (cheque) e promissory_note (nota promissória)	CNAB 444, espécies 51, 52 e 87 (cheque) e 02 e 06 (nota promissória)	.rem · .txt	—
ccb e structured_cci	CSV	.csv	Modelo
legal_fees (honorários advocatícios)	CSV	.csv	Modelo
contract (contratos parcelados)	CSV	.csv	Modelo

Em lotes de substituição, as linhas de recompra entram no mesmo CSV, com as colunas de recompra: modelo de substituição.

Cada formato atende tipos específicos

O CSV é aceito apenas para ccb, structured_cci, legal_fees e contract. Para cessão de duplicatas, CT-e, cheques e notas promissórias o formato é o CNAB 444 — o mesmo layout de remessa de cobrança usado no mercado, descrito em Layout CNAB 444 — Cessão. O layout do CSV de contratos parcelados está em Layout CSV — Contratos Parcelados.

Demais tipos de ativo, como discounted_contract, são cedidos pela API, ativo a ativo — não há formato de arquivo para eles hoje.

Fluxo do envio

Você, no portalQI Tech

1Dados do lote

Você, no portal

Cedente, configuração de cessão, substituição e meio de pagamento ao cedente.

2Upload do arquivo

Você, no portal

Arraste o arquivo .rem, .txt ou .csv para a área de upload e confirme o envio.

Validação do arquivo

QI Tech

Estrutura, posições, domínios e documentos são conferidos linha a linha.

Arquivo recusado

QI Tech

Uma única linha inválida recusa o arquivo inteiro. O portal exibe as linhas e os motivos.

Lote criado com os ativos

QI Tech

Cada linha vira um ativo e o lote entra no fluxo padrão de cessão.

Ver documentação →

Elegibilidade, aprovação, termo e pagamento

QI Tech

A partir daqui o fluxo é idêntico ao da cessão via API.

Ver documentação →

Passo a passo pela tela

No portal do gestor e no portal do consultor:

1. Acesse Ativos › Cessões e clique em Nova cessão.
2. Informe o cedente (CPF/CNPJ) e selecione a configuração de cessão — é ela que define o fundo, o tipo de ativo e, portanto, o formato de arquivo aceito.
3. Informe o identificador do lote e a data da cessão, que precisa ser a data contábil aberta do fundo — normalmente o dia útil corrente.
4. Marque Substituição se o lote tiver ativos de recompra.
5. Escolha o meio de pagamento ao cedente (Pix ou TED), quando aplicável.
6. Arraste o arquivo (.rem, .txt ou .csv) para a área de upload e confirme.

O lote passa a aparecer na listagem de cessões, com o status atualizado em tempo real conforme a validação avança.

Permissões

O usuário precisa da permissão de criação de cessão por arquivo no fundo em questão. A concessão é feita pelo administrador do portal em Usuários › Associações do fundo.

Acompanhamento e retorno de erros

A listagem de cessões mostra o andamento do lote de arquivo:

Etapa	O que significa	O que fazer
Aguardando arquivo	Lote criado, arquivo ainda não enviado	Faça o upload e confirme o envio
Validação em andamento	Arquivo recebido, sendo conferido linha a linha	Aguarde
Criando o lote	Arquivo válido, lote sendo criado	Aguarde
Inserindo os ativos	Cada linha está virando um ativo	Aguarde
Concluído	Todos os ativos inseridos	Acompanhe o lote pelo fluxo de cessão
Recusado	Arquivo recusado na validação	Corrija o arquivo e envie um lote novo, com um novo identificador

Quando o arquivo é recusado, o portal lista as linhas inválidas e, para cada uma, o campo, as posições no registro e a descrição do erro em português — por exemplo:

Linha 1, posições 218–234: o CNPJ do sacado '45678912000199' é inválido. Verifique o número do documento e tente novamente.

Validação é tudo ou nada

Uma única linha inválida recusa o arquivo inteiro — não existe processamento parcial. A análise para após 50 erros encontrados, então corrija os erros apontados e reenvie: podem existir outros adiante.

Regras que valem para qualquer arquivo

• O identificador do lote é único e definitivo. Um lote recusado não pode ser reenviado com o mesmo identificador.
• A data da cessão precisa ser a data contábil aberta do fundo. Outra data devolve erro na criação do lote.
• O arquivo é imutável. Para alterar qualquer informação, envie um lote novo.
• Cada linha vira um ativo, identificado pelo número do documento (posições 111–120 no CNAB). Em arquivos de duplicata e CT-e, duas linhas com o mesmo número de documento derrubam a cessão inteira — cada título precisa de um número próprio. Em CSV de CCB e de contrato parcelado, ao contrário, várias linhas com o mesmo identificador são lidas como as parcelas de um mesmo contrato.
• O cedente e o originador precisam estar previamente cadastrados e vinculados à configuração de cessão — veja Homologação de Cedente.

Envio por SFTP

Para operações de alto volume, a QI DTVM também disponibiliza a esteira de remessa por SFTP, com diretório dedicado por fundo e cedente e arquivo de retorno com os erros. É uma configuração sob demanda — fale com integracao.dtvm@qitech.com.br.