Asset Repurchase and Sale
This section documents the APIs that enable the sale and repurchase of credit rights already held in the portfolios of funds administered by QI DTVM. The flow covers everything from batch creation to writing the assets off the fund's portfolio.
This service only writes the assets off the fund's portfolio. It does not send data to other administrators.
There are two fundamental concepts: the batch (assignment) and the asset (asset). A batch is made up of one or more assets, and every asset inserted must already be in the fund's portfolio.
- To gain access to these services, contact integracao.dtvm@qitech.com.br to enable the Sandbox and Production environments.
- You will need the
fund_class_key(the fund's key), which makes up the base URL of every endpoint in this API, and theassignment_configuration_key(the configuration key), provided when the batch is created:
/trade_resolve/fund_class/{fund_class_key}
Sale/repurchase flow
The diagram below shows the main path, its branches and the resulting status of each step. Hover over a node to see the endpoint, and click to open the documentation.
Provide a unique external_id, the fund's accounting date and the document of whoever will make the payment to the fund.
/trade_resolve/fund_class/{fund_class_key}/assignmentOne request per asset, identified by the same external_id under which it was added to the portfolio. The asset must be active in the portfolio.
.../assignment/{external_id}/assetWhen the sale price diverges by more than 5% from the fair book value, the asset is held. The confirmation is not available in the API: align with integracao.dtvm@qitech.com.br.
At least one non-discarded asset is required. You may send number_of_assets and total_value so the API can check the totals.
.../assignment/{external_id}The batch can be discarded until it is closed. Discarding is not available in the API: request it from integracao.dtvm@qitech.com.br.
Internal term: QI Tech generates the document and collects the signatures. External term: the batch stays in pending_signed_term_submission.
With the term signed, QI Tech records the payment expectation in the fund account.
Once the credit is confirmed, the batch moves to pending_wallet_sale and the assets are written off one by one. When all of them finish, the batch is closed.
Step by step
1. Batch Creation
Create the batch by providing a unique identifier (external_id), the operation date (the fund's current accounting date) and the document of whoever will make the payment to the fund. The batch starts in pending_assets_insertion and is the container for all the assets that will be written off.
Go to the batch creation documentation
2. Asset Insertion
Insert one asset per request, identifying it by the same external_id under which it was added to the portfolio (or by the contract number). The asset must be active in the fund's portfolio at the time of insertion.
Go to the asset insertion documentation
If the sale price provided diverges by more than 5% from the asset's fair book value, the asset does not proceed automatically: it stays in pending_validation and requires a confirmation before entering the write-off. Divergences of up to 5% go straight to pending_wallet_sale.
The confirmation is not available in the API. While there is an asset in pending_validation, the batch does not move forward after closing. If your flow can produce divergences above 5%, align the procedure with integracao.dtvm@qitech.com.br.
3. Batch Closing
After inserting all the assets, close the batch. At least one non-discarded asset is required. Optionally, you may send number_of_assets and total_value so that the API checks the consolidated quantity and total amount before accepting the closing.
The batch can only be discarded up to this step, and discarding the batch is not available in the API: request it from integracao.dtvm@qitech.com.br.
Go to the closing documentation
4. Repurchase Term
Who is responsible for issuing the Repurchase Term depends on the batch configuration:
- Internal term — when all assets are ready for the write-off, QI Tech generates the term (
pending_documents_generation) and collects the parties' signatures (pending_documents_signature). No action is required from the integrator. - External term — the batch moves to
pending_signed_term_submissionand must receive the already signed term. Submitting this term is not available onmanager-api,consultant-apiorassignor-api: before operating with an external term, arrange the submission with integracao.dtvm@qitech.com.br.
In both cases, once the term is signed the batch moves to pending_payment, awaiting the credit in the fund account.
5. Payment and Asset Write-off
The final steps are automated: QI Tech confirms the credit in the fund account, the batch moves to pending_wallet_sale, the assets are written off the portfolio and, when all assets are completed, the batch is closed in completed.
Webhook
When the internal term is signed and the batch moves to pending_payment, QI Tech sends the trade_resolve.assignment_status_change webhook to the agents registered in the batch configuration. It is the only status that emits a webhook: batches with an external term do not receive this event. Registration is done by QI Tech: request it at integracao.dtvm@qitech.com.br. To validate the signature, see Receiving Webhooks.
{
"webhook_type": "trade_resolve.assignment_status_change",
"webhook_datetime": "2024-04-02T10:15:00Z",
"data": {
"assignment_external_id": "931e9437-d025-41ab-bb53-6b94e10fd361",
"assignment_new_status": "pending_payment",
"signed_term_url": "https://URL_TEMPORARIA_DO_TERMO"
}
}
| Field | Description |
|---|---|
assignment_external_id | external_id of the batch |
assignment_new_status | New status of the batch: pending_payment |
signed_term_url | Link to download the signed term. Expires in 24 hours. |