Testando a Captura de Lastro
Esta página é um roteiro para quem está construindo a leitura automatizada dos Lastros da Cessão e precisa de um document_url que funcione de verdade para testar antes de ir a produção.
A ideia é simples: em sandbox, você roda uma cessão de ponta a ponta usando os PDFs de exemplo que disponibilizamos abaixo. O assignment_documents é gerado pelo mesmo código que gera o relatório em produção, com links pré-assinados legítimos — nada é montado à mão.
document_url é uma URL pré-assinada de S3, gerada no momento em que o relatório é produzido e válida por 5 dias. Um arquivo estático com links reais expiraria antes de chegar até você. Rodando o roteiro, você gera links novos sempre que precisar.
O que você precisa ter em sandbox
Este teste usa o fluxo normal de cessão, então ele pressupõe o mesmo setup de qualquer integração:
| Item | Como obter |
|---|---|
Classe de fundo (fund_class_key) | Fornecida pelo time de integração. |
Configuração de cessão (assignment_configuration_key) | Fornecida pelo time de integração. Ela define o tipo de ativo da cessão e quais documentos são exigidos. |
assignment_documents na rotina de relatórios da configuração | Peça ao time de integração para incluir o relatório na configuração de cessão. Sem isso o arquivo não é gerado. |
| Destino de entrega (SFTP) | Configurado junto com a rotina de relatórios. Veja a integração SFTP. |
Não existe caminho que produza um document_url real sem uma cessão real em sandbox — o relatório é uma consulta aos documentos efetivamente anexados aos ativos daquela cessão. Se o seu objetivo é apenas conferir a estrutura das colunas, use o pacote de exemplos da introdução, que traz o CSV com URL de exemplo no formato correto.
Arquivos de exemplo
Um documento por document_type, com dados fictícios, texto extraível (não são imagem) e a estrutura típica de cada tipo:
📦 Baixar todos (lastros_exemplo.zip)
| Arquivo | document_type | O que é |
|---|---|---|
| ccb_exemplo_01.pdf | ccb | CCB emitida pela QI SCD, 3 parcelas, 22 páginas com cadeia de endossos |
| ccb_exemplo_02.pdf | ccb | CCB emitida pela QI SCD, 2 parcelas, 22 páginas com cadeia de endossos |
| duplicata_mercantil_exemplo.pdf | duplicata_mercantil | Duplicata mercantil com chave de acesso da NF-e |
| invoice_exemplo.pdf | invoice | DANFE da NF-e referenciada pela duplicata |
| duplicata_servicos_exemplo.pdf | duplicata_servicos | Duplicata de prestação de serviços, referenciando NFS-e |
| cte_exemplo.pdf | cte | DACTE |
| discounted_contract_exemplo.pdf | discounted_contract | Contrato de prestação de serviços com cláusula de cessão |
Nenhum deles tem validade jurídica ou fiscal, nenhum foi transmitido à SEFAZ e nenhum contém dados de pessoas ou empresas reais. Servem exclusivamente para teste de leitura.
Os dois PDFs de ccb são consistentes com o example_reports.zip publicado na introdução aos relatórios: mesmos números de contrato (0900112233/EXA e 0900112247/EXB), mesmos valores de parcela, mesmos vencimentos e mesma taxa mensal que aparecem no assignment_assets_wallet_composition de exemplo.
Os dois PDFs de ccb são a estrutura de verdade de uma CCB emitida pela QI Sociedade de Crédito Direto S.A. — os Quadros I a XI na ordem em que aparecem no documento real, com o texto integral das condições gerais e especiais, a página de assinatura eletrônica do emitente e a cadeia de endossos até o fundo. É o documento que o seu leitor vai encontrar em produção quando o originador emite pela QI Tech, com os dados trocados por fictícios.
Três partes que costumam ser as mais úteis para validação de lastro:
- Quadro V, item 5 — a tabela com as datas possíveis de liberação. Cada linha tem seu próprio Valor Total, IOF, Valor Líquido e CET; a linha que vale é a da data em que os recursos foram efetivamente liberados. Um leitor que assuma uma linha só extrai o valor errado.
- Quadro V, item 13 — o demonstrativo do CET, que reconcilia com a primeira linha da tabela do item 5.
- Endossos (últimas páginas) — a cadeia
QI SCD → cedente → fundo, cada elo com sua própria página de assinatura digital (hash, data, signatários). É por aí que se comprova a titularidade do título pelo fundo.
O document_type do relatório continua sendo a fonte de verdade sobre o tipo — não tente inferir da estrutura interna.
O template de produção repete palavras em dois pontos, e os exemplos reproduzem isso:
- item 1.1 do Quadro V —
2,3100% % a.m. (dois inteiros e três mil e cem décimos de milésimo por cento por cento), com%epor centoduplicados; - item 2 do Quadro V —
2. Prazo: 91 dias dias corridos.
Não é erro destes arquivos. Mantivemos como está para o seu leitor encontrar em sandbox exatamente o texto que vai encontrar em produção — se você normalizar o texto antes de casar o padrão, esses dois campos são os que mais provavelmente quebram. Quando o template for corrigido, os exemplos são regerados.
Os documentos de exemplo do restante da documentação usam CPF e CNPJ de fachada, com dígito verificador inválido — 123.456.789-00, 12.345.678/0001-99 e afins. Isso não incomoda quem só lê um payload de exemplo, mas reprovaria em qualquer validação de lastro que confira DV.
Nestes PDFs os dígitos verificadores foram corrigidos, preservando os 12 primeiros dígitos: 123.456.789-09, 12.345.678/0001-95, 22.333.444/0001-81. As chaves de acesso de NF-e e CT-e também têm DV correto e embutem o CNPJ do emitente já corrigido.
Consequência: o borrower_document do assignment_assets_wallet_composition de exemplo difere do CPF impresso no PDF nos dois últimos dígitos. Se você está testando o cruzamento entre os dois arquivos, use asset_external_id, asset_key, número de contrato, valores e vencimentos — não o documento do sacado.
Roteiro
1. Crie a cessão
O external_id que você informar aqui é o mesmo que vai aparecer na coluna assignment_external_id do relatório e no nome do arquivo. Detalhes em Criação da Cessão.
2. Insira o ativo
O payload depende do tipo de ativo da sua configuração de cessão — veja Criação de Ativos para operação de crédito, ou as páginas de duplicata, CT-e e contrato descontado.
Guarde o external_id do ativo: ele é a chave de junção com os outros relatórios.
3. Anexe o documento de exemplo
Converta o PDF escolhido para Base64:
base64 -w 0 ccb_exemplo_01.pdf > ccb_exemplo_01.b64
{
"document_type": "ccb",
"document_b64": "JVBERi0xLjcKJfCflqQKMSAwIG9iago8PAovVHlwZSAvQ2F0YWxvZwo..."
}
Os tipos aceitos em document_type são os que a sua configuração de cessão exige, não a lista completa de tipos existentes. Detalhes e erros possíveis em Inserção de Documentos do Ativo.
Para ativos do tipo duplicata_mercantil, a plataforma pode gerar a documentação automaticamente a partir dos dados da nota fiscal — nesse caso não há upload a fazer, e o lastro aparece no relatório sem você anexar nada.
Isso depende da configuração de cessão: em algumas configurações a geração automática não acontece e o documento é esperado por upload. Confirme com o time de integração qual dos dois casos se aplica à sua antes de montar o teste. Independente disso, os PDFs de duplicata_mercantil e invoice deste pacote servem como referência de estrutura para o seu leitor.
4. Encerre a inserção
{
"assignment_status": "completed_assets_insertion"
}
A partir daqui a cessão segue para a elegibilidade e para a aprovação — veja Encerramento da inserção e Aprovação da cessão.
5. Receba o arquivo
O assignment_documents é gerado quando a cessão passa pela etapa de aprovação e gravado na pasta de SFTP configurada para o fundo, com o nome:
{nome_resumido_fundo}_assignment_documents_{external_id}_{AAAA-MM-DD}.csv
É o CSV com os links — os PDFs em si não são transferidos para o SFTP. Instruções de conexão e exemplos de download em Integração SFTP.
Este é o ponto de atenção mais importante da entrega por SFTP. A validade de 5 dias dos links começa a contar na geração do relatório, não na hora em que você busca o arquivo. O CSV continua na pasta indefinidamente, mas um arquivo coletado no sexto dia traz links que já não funcionam.
Colete o arquivo assim que ele chegar, ou trate o erro de link expirado como sinal de que o relatório precisa ser gerado novamente — e não como falha do seu leitor.
O Webhook de Entrega cobre as rotinas de relatório do fundo, e não as entregas geradas por cessão. Para o assignment_documents não há aviso de arquivo disponível.
O sinal mais próximo é o webhook de status do lote de cessão. Em fluxos com aprovação manual, a passagem para pending_consultant_approval ou pending_manager_approval marca a entrada na etapa de aprovação, que é quando o relatório é gerado — use esse evento para agendar a coleta. Em fluxos com aprovação automática esses dois status não ocorrem, e o sinal utilizável é o status seguinte do lote no seu fluxo. Em ambos os casos o arquivo aparece na pasta em seguida, não no mesmo instante do webhook.
O que validar no seu leitor
Três comportamentos do document_url que costumam quebrar implementações e que você consegue exercitar com o arquivo que acabou de receber:
Os links expiram em 5 dias. São URLs pré-assinadas com X-Amz-Expires=432000, contados do momento da geração do relatório. Passado o prazo o link retorna erro e é preciso gerar o relatório novamente. O identificador estável do documento é o document_key — nunca a URL. Se você precisa arquivar o lastro, baixe os arquivos dentro da janela.
O arquivo chega sem nome útil e sem extensão. O download vem com os headers:
Content-Disposition: attachment; filename="file"
Content-Type: binary/octet-stream
Ou seja: o arquivo se chama file, sem extensão, e o content-type não identifica o formato. Não infira o tipo pelo nome nem pelo content-type — use a coluna document_type do CSV. O conteúdo é sempre PDF.
Um ativo pode ocupar mais de uma linha. Quando o ativo tem mais de um documento, ele aparece repetido, com o mesmo asset_key e document_type diferente. Ativos sem documento anexado não aparecem, e ativos descartados (discarded) ou reprovados (denied) são excluídos do arquivo.
document_url não é sempre uma URLSe a assinatura do link falhar no momento em que o relatório é gerado, a coluna vem preenchida com uma mensagem de erro em texto, não com uma URL — e o CSV é entregue normalmente, com as outras colunas íntegras.
Trate document_url como campo não confiável: valide que o valor começa com https:// antes de tentar baixar. Uma linha nessa condição significa que aquele documento precisa ser obtido em uma nova geração do relatório, não que o arquivo não exista. Um leitor que assuma "toda linha tem URL válida" quebra no primeiro caso desses.
Cruzando com a composição da cessão
Para validação de lastro, o cruzamento mais útil é entre este relatório e a Composição de Ativos da Cessão, pelas colunas asset_external_id e asset_key. Ativo que aparece na composição e não aparece no lastro é ativo sem documento anexado.
Um limite deste teste
Não existe um layout QI Tech DTVM por tipo de documento. Os arquivos de lastro são os documentos originais do cedente ou do originador — a CCB emitida pelo originador, o DANFE gerado pelo ERP dele, o DACTE da transportadora. A DTVM armazena e valida esses arquivos, não os gera, e é por isso que a validação de cada tipo é configurada por template do nosso lado.
A distinção importa aqui. A QI Tech emite crédito por outras frentes — BaaS e LaaS — e essas emissões têm, sim, um layout próprio de CCB, que é o das CCBs de exemplo desta página. O que não existe é um layout definido pela DTVM para o lastro que ela recebe: quando o originador é a própria QI Tech, o documento segue o padrão daquela emissão; quando é outro originador, segue o padrão dele.
Ou seja: a CCB de exemplo é um layout de lastro possível — o mais provável, se o seu originador emite pela QI Tech — e não o layout que a DTVM exige.
Consequência prática: o que você pode tratar como contrato estável é o CSV — colunas, tipos e semântica. O interior do PDF varia por originador. Se o seu fundo compra de mais de um originador, ou se o originador não emite pela QI Tech, teste também contra um arquivo real dele antes de fechar a implementação. Os outros cinco exemplos (duplicata, invoice, CT-e, contrato) reproduzem a estrutura típica de cada tipo, mas não vêm de um emissor específico — são referência de campos, não de layout.