Manual de Aditamento

Este manual descreve o passo a passo envolvido no processo de aditamento. Trata-se do postergamento do prazo da dívida, em que ocorre a mudança na data de vencimento das parcelas e se mantém o número de contrato.

Nesse processo de aditamento, a final_debt_key retornada no webhook de desembolso é a nova chave da operação e, após esse processo, novos boletos das parcelas aditadas serão gerados.

O aditamento só é válido para operações pré-fixadas.

1 - Criação da operação de aditamento

O campo desired_installments é uma lista de objetos com o atributo due_date.

O campo de calculate_delay só está disponível no Response Body se for enviado na requisição de POST.

Nesse momento, como ainda não houve desembolso da operação originada do aditamento, os campos relacionados ao boleto, como bank_slip_key, digitable_line, qr_code_key e qr_code_url, serão nulos.

1.1. Simulação:

Request

ENDPOINT

/amendment_simulation

MÉTODO

POST

Request Body

{
	"amendment_debt_key": "\<Chave unitária da operação/debt a ser aditada\>",
	"amendment_date": "\<Nova data de referência para a operação originada a partir aditamento\>",
	"financial": {
		"calculate_delay": "\<Booleano para cálculo de juros de atraso em cima da operação a ser adiatada\>",
        "monthly_rate": "\<Valor em decimal do juros do aditamento ao mês\>", 
		"desired_installments" : [
			{
				"due_date": "\<Nova data de vencimento da parcela\>",
			}
		]
	},
	"additional_data": "\<JSON de campos adicionais livre\>",
}

Response

Response Body

{
	"amendment_debt_key": "\<Chave unitária da operação/debt a ser aditada enviada no POST\>",
	"amendment_date": "\<Nova data de referência para a operação, originada a partir da data enviada no POST\>",
	"financial":{
		"calculate_delay": "\<Booleano para cálculo de juros de atraso em cima da operação a ser adiatada\>",
        "monthly_rate": "\<Valor em decimal do juros do aditamento ao mês\>",
		"desired_installments" : [
			{
				"due_date": "\<Nova data de vencimento da parcela\>",
				"total_amount": "\<Valor da parcela\>",
			}
		]
	},
	"additional_data": "\<JSON de campos adicionais livre enviada no POST\>",
	"final_debt": {
		"annual_cet": "\<Custo Efetivo Total anual\>",
		"cet": "\<Custo Efetivo Total mensal\>",
		"installments":{
            "bank_slip_key": "\<Chave unitária do boleto relacionado a parcela\>",
            "business_due_date": "\<Data de vencimento da parcela, considerndo dias úteis\>",
            "calendar_days": "\<Dias corridos em relação a data de referência anterior\>",
            "digitable_line": "\<Linha digitável do boleto\>",
            "due_date": "\<Data de vencimento da parcela\>",
            "due_interest": "\<Valor de Juros da parcela\>",
            "due_principal":"\<Valor Principal da parcela\>",
            "installment_key": "\<Chave unitária característica da parcela\>",
            "installment_number": "\<Número da parcela dentro do total de parcelas\>",
            "post_fixed_amount": "\<Valor de Juros pós-fixado da parcela\>",
            "pre_fixed_amount": "\<Valor de Juros pré-fixado da parcela\>",
            "principal_amortization_amount": "\<Valor de amortização de principal da parcela\>",
            "qr_code_key": "\<Chave unitária do QR Code associado ao boleto\>",
            "qr_code_url": "\<URL do QR Code associado ao boleto\>",
            "total_amount": "\<Valor Total da parcela\>",
            "workdays": "\<Dias úteis em relação a data de referência anterior\>",
        },
		"prefixed_interest_rate": {
			"annual_rate": "\<Taxa anual de juros pré-fixado\>",
        	"daily_rate": "\<Taxa diária de juros pré-fixado\>",
        	"interest_base": "\<Base de cálculo de juros\>",
        	"monthly_rate": "\<Taxa mensal de juros pré-fixado\>",
    	},
		"issue_amount": "\<Valor de emissão da operação de aditamento\>",
		"number_of_installments": "\<Número de parcelas\>",
		"total_iof": "\<IOF da operação\>"
	}
}

1.2. Criação:

Request

ENDPOINT

/amendment

MÉTODO

POST

Request Body

