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. 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.
O envio de arquivo de cessão é feito pelo portal, não pela API de integração. Pela API, a cessão é feita pelo fluxo de criação de lote + inserção de ativos, ativo a ativo, sem arquivo.
| 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, contratos, CTe) e CSV (CCB) | 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 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 |
ccb e structured_cci | CSV | .csv | Modelo |
legal_fees (honorários advocatícios) | 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.
O CSV é aceito apenas para ccb, structured_cci e legal_fees. Para cessão de duplicatas e CT-e o formato é o CNAB 444 — o mesmo layout de remessa de cobrança usado no mercado, descrito em Layout CNAB 444 — Cessão.
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
Cedente, configuração de cessão, substituição e meio de pagamento ao cedente.
Arraste o arquivo .rem, .txt ou .csv para a área de upload e confirme o envio.
Estrutura, posições, domínios e documentos são conferidos linha a linha.
Uma única linha inválida recusa o arquivo inteiro. O portal exibe as linhas e os motivos.
Cada linha vira um ativo e o lote entra no fluxo padrão de cessão.
Ver documentação →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:
- Acesse Ativos › Cessões e clique em Nova cessão.
- 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.
- 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.
- Marque Substituição se o lote tiver ativos de recompra.
- Escolha o meio de pagamento ao cedente (Pix ou TED), quando aplicável.
- Arraste o arquivo (
.rem,.txtou.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.
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.
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, 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.
Para operações de alto volume, a QI CTVM 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.