Criação de pedido de aditamento
Para realizar um pedido de aditamento é necessário realizar uma requisição usando a chave única que representa o fundo (fund_class_key, fornecida pela QI Tech) e a chave única que representa a configuração da esteira de aditamento (amendment_configuration_key, fornecida pela QI Tech).
Nos aditamentos realizados por este sistema é permitida a alteração do fluxo de pagamento, da taxa nominal do contrato ou de ambos. Também é possível definir que o aditamento será realizado juntamente com uma entrada paga pelo devedor.
| Perfil | Host | Permissão exigida |
|---|---|---|
| Gestora | manager-api | Escrita |
| Consultoria | consultant-api | Lotes |
| Cedente | assignor-api | Escrita |
URL base de cada host: Ambientes (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
| Campo | Tipo | Descrição | Obrigatório |
|---|---|---|---|
asset_external_id | string | Identificador do contrato que está sendo aditado, o mesmo com que ele foi encarteirado. Até 50 caracteres. | Um dos dois: asset_external_id ou contract_number |
contract_number | string | Número do contrato a ser aditado, alternativa ao asset_external_id. Até 50 caracteres. | Um dos dois: asset_external_id ou contract_number |
asset_type | string | Tipo do ativo aditado: ccb ou structured_cci | Sim |
amendment_date | string | Data em que o aditamento está sendo realizado (formato: YYYY-MM-DD) | Sim |
amendment_type | string | Tipo de aditamento a ser realizado. Ver Enumerador Tipo de Aditamento | Sim |
down_payment_value | number | Valor da entrada a ser paga pelo devedor no momento do aditamento (maior ou igual a 0) | Não |
installments | array | Lista de parcelas do contrato após o aditamento | Depende do amendment_type |
installments[].maturity_date | string | Data de vencimento da parcela (formato: YYYY-MM-DD) | Sim |
installments[].face_value | number | Valor nominal da parcela (maior ou igual a 0) | Sim |
installments[].installment_number | integer | Número sequencial da parcela, a partir de 1 | Sim |
installments[].external_id | string | Identificador da parcela no seu sistema | Não |
pre_fixed | object | Configurações da taxa pré-fixada | Depende do amendment_type |
pre_fixed.monthly_rate | number | Taxa mensal a ser aplicada | Sim |
pre_fixed.calendar_base | string | Base de calendário para cálculo. Único valor aceito: workdays | Sim |
Envie exatamente um entre asset_external_id e contract_number. Sem nenhum dos dois a API devolve AAM000041; com os dois, 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"
}
]
}
O status inicial depende da configuração da esteira de aditamento, definida pela QI Tech:
pending_document— a esteira exige o termo de aditamento (amendment_configuration.requires_document: true, o padrão). O aditamento só avança depois do envio do documento.pending_processing— a esteira não exige documento (requires_document: false). O aditamento segue direto para processamento.
O envio do termo de aditamento não está disponível na manager-api. Se a gestora cria o aditamento numa esteira que exige documento, ele fica parado em pending_document. Para resolver, o termo precisa ser enviado pela consultoria ou pelo cedente vinculados à esteira, ou a gestora pode pedir à QI Tech, em integracao.dtvm@qitech.com.br, uma esteira de aditamento sem exigência de documento.
Enumerador Tipo de Aditamento
| Enumerador | Descrição |
|---|---|
| payment_flow | Aditamento apenas do fluxo de pagamento |
| nominal_rate | Aditamento apenas da taxa nominal do contrato |
| all_contract | Aditamento do fluxo de pagamento e da taxa nominal do contrato |
Os campos installments e pre_fixed devem ou não ser enviados de acordo com o tipo de aditamento, conforme a tabela abaixo. Combinação diferente devolve AAM000008.
| Tipo de aditamento | installments | pre_fixed |
|---|---|---|
| all_contract | Obrigatório | Obrigatório |
| nominal_rate | Não deve ser enviado | Obrigatório |
| payment_flow | Obrigatório | Não deve ser enviado |
Status do aditamento
| Status | Significado |
|---|---|
pending_document | Aguardando o termo de aditamento |
pending_approval | Termo recebido, aguardando aprovação |
pending_processing | Em processamento |
pending_conciliation | Aguardando o crédito da entrada (down_payment_value) na conta do fundo |
pending_wallet_update | Atualizando o contrato na carteira do fundo |
completed | Aditamento aplicado ao contrato |
denied | Aditamento negado; o motivo vem em denial_reason |
Webhook
Quando o aditamento chega a completed ou denied, a QI Tech envia o webhook asset_amendment.status_change à gestora do fundo e ao cedente e à consultoria vinculados à esteira, para quem tiver o webhook configurado. A configuração é feita pela QI Tech: solicite em integracao.dtvm@qitech.com.br. Para validar a assinatura, veja Autenticação de 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 só vem quando o aditamento tem entrada; denial_reason só vem quando o status é denied.
Erros
| Status | Código | Quando acontece |
|---|---|---|
| 400 | QIT000001 | Corpo fora do contrato: campo obrigatório ausente, campo desconhecido, data inválida, valor fora do enum |
| 400 | AAM000041 | Nem asset_external_id nem contract_number foram enviados |
| 400 | AAM000042 | asset_external_id e contract_number foram enviados juntos |
| 400 | AAM000008 | installments/pre_fixed incompatíveis com o amendment_type |
| 404 | AAM000003 | Não existe fundo com essa fund_class_key |
| 404 | AAM000024 | amendment_configuration_key não encontrada para o fundo |
| 404 | AAM000006 | asset_type não existe |
| 404 | AAM000007 | Nenhum ativo ativo com esse asset_external_id e asset_type na carteira do fundo |
| 404 | AAM000043 | Nenhum ativo ativo com esse contract_number e asset_type |
| 409 | AAM000044 | Mais de um ativo ativo com o mesmo contract_number: use asset_external_id |
| 4xx | WLT... ou AAM000030 | A carteira do fundo recusou o aditamento na validação. O código e a descrição vêm da carteira; sem código da carteira, volta AAM000030 |
Erros de autenticação, permissão e host: veja Erros da API.