{
	"amendment_debt_key": "\<Chave unitária da operação/debt a ser aditada\>",
	"amendment_date": "\<Nova data de referência para a operação originada a partir aditamento\>",
	"financial": {
		"calculate_delay": "\<Booleano para cálculo de juros de atraso em cima da operação a ser adiatada\>",
        "monthly_rate": "\<Valor em decimal do juros do aditamento ao mês\>",
		"desired_installments" : [
			{
				"due_date": "\<Nova data de vencimento da parcela\>",
			}
		]
	},
	"additional_data": "\<JSON de campos adicionais livre\>",
}

Response

Response Body

{
	"amendment_key": "\<Chave unitária característica do aditamento\>",
	"amendment_debt_key": "\<Chave unitária da operação/debt a ser aditada enviada no POST\>",
	"amendment_date": "\<Nova data de referência para a operação, originada a partir da data enviada no POST\>",
	"financial":{
		"calculate_delay": "\<Booleano para cálculo de juros de atraso em cima da operação a ser adiatada\>",
        "monthly_rate": "\<Valor em decimal do juros do aditamento ao mês\>",
		"desired_installments" : [
			{
				"due_date": "\<Nova data de vencimento da parcela\>",
				"total_amount": "\<Valor da parcela\>",
			}
		]
	},
	"additional_data": "\<JSON de campos adicionais livre enviada no POST\>",
	"amendment_status": "waiting_signature",
	"document_key": "\<Chave unitária do documento/contrato da operação de aditamento\>",
	"document_url": "\<URL do documento/contrato da operação de aditamento\>",
	"final_debt": {
		"annual_cet": "\<Custo Efetivo Total anual\>",
		"cet": "\<Custo Efetivo Total mensal\>",
		"installments":{
            "bank_slip_key": "\<Chave unitária do boleto relacionado a parcela\>",
            "business_due_date": "\<Data de vencimento da parcela, considerndo dias úteis\>",
            "calendar_days": "\<Dias corridos em relação a data de referência anterior\>",
            "digitable_line": "\<Linha digitável do boleto\>",
            "due_date": "\<Data de vencimento da parcela\>",
            "due_interest": "\<Valor de Juros da parcela\>",
            "due_principal":"\<Valor Principal da parcela\>",
            "installment_key": "\<Chave unitária característica da parcela\>",
            "installment_number": "\<Número da parcela dentro do total de parcelas\>",
            "post_fixed_amount": "\<Valor de Juros pós-fixado da parcela\>",
            "pre_fixed_amount": "\<Valor de Juros pré-fixado da parcela\>",
            "principal_amortization_amount": "\<Valor de amortização de principal da parcela\>",
            "qr_code_key": "\<Chave unitária do QR Code associado ao boleto\>",
            "qr_code_url": "\<URL do QR Code associado ao boleto\>",
            "total_amount": "\<Valor Total da parcela\>",
            "workdays": "\<Dias úteis em relação a data de referÊncia anterior\>",
        },
		"prefixed_interest_rate": {
			"annual_rate": "\<Taxa anual de juros pré-fixado\>",
        	"daily_rate": "\<Taxa diária de juros pré-fixado\>",
        	"interest_base": "\<Base de cálculo de juros\>",
        	"monthly_rate": "\<Taxa mensal de juros pré-fixado\>",
    	},
		"issue_amount": "\<Valor de emissão da operação de aditamento\>",
		"number_of_installments": "\<Número de parcelas\>",
		"total_iof": "\<IOF da operação\>"
	}
}

Em relação a simulação, o Response Body da criação se diferencia pela presença da amendment_key, da amendment_status, da document_key e da document_url.

Na criação do operação de aditamento, sempre se retorna o amendment_status como "waiting_signature".

2 - GET da operação de aditamento

Request

ENDPOINT

/amendment/[AMENDMENT_KEY]

MÉTODO

GET

O amendment_key que deve ser enviado para realização do GET é o valor do campo, de mesmo nome, retornado na criação da operação de aditamento e que representa a chave unitária característica do aditamento.

Response

Response Body

