Testing the Collateral Capture
This page is a walkthrough for anyone building the automated reading of the Assignment Collateral and who needs a document_url that really works in order to test before going to production.
The idea is simple: in sandbox, you run an assignment end to end using the example PDFs made available below. The assignment_documents is generated by the same code that generates the report in production, with legitimate pre-signed links — nothing is assembled by hand.
document_url is a pre-signed S3 URL, generated at the moment the report is produced and valid for 5 days. A static file with real links would expire before reaching you. By running the walkthrough, you generate new links whenever you need them.
What you need to have in sandbox
This test uses the normal assignment flow, so it assumes the same setup as any integration:
| Item | How to obtain it |
|---|---|
Fund class (fund_class_key) | Provided by the integration team. |
Assignment configuration (assignment_configuration_key) | Provided by the integration team. It defines the asset type of the assignment and which documents are required. |
assignment_documents in the report routine of the configuration | Ask the integration team to include the report in the assignment configuration. Without it the file is not generated. |
| Delivery destination (SFTP) | Configured together with the report routine. See the SFTP integration. |
There is no path that produces a real document_url without a real assignment in sandbox — the report is a query over the documents actually attached to the assets of that assignment. If your goal is only to check the structure of the columns, use the examples package from the introduction, which carries the CSV with an example URL in the correct format.
Example files
One document per document_type, with fictitious data, extractable text (they are not images) and the typical structure of each type:
📦 Download all (lastros_exemplo.zip)
| File | document_type | What it is |
|---|---|---|
| ccb_exemplo_01.pdf | ccb | CCB issued by QI SCD, 3 installments, 22 pages with the chain of endorsements |
| ccb_exemplo_02.pdf | ccb | CCB issued by QI SCD, 2 installments, 22 pages with the chain of endorsements |
| duplicata_mercantil_exemplo.pdf | duplicata_mercantil | Commercial duplicata with the access key of the NF-e |
| invoice_exemplo.pdf | invoice | DANFE of the NF-e referenced by the duplicata |
| duplicata_servicos_exemplo.pdf | duplicata_servicos | Service duplicata, referencing an NFS-e |
| cte_exemplo.pdf | cte | DACTE |
| discounted_contract_exemplo.pdf | discounted_contract | Service provision contract with an assignment clause |
None of them has legal or tax validity, none was transmitted to SEFAZ and none contains data of real people or companies. They serve exclusively for reading tests.
The two ccb PDFs are consistent with the example_reports.zip published in the reports introduction: the same contract numbers (0900112233/EXA and 0900112247/EXB), the same installment values, the same maturities and the same monthly rate that appear in the example assignment_assets_wallet_composition.
The two ccb PDFs are the real structure of a CCB issued by QI Sociedade de Crédito Direto S.A. — Quadros I to XI in the order they appear in the real document, with the full text of the general and special conditions, the electronic signature page of the issuer and the chain of endorsements up to the fund. It is the document your reader will find in production when the originator issues through QI Tech, with the data replaced by fictitious data.
Three parts that tend to be the most useful for collateral validation:
- Quadro V, item 5 — the table with the possible disbursement dates. Each line has its own Total Value, IOF, Net Value and CET; the line that counts is the one for the date the funds were actually disbursed. A reader that assumes a single line extracts the wrong value.
- Quadro V, item 13 — the CET statement, which reconciles with the first line of the table in item 5.
- Endorsements (last pages) — the
QI SCD → assignor → fundchain, each link with its own digital signature page (hash, date, signatories). That is how the fund's ownership of the instrument is evidenced.
The document_type of the report remains the source of truth about the type — do not try to infer it from the internal structure.
The production template repeats words in two places, and the examples reproduce that:
- item 1.1 of Quadro V —
2,3100% % a.m. (dois inteiros e três mil e cem décimos de milésimo por cento por cento), with%andpor centoduplicated; - item 2 of Quadro V —
2. Prazo: 91 dias dias corridos.
It is not a mistake of these files. We kept them as they are so your reader finds in sandbox exactly the text it will find in production — if you normalize the text before matching the pattern, those two fields are the ones most likely to break. When the template is fixed, the examples are regenerated.
The example documents in the rest of the documentation use placeholder CPF and CNPJ, with an invalid check digit — 123.456.789-00, 12.345.678/0001-99 and the like. That does not bother anyone who only reads an example payload, but it would fail any collateral validation that checks the check digit.
In these PDFs the check digits were corrected, preserving the first 12 digits: 123.456.789-09, 12.345.678/0001-95, 22.333.444/0001-81. The access keys of the NF-e and CT-e also have a correct check digit and embed the already corrected CNPJ of the issuer.
Consequence: the borrower_document of the example assignment_assets_wallet_composition differs from the CPF printed in the PDF in the last two digits. If you are testing the cross-reference between the two files, use asset_external_id, asset_key, contract number, values and maturities — not the drawee's document.
Walkthrough
1. Create the assignment
The external_id you provide here is the same one that will appear in the assignment_external_id column of the report and in the file name. Details in Assignment Creation.
2. Insert the asset
The payload depends on the asset type of your assignment configuration — see Asset Creation for a credit operation, or the duplicata, CT-e and discounted contract pages.
Store the external_id of the asset: it is the join key with the other reports.
3. Attach the example document
Convert the chosen PDF to Base64:
base64 -w 0 ccb_exemplo_01.pdf > ccb_exemplo_01.b64
{
"document_type": "ccb",
"document_b64": "JVBERi0xLjcKJfCflqQKMSAwIG9iago8PAovVHlwZSAvQ2F0YWxvZwo..."
}
The types accepted in document_type are the ones your assignment configuration requires, not the complete list of existing types. Details and possible errors in Inserting Asset Documents.
For assets of the duplicata_mercantil type, the platform can generate the documentation automatically from the invoice data — in that case there is no upload to do, and the collateral appears in the report without you attaching anything.
This depends on the assignment configuration: in some configurations the automatic generation does not happen and the document is expected by upload. Confirm with the integration team which of the two cases applies to yours before setting up the test. Regardless of that, the duplicata_mercantil and invoice PDFs of this package serve as a structure reference for your reader.
4. Close the insertion
{
"assignment_status": "completed_assets_insertion"
}
From here on the assignment moves to eligibility and to approval — see Closing the insertion and Assignment approval.
5. Receive the file
The assignment_documents is generated when the assignment goes through the approval stage and written to the SFTP folder configured for the fund, with the name:
{short_fund_name}_assignment_documents_{external_id}_{YYYY-MM-DD}.csv
It is the CSV with the links — the PDFs themselves are not transferred to the SFTP. Connection instructions and download examples in SFTP Integration.
This is the most important point of attention in the SFTP delivery. The 5-day validity of the links starts counting at the generation of the report, not at the moment you fetch the file. The CSV stays in the folder indefinitely, but a file collected on the sixth day carries links that no longer work.
Collect the file as soon as it arrives, or treat the expired link error as a sign that the report needs to be generated again — and not as a failure of your reader.
The Delivery Webhook covers the fund's report routines, not the deliveries generated by an assignment. For assignment_documents there is no notice that the file is available.
The closest signal is the assignment batch status webhook. In flows with manual approval, the transition to pending_consultant_approval or pending_manager_approval marks the entry into the approval stage, which is when the report is generated — use that event to schedule the collection. In flows with automatic approval those two statuses do not occur, and the usable signal is the next batch status in your flow. In both cases the file appears in the folder afterwards, not at the same instant as the webhook.
What to validate in your reader
Three behaviors of document_url that tend to break implementations and that you can exercise with the file you have just received:
The links expire in 5 days. They are pre-signed URLs with X-Amz-Expires=432000, counted from the moment the report is generated. After that period the link returns an error and the report has to be generated again. The stable identifier of the document is the document_key — never the URL. If you need to archive the collateral, download the files within the window.
The file arrives without a useful name and without an extension. The download comes with the headers:
Content-Disposition: attachment; filename="file"
Content-Type: binary/octet-stream
That is: the file is called file, without an extension, and the content-type does not identify the format. Do not infer the type from the name nor from the content-type — use the document_type column of the CSV. The content is always PDF.
An asset can occupy more than one line. When the asset has more than one document, it appears repeated, with the same asset_key and a different document_type. Assets without an attached document do not appear, and discarded (discarded) or denied (denied) assets are excluded from the file.
document_url is not always a URLIf the signing of the link fails at the moment the report is generated, the column comes filled with an error message in text, not with a URL — and the CSV is delivered normally, with the other columns intact.
Treat document_url as an untrusted field: validate that the value starts with https:// before trying to download. A line in that condition means that document has to be obtained in a new generation of the report, not that the file does not exist. A reader that assumes "every line has a valid URL" breaks on the first such case.
Cross-referencing with the assignment composition
For collateral validation, the most useful cross-reference is between this report and the Assignment Assets Composition, through the asset_external_id and asset_key columns. An asset that appears in the composition and does not appear in the collateral is an asset without an attached document.
A limit of this test
There is no QI Tech DTVM layout per document type. The collateral files are the original documents of the assignor or of the originator — the CCB issued by the originator, the DANFE generated by their ERP, the DACTE of the carrier. The DTVM stores and validates those files, it does not generate them, and that is why the validation of each type is configured by template on our side.
The distinction matters here. QI Tech issues credit through other fronts — BaaS and LaaS — and those issuances do have their own CCB layout, which is the one of the example CCBs on this page. What does not exist is a layout defined by the DTVM for the collateral it receives: when the originator is QI Tech itself, the document follows the standard of that issuance; when it is another originator, it follows theirs.
That is: the example CCB is one possible collateral layout — the most likely one, if your originator issues through QI Tech — and not the layout the DTVM requires.
Practical consequence: what you can treat as a stable contract is the CSV — columns, types and semantics. The interior of the PDF varies by originator. If your fund buys from more than one originator, or if the originator does not issue through QI Tech, also test against a real file of theirs before finalizing the implementation. The other five examples (duplicata, invoice, CT-e, contract) reproduce the typical structure of each type, but they do not come from a specific issuer — they are a reference for fields, not for layout.