Assignment contract
This process generates an assignment contract between the Investment Fund and the Assignor and sends it for signature. To generate a contract, you need the fund's fund_class_key, provided by the QI DTVM team, as well as an assignment_contract_template_key, also provided by the team, which defines the contract parameters, such as co-obligation, mandatory assignment documents, clauses and the contract's products.
Products identify, for example, an assignment configuration for a given asset type, for repurchase, and so forth. They come from the template: there is no need to send them in the request. Two documents are sent for signature: the contract itself, with all the related parties involved, such as assignor, manager, guarantors, etc.; and the manager's declaration, which must be signed by the manager alone, attesting that all rules and requirements set out by CVM, Anbima and the Central Bank regarding the assignor's operation have been met, covering everything from risk analysis to AML, among others that can be consulted on the respective portals.
The contract flow is configurable: you can have the documents sent for signature as soon as they are generated, or have them wait for a manual submission. In addition, if the contract is proposed by a consultant, the manager's approval is required before it is sent for signature. Finally, if the assignor's registration has not yet been released, or is being updated, you must wait for the latest analysis to be concluded before sending it for signature. If the analysis is rejected, the contract is canceled as well.
Optionally, you may define guarantors for the operation between the assignor and the fund, provided the contract template allows it. Guarantors must be registered beforehand together with the assignor, and are only referenced in the contract by their document number. Disbursement accounts are defined in the assignor's registration; when the template requires a specific account for the contract, it is indicated in disbursement_account_key.
The entire contract signature flow is handled by our certification authority, CertifiQI. Tracking the signatures and activating the products happen automatically — see Product activation.
| Profile | Host | Required permission |
|---|---|---|
| Manager | manager-api | Write |
| Consultant | consultant-api | Create assignment contracts |
Base URL for each host: Environments (Hosts).
Request
{
"fund_class_key": "813ce253-bae5-4448-8d15-04c48d9991b7",
"assignor_document_number": "55.666.777/0001-81",
"assignment_contract_template_key": "2555f90a-4c6a-4d65-8bda-5d16f827840c",
"credit_limit": 1000000,
"external_id": "Contract 550",
"observation": "Contract regarding the link with the assignor's co-obligation",
"guarantors": [
{
"name": "Operation guarantor",
"document_number": "969.698.790-03"
}
]
}
Body Params
| Field | Type | Description | Characters |
|---|---|---|---|
fund_class_key * | string | Unique key identifying the Fund. Generated when the Fund is created and provided by the QI DTVM team. | uuid key |
assignment_contract_template_key * | string | Unique key identifying the Contract Template. Also provided by the QI DTVM team. | uuid key |
assignor_document_number ** | string | Assignor's document number. | CPF or CNPJ, up to 18 |
assignor_registry_key ** | string | Assignor registration key, an alternative to assignor_document_number. | uuid key |
credit_limit | number | Credit limit amount for the contract. | 1 to 1,000,000,000 |
disbursement_account_key | string | Contract disbursement account. Required when the template's disbursement account policy is locked_on_assignment_contract, and rejected otherwise. Must be an active account of the assignor. | uuid key |
external_id | string | External identifier of the contract. Usually the contract number. | Up to 50 |
case_number | string | Case number. Unique per fund; if omitted, it is generated automatically. | Up to 17 |
observation | string | Observation. Free-form field for any notes. | Up to 1000 |
delay | object | Late-payment fine (fine) and interest (interest). Only accepted when the template allows these values to be customized. | -- |
guarantors | array | Guarantors of the operation. | See Guarantor Definition. |
*Required fields
**Send exactly one of the two: assignor_document_number or assignor_registry_key.
It is very important that guarantors are referenced both in the assignor's registration and at this stage. If a guarantor is referenced only in the registration and not in the contract, they will not sign the document. If referenced only in the contract and not in the registration, an error is returned.
Response
The response body is the full contract, in the same format as the Contract Query. Excerpt:
{
"assignment_contract_key": "41d6ff41-1dac-4df7-9e50-d15210ec57f3",
"status": "pending_document",
"external_id": "Contract 550",
"case_number": "17375775230001234",
"disbursement_account_key": null,
"products": [
{
"product_key": "57efbd9f-0917-4c79-9a43-bc8f1039fc78",
"assignment_configuration_key": null,
"fund_class_configuration_key": "0b6f3a8e-2f7d-4c11-9a52-6a1d1c0e9f10",
"product_type": "assignment_term",
"asset_type": "ccb",
"has_coobligation": true,
"status": "pending_contract_signature"
}
]
}
It is extremely important to save the assignment_contract_key: it identifies the contract in queries and webhooks, and the assignment configurations generated by the contract (including those originated by the Branches flow) are linked to it. To retrieve the products and the generated configurations, use the Contract Query.
Product activation
There is no activation call: products are activated automatically when the contract is signed.
- All documents signed → the contract moves to
signedand theassignment_contract.assignment_contract_status_changewebhook is sent withassignment_contract_new_status: contract_signed. - Each product moves from
pending_contract_signaturetopending_create_assignment_configurationwhile the assignment pipeline is configured. This may take a few minutes. - Once the pipeline is configured, the product moves to
activeand theassignment_contract.product_status_changewebhook is sent, carrying theassignment_configuration_key— the key used to assign assets between the fund and the assignor.
The payloads are in Contract Webhooks. If you prefer not to rely on the webhook, query the contract and read products[].status and products[].assignment_configuration_key.
Guarantor Definition
| Field | Type | Description | Characters |
|---|---|---|---|
name | string | Guarantor's name. | Up to 255 |
document_number | string | CPF or CNPJ, formatted. | 14 to 18 |
As already noted, the guarantor must be registered beforehand, together with the specific assignor.
Enumerators
Assignment Contract Status
| Enumerator | Description |
|---|---|
| created | Contract created (initial, transitory state) |
| pending_document | Pending document generation |
| pending_manager_approval | Pending manager approval |
| pending_assignor_registry_release | Pending release of the linked assignor registration (under registration or update) |
| pending_signature_submission | Pending manual submission for signature |
| sending_to_signature | Being sent for signature |
| pending_signature | Available for the parties to sign |
| waiting_escrow_data | Awaiting escrow account data (only in templates with an escrow account) |
| pending_escrow_activation | Awaiting escrow account activation (only in templates with an escrow account) |
| signed | Signed |
| suspended | Suspended; products stay inactive until reactivation |
| denied | Rejected in the manager's review |
| canceled | Canceled |
Product Status
| Enumerator | Description |
|---|---|
| pending_contract_signature | Awaiting contract signature |
| pending_create_assignment_configuration | Contract signed; assignment pipeline being configured |
| active | Active; assignment_configuration_key available |
| inactive | Inactive (contract canceled or suspended) |
Attached Document Status
| Enumerator | Description |
|---|---|
| pending_generate | Pending document generation |
| approved | Document generated |
| pending_upload | Awaiting document upload |
| uploaded | Document uploaded |
| pending_validation | Document uploaded, under validation |
| pending_signed_upload | Awaiting upload of the signed document |
| signed | Document signed |
| reproved | Document invalidated (contract canceled or rejected) |
Errors
| Status | Code | When it happens |
|---|---|---|
| 404 | ACT000001 | fund_class_key not found or does not belong to the authenticated manager. |
| 404 | ACT000016 | assignment_contract_template_key not found for the fund. |
| 400 | ACT000126 | The template is inactive. Use an active template. |
| 404 | ACT000065 | The assignor for the assignor_document_number is not registered for the proposing agent. |
| 404 | ACT000134 | assignor_registry_key not found, or the agent does not own the registration. |
| 400 | ACT000142 | The assignor only has a basic analysis registration and cannot receive a contract. |
| 400 | ACT000096 | The assignor has no registered account. Register one in Account Maintenance. |
| 400 | ACT000155 | The template requires disbursement_account_key and it was not sent. |
| 400 | ACT000156 | disbursement_account_key sent, but the template does not accept a per-contract account. |
| 400 | ACT000154 | disbursement_account_key is not an active account of the assignor. |
| 400 | ACT000081 | An item in guarantors is not registered as a guarantor of the assignor. |
| 400 | ACT000102 | delay sent, but the template does not allow customizing the fine and interest. |
| 409 | ACT000095 | case_number already used in this fund. Use another one or omit the field. |
Authentication, permission and host errors: see API errors.