{
	"amendment_key": "\<Chave unitária característica do aditamento\>",
	"amendment_debt_key": "\<Chave unitária da operação/debt a ser aditada enviada no POST\>",
	"amendment_date": "\<Nova data de referência para a operação, originada a partir da data enviada no POST\>",
	"financial":{
		"calculate_delay": "\<Booleano para cálculo de juros de atraso em cima da operação a ser adiatada\>",
        "monthly_rate": "\<Valor em decimal do juros do aditamento ao mês\>",
		"desired_installments" : [
			{
				"due_date": "\<Nova data de vencimento da parcela\>",
				"total_amount": "\<Valor da parcela\>",
			}
		]
	},
	"additional_data": "\<JSON de campos adicionais livre enviada no POST\>",
	"amendment_status":  "\<Status do aditamento\>",
	"document_key": "\<Chave unitária do documento/contrato da operação de aditamento\>",
	"document_url": "\<URL do documento/contrato da operação de aditamento\>",
	"final_debt": {
		"annual_cet": "\<Custo Efetivo Total anual\>",
		"cet": "\<Custo Efetivo Total mensal\>",
		"installments":{
            "bank_slip_key": "\<Chave unitária do boleto relacionado a parcela\>",
            "business_due_date": "\<Data de vencimento da parcela, considerndo dias úteis\>",
            "calendar_days": "\<Dias corridos em relação a data de referência anterior\>",
            "digitable_line": "\<Linha digitável do boleto\>",
            "due_date": "\<Data de vencimento da parcela\>",
            "due_interest": "\<Valor de Juros da parcela\>",
            "due_principal":"\<Valor Principal da parcela\>",
            "installment_key": "\<Chave unitária característica da parcela\>",
            "installment_number": "\<Número da parcela dentro do total de parcelas\>",
            "post_fixed_amount": "\<Valor de Juros pós-fixado da parcela\>",
            "pre_fixed_amount": "\<Valor de Juros pré-fixado da parcela\>",
            "principal_amortization_amount": "\<Valor de amortização de principal da parcela\>",
            "qr_code_key": "\<Chave unitária do QR Code associado ao boleto\>",
            "qr_code_url": "\<URL do QR Code associado ao boleto\>",
            "total_amount": "\<Valor Total da parcela\>",
            "workdays": "\<Dias úteis em relação a data de referência anterior\>",
        },
		"prefixed_interest_rate": {
			"annual_rate": "\<Taxa anual de juros pré-fixado\>",
        	"daily_rate": "\<Taxa diária de juros pré-fixado\>",
        	"interest_base": "\<Base de cálculo de juros\>",
        	"monthly_rate": "\<Taxa mensal de juros pré-fixado\>",
    	},
		"issue_amount": "\<Valor de emissão da operação de aditamento\>",
		"number_of_installments": "\<Número de parcelas\>",
		"total_iof": "\<IOF da operação\>"
	}
}

Response Canceled

Response Body

{
	"amendment_key": "\<Chave unitária característica do aditamento\>",
	"amendment_debt_key": "\<Chave unitária da operação/debt a ser aditada enviada no POST\>",
	"amendment_date": "\<Nova data de referência para a operação, originada a partir da data enviada no POST\>",
	"financial":{
		"calculate_delay": "\<Booleano para cálculo de juros de atraso em cima da operação a ser adiatada\>",
        "monthly_rate": "\<Valor em decimal do juros do aditamento ao mês\>",
		"desired_installments" : [
			{
				"due_date": "\<Nova data de vencimento da parcela\>",
				"total_amount": "\<Valor da parcela\>",
			}
		]
	},
	"additional_data": "\<JSON de campos adicionais livre enviada no POST\>",
	"amendment_status":  "canceled",
	"cancel_reason": {
		"enumerator": "non_signed_amendment",
		"description": "It wasn't possible to effect the amendment of the operation, because the amended operation hasn't been signed until the sent reference date (2023-09-19).",
		"translation": "Não foi possível efetivar o aditamento da operação, pois a operação de aditamento não foi assinada até a data de referência enviada (2023-09-19)."
	},
	"document_key": "\<Chave unitária do documento/contrato da operação de aditamento\>",
	"document_url": "\<URL do documento/contrato da operação de aditamento\>",
	"final_debt": {
		"annual_cet": "\<Custo Efetivo Total anual\>",
		"cet": "\<Custo Efetivo Total mensal\>",
		"installments":{
            "bank_slip_key": "\<Chave unitária do boleto relacionado a parcela\>",
            "business_due_date": "\<Data de vencimento da parcela, considerndo dias úteis\>",
            "calendar_days": "\<Dias corridos em relação a data de referência anterior\>",
            "digitable_line": "\<Linha digitável do boleto\>",
            "due_date": "\<Data de vencimento da parcela\>",
            "due_interest": "\<Valor de Juros da parcela\>",
            "due_principal":"\<Valor Principal da parcela\>",
            "installment_key": "\<Chave unitária característica da parcela\>",
            "installment_number": "\<Número da parcela dentro do total de parcelas\>",
            "post_fixed_amount": "\<Valor de Juros pós-fixado da parcela\>",
            "pre_fixed_amount": "\<Valor de Juros pré-fixado da parcela\>",
            "principal_amortization_amount": "\<Valor de amortização de principal da parcela\>",
            "qr_code_key": "\<Chave unitária do QR Code associado ao boleto\>",
            "qr_code_url": "\<URL do QR Code associado ao boleto\>",
            "total_amount": "\<Valor Total da parcela\>",
            "workdays": "\<Dias úteis em relação a data de referência anterior\>",
        },
		"prefixed_interest_rate": {
			"annual_rate": "\<Taxa anual de juros pré-fixado\>",
        	"daily_rate": "\<Taxa diária de juros pré-fixado\>",
        	"interest_base": "\<Base de cálculo de juros\>",
        	"monthly_rate": "\<Taxa mensal de juros pré-fixado\>",
    	},
		"issue_amount": "\<Valor de emissão da operação de aditamento\>",
		"number_of_installments": "\<Número de parcelas\>",
		"total_iof": "\<IOF da operação\>"
	}
}

