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.

Por que não entregamos um arquivo pronto com links

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 há atalho para o setup

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

Estes arquivos são fictícios

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.

As CCBs de exemplo seguem o layout real de emissão da QI Tech

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.

Duas duplicações do template foram preservadas de propósito

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 % e por cento duplicados;
• 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.

CPF e CNPJ destes PDFs têm dígito verificador válido

Para não reprovar em validações de lastro que conferem dígito verificador, os CPFs e CNPJs impressos nestes PDFs têm DV válido, e as chaves de acesso de NF-e e CT-e também. Todos são fictícios.

Consequência: o borrower_document do assignment_assets_wallet_composition do pacote de exemplos 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

Chame POST /trade_receivables/fund_class/{fund_class_key}/assignment_configuration/{assignment_configuration_key}/assignment. 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

Chame POST .../assignment/{assignment_external_id}/asset, uma vez por 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

Envie o arquivo com POST .../assignment/{assignment_external_id}/asset/{asset_external_id}/document:

Request Body

{
    "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 Envio do Lastro do Ativo.

Duplicatas mercantis podem não passar por aqui

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

Chame PUT .../assignment/{assignment_external_id} com o status de encerramento:

Request Body

{
    "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 entregue no destino definido na configuração de cessão, 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.

O arquivo espera na pasta, os links não

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.

Este relatório não emite o Webhook de Entrega

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. O prazo conta a partir 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 nome do arquivo baixado não identifica o formato com segurança. O download vem com Content-Disposition: attachment; filename="{document_type}-{asset_external_id}.pdf" (acentos são removidos e os demais caracteres fora de A-Z a-z 0-9 . _ - viram _). Não infira o tipo pelo nome nem pelo Content-Type — use a coluna document_type do CSV.

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 URL

Se a assinatura do link falhar no momento em que o relatório é gerado, a coluna vem preenchida com uma mensagem de erro em texto — Erro: Credenciais não configuradas corretamente. —, 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.

"QI Tech" não é o mesmo que "QI Tech DTVM"

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.