Amendment Request Creation
To make an amendment request, you need to send a request using the unique key that represents the fund (fund_class_key, provided by QI Tech) and the unique key that represents the amendment pipeline configuration (amendment_configuration_key, provided by QI Tech).
In amendments made through this system, it is allowed to change the payment flow, the nominal rate of the contract, or both. It is also possible to define that the amendment will be made together with a down payment paid by the debtor.
| Profile | Host | Required permission |
|---|---|---|
| Manager | manager-api | Write |
| Consultant | consultant-api | Batches |
| Assignor | assignor-api | Write |
Base URL for each host: Environments (Hosts).
Request
{
"asset_external_id": "931e9437-d025-41ab-bb53-6b94e10fd361",
"asset_type": "ccb",
"amendment_date": "2024-04-01",
"amendment_type": "all_contract",
"down_payment_value": 400.23,
"installments": [
{
"maturity_date": "2025-01-31",
"face_value": 1000.31,
"installment_number": 1
},
{
"maturity_date": "2025-02-28",
"face_value": 1000.31,
"installment_number": 2
}
],
"pre_fixed": {
"monthly_rate": 0.02,
"calendar_base": "workdays"
}
}
Body Params
| Field | Type | Description | Required |
|---|---|---|---|
asset_external_id | string | Identifier of the contract being amended, the same one it was added to the portfolio with. Up to 50 characters. | One of the two: asset_external_id or contract_number |
contract_number | string | Number of the contract to be amended, an alternative to asset_external_id. Up to 50 characters. | One of the two: asset_external_id or contract_number |
asset_type | string | Type of the amended asset: ccb or structured_cci | Yes |
amendment_date | string | Date when the amendment is being made (format: YYYY-MM-DD) | Yes |
amendment_type | string | Type of amendment to be made. See Amendment Type Enumerator | Yes |
down_payment_value | number | Down payment amount to be paid by the debtor at the time of the amendment (greater than or equal to 0) | No |
installments | array | List of contract installments after the amendment | Depends on amendment_type |
installments[].maturity_date | string | Installment due date (format: YYYY-MM-DD) | Yes |
installments[].face_value | number | Nominal value of the installment (greater than or equal to 0) | Yes |
installments[].installment_number | integer | Sequential number of the installment, starting at 1 | Yes |
installments[].external_id | string | Identifier of the installment in your system | No |
pre_fixed | object | Pre-fixed rate configuration | Depends on amendment_type |
pre_fixed.monthly_rate | number | Monthly rate to be applied | Yes |
pre_fixed.calendar_base | string | Calendar base for calculation. Only accepted value: workdays | Yes |
Send exactly one of asset_external_id and contract_number. With neither, the API returns AAM000041; with both, AAM000042.
Response
{
"asset_amendment_key": "a914aac6-93ff-45ee-8574-f4dbaf6c0642",
"status": "pending_document",
"amendment_type": "all_contract",
"amendment_configuration": {
"amendment_configuration_key": "5f0d3a52-8c1e-4b8e-9a51-2f6a8f0c1d22",
"fund_class": {
"fund_class_key": "<fund_class_key>",
"document_number": "11.222.333/0001-81",
"name": "FUNDO EXEMPLO FIDC",
"manager": {
"manager_key": "<manager_key>",
"document_number": "22.333.444/0001-81",
"manager_name": "GESTORA EXEMPLO LTDA"
},
"accounting_date": "2024-04-01"
},
"requires_document": true
},
"asset_type": "ccb",
"asset_key": "0b6f6c55-5d1b-4b6e-8f3a-6c1f0f7f2b10",
"amendment_date": "2024-04-01",
"asset_external_id": "931e9437-d025-41ab-bb53-6b94e10fd361",
"source": "api_integration",
"status_history": [
{
"status": "pending_document",
"event_datetime": "2024-04-01T13:02:45Z"
}
]
}
The initial status depends on the amendment pipeline configuration, defined by QI Tech:
pending_document— the pipeline requires the amendment term (amendment_configuration.requires_document: true, the default). The amendment only moves forward after the document is sent.pending_processing— the pipeline does not require a document (requires_document: false). The amendment goes straight to processing.
Sending the amendment term is not available on manager-api. If the manager creates the amendment in a pipeline that requires a document, it stays stuck in pending_document. To resolve it, the term must be sent by the consultant or the assignor linked to the pipeline, or the manager can ask QI Tech, at integracao.dtvm@qitech.com.br, for an amendment pipeline that does not require a document.
Amendment Type Enumerator
| Enumerator | Description |
|---|---|
| payment_flow | Amendment of the payment flow only |
| nominal_rate | Amendment of the contract's nominal rate only |
| all_contract | Amendment of both the payment flow and the contract's nominal rate |
The installments and pre_fixed fields must or must not be sent according to the amendment type, as shown in the table below. A different combination returns AAM000008.
| Amendment type | installments | pre_fixed |
|---|---|---|
| all_contract | Required | Required |
| nominal_rate | Must not be sent | Required |
| payment_flow | Required | Must not be sent |
Amendment status
| Status | Meaning |
|---|---|
pending_document | Waiting for the amendment term |
pending_approval | Term received, waiting for approval |
pending_processing | Processing |
pending_conciliation | Waiting for the down payment (down_payment_value) to be credited to the fund's account |
pending_wallet_update | Updating the contract in the fund's portfolio |
completed | Amendment applied to the contract |
denied | Amendment denied; the reason comes in denial_reason |
Webhook
When the amendment reaches completed or denied, QI Tech sends the asset_amendment.status_change webhook to the fund's manager and to the assignor and consultant linked to the pipeline, for those who have the webhook configured. The configuration is done by QI Tech: request it at integracao.dtvm@qitech.com.br. To validate the signature, see Receiving Webhooks.
{
"webhook_type": "asset_amendment.status_change",
"webhook_datetime": "2024-04-02T10:15:00Z",
"data": {
"asset_amendment_key": "a914aac6-93ff-45ee-8574-f4dbaf6c0642",
"amendment_configuration_key": "5f0d3a52-8c1e-4b8e-9a51-2f6a8f0c1d22",
"fund_class_key": "<fund_class_key>",
"fund_class_document_number": "11.222.333/0001-81",
"asset_key": "0b6f6c55-5d1b-4b6e-8f3a-6c1f0f7f2b10",
"asset_external_id": "931e9437-d025-41ab-bb53-6b94e10fd361",
"asset_type": "ccb",
"amendment_type": "all_contract",
"amendment_date": "2024-04-01",
"status": "completed",
"down_payment_value": 400.23
}
}
down_payment_value is only present when the amendment has a down payment; denial_reason is only present when the status is denied.
Errors
| Status | Code | When it happens |
|---|---|---|
| 400 | QIT000001 | Body outside the contract: missing required field, unknown field, invalid date, value outside the enum |
| 400 | AAM000041 | Neither asset_external_id nor contract_number was sent |
| 400 | AAM000042 | asset_external_id and contract_number were sent together |
| 400 | AAM000008 | installments/pre_fixed incompatible with amendment_type |
| 404 | AAM000003 | There is no fund with this fund_class_key |
| 404 | AAM000024 | amendment_configuration_key not found for the fund |
| 404 | AAM000006 | asset_type does not exist |
| 404 | AAM000007 | No active asset with this asset_external_id and asset_type in the fund's portfolio |
| 404 | AAM000043 | No active asset with this contract_number and asset_type |
| 409 | AAM000044 | More than one active asset with the same contract_number: use asset_external_id |
| 4xx | WLT... or AAM000030 | The fund's portfolio rejected the amendment during validation. The code and description come from the portfolio; if the portfolio sends no code, AAM000030 is returned |
Authentication, permission and host errors: see API errors.