3 - Cancelamento da operação de aditamento

Request

ENDPOINT

/amendment/[AMENDMENT_KEY]

MÉTODO

DELETE

O amendment_key que deve ser enviado para realização do DELETE é o valor do campo, de mesmo nome, retornado na criação da operação de aditamento e que representa a chave unitária característica do aditamento.

No DELETE do aditamento, não há payload de resposta e o status da operação de aditamento é alterado para "canceled".

4 - Webhooks

Atenção!

Os webhooks da QI Tech não devem ser mapeadas de forma restrita. Campos adicionais podem ser incluídos aos payloads dos webhooks retornados em nossas APIs.

Reenvio de Webhooks

Você pode consultar e reenviar webhooks seguindo as instruções detalhadas na documentação: Reenvio de Webhooks.

Abaixo estão descritos os webhooks que serão enviados nas situações de assinatura, de desembolso e de cancelamento da operação de aditamento.

4.1. Assinatura:

Body

{
    "webhook_type": "amendment",
	"amendment_key": "\<Chave unitária característica do aditamento\>",
    "event_datetime": "\<String de data referente ao momento de assinatura no formato da ISO8601\>",
    "data": {
            "amendment_status": "signed",
            "document_key": "\<Chave unitária do documento/contrato da operação de aditamento\>",
            "signed_document_url": "\<URL do documento/contrato da operação de aditamento assinado\>"
            }
}

4.2. Desembolso:

Body

{
	"webhook_type": "amendment",
	"amendment_key": "\<Chave unitária característica do aditamento\>",
	"event_datetime": "\<String de data referente ao momento de desembolso no formato da ISO8601\>",
	"data": {
		"amendment_status": "disbursed",
		"final_debt_key": "\<Chave unitária da operação/debt originada do aditamento\>",
		"installments": [
			{
            "bank_slip_key": "\<Chave unitária do boleto relacionado a parcela\>",
            "business_due_date": "\<Data de vencimento da parcela, considerndo dias úteis\>",
            "calendar_days": "\<Dias corridos em relação a data de referência anterior\>",
            "digitable_line": "\<Linha digitável do boleto\>",
            "due_date": "\<Data de vencimento da parcela\>",
            "due_interest": "\<Valor de Juros da parcela\>",
            "due_principal":"\<Valor Principal da parcela\>",
            "installment_key": "\<Chave unitária característica da parcela\>",
            "installment_number": "\<Número da parcela dentro do total de parcelas\>",
            "post_fixed_amount": "\<Valor de Juros pós-fixado da parcela\>",
            "pre_fixed_amount": "\<Valor de Juros pré-fixado da parcela\>",
            "principal_amortization_amount": "\<Valor de amortização de principal da parcela\>",
            "qr_code_key": "\<Chave unitária do QR Code associado ao boleto\>",
            "qr_code_url": "\<URL do QR Code associado ao boleto\>",
            "total_amount": "\<Valor Total da parcela\>",
            "workdays": "\<Dias úteis em relação a data de referência anterior\>"
        }
	]
	}
}

4.3. Cancelamento:

Body

{
    "webhook_type": "amendment",
	"amendment_key": "\<Chave unitária característica do aditamento\>",
    "event_datetime": "\<String de data referente ao momento de desembolso no formato da ISO8601\>",
    "data": {
		"amendment_status": "canceled",
		"cancel_reason": {
			"enumerator": "\<Enumerador do motivo de cancelamento\>",
			"description": "\<Descrição do motivo de cancelamento em inglês\>",
			"translation": "\<Tradução da descrição do motivo de cancelamento\>"
		}
	}
}

A cancel_reason segue os seguintes enumeradores: Enumerador Cancel Reason.

5 - Informações Gerais

A referência anterior nos campos calendar_days ou workdays é a data de desembolso na primeira parcela e a data de vencimento da parcela anterior nos demais casos.

O campo installments é uma lista preenchida de objetos. Nesse caso, para cada parcela do aditamento, deve haver um objeto com as respectivas informações.

Campo	Tipo	Exemplo	Observações
`additional_data`	json		Não é obrigatório seu envio
`amendment_key`	string	5fd3ecc8-1ea5-4d23-835c-37338da96181
`amendment_date`	string	"2023-06-05"
`amendment_debt_key`	string	31327efa-a96e-4a17-b703-e9fc39e17902
`amendment_status`	enumerador	Enumerador Amendment Status
`annual_cet`	float	0.0012
`annual_rate`	float	0.0012
`bank_slip_key`	string	aea9ab16-d211-4c17-8f46-8a2669154a37
`business_due_date`	string	"2023-10-05"
`calculate_delay`	bool	True	Não é obrigatório seu envio e é default como Falso
`calendar_days`	int	27
`cet`	float	0.0012
`daily_rate`	float	0.0012
`digitable_line`	string	32990001031000699925351000000201192690000055231
`document_key`	string	7f49d9ff-0878-4d48-8cc3-cb0c3c6769d2
`document_url`	string	"https://storage.googleapis.com/sandbox-doc-api/documents/7f49d9ff-0878-4d48-8cc3-cb0c3c6769d2/image_166618030043.jpg"
`due_date`	string	"2023-06-05"
`due_interest`	float	0.0
`due_principal`	float	1000.10
`event_datetime`	string	"2023-05-05T22:20:10Z"
`final_debt_key`	string	8779a554-1ec9-40ec-8ff2-cbd52fc776ef	Essa é a nova debt key
`installment_number`	int	3
`installment_key`	string	1b65d775-b5ab-49d5-a833-46980387afb1
`interest_base`	enumerador	Enumerador Interest Base
`issue_amount`	float	1000.00
`monthly_rate`	float	0.0012
`number_of_installments`	int	3
`post_fixed_amount`	int	0	Sempre zero, já que o aditamento só é válido para operações pré-fixadas
`pre_fixed_amount`	float	2.00
`principal_amortization_amount`	float	20.00
`qr_code_key`	string	003590d0-29f8-4d18-93bb-a7c36f0f1785
`qr_code_url`	string	"00020126970014br.gov.bcb.pix2575qrcode-h.sandbox.qitech.app/bacen/cobv/cf7d2d2e-003a-4296-9daf-350864d282245204000053039865802BR5925QI SOCIEDADE DE CREDITO D6009Sao Paulo61080145200062070503***63047335"
`signed_document_url`	string	"https://storage.googleapis.com/sandbox-doc-api/documents/7f49d9ff-0878-4d48-8cc3-cb0c3c6769d2/image_166618030043.jpg"
`total_amount`	float	100.00
`total_iof`	float	11.03
`workdays`	int	10

Enumerador Interest Base

Enumerador	Descrição
workdays	Base de cálculo de juros em dias úteis considerando um ano de 252 dias
calendar_days	Base de cálculo de juros em dias corridos considerando um ano de 360 dias
calendar_days_365	Base de cálculo de juros em dias corridos considerando um ano de 365 dias

Enumerador Amendment Status

Enumerador	Descrição
waiting_signature	Aguardando assinatura
signed	Assinada
disbursed	Desembolsada
canceled	Cancelada
disbursing_error	Erro no momento do desembolso

Atenção!

O status 'disbursing_error' representa um status intermediário, o contrato de aditamento será cancelado ou desembolsado.

Enumerador Cancel Reason

Enumerador	Descrição
delete_amendment	Requisição no endpoint de DELETE
non_signed_amendment	Operação de aditamento não foi assinada até a data de referência enviada (amendment_date)
different_balance_due	Saldo devedor diferente entre a criação da operação de aditamento e o desembolso
different_installments_number	Número de parcelas em aberto diferente entre a criação da operação de aditamento e o desembolso

Manual de Aditamento

1 - Criação da operação de aditamento​

2 - GET da operação de aditamento​

3 - Cancelamento da operação de aditamento​

4 - Webhooks​

5 - Informações Gerais​

Enumerador Interest Base​

Enumerador Amendment Status​

Enumerador Cancel Reason​

1 - Criação da operação de aditamento

2 - GET da operação de aditamento

3 - Cancelamento da operação de aditamento

4 - Webhooks

5 - Informações Gerais

Enumerador Interest Base

Enumerador Amendment Status

Enumerador Cancel Reason