延期修改手册

本手册描述了延期修改（Aditamento）流程的分步说明。该操作是对债务偿还期限的延后，即对分期付款到期日进行变更，同时保持合同编号不变。

在此延期修改流程中，放款 webhook 中返回的 final_debt_key 是该操作的新密钥，在此流程完成后，将为已修改的分期生成新的银行单据（boletos）。

延期修改仅对固定利率（pré-fixadas）操作有效。

1 - 创建延期修改操作

desired_installments 字段是一个包含 due_date 属性的对象列表。

calculate_delay 字段仅在请求的 POST 中发送时，才会在 Response Body 中返回。

此时，由于延期修改操作尚未放款，与银行单据相关的字段（如 bank_slip_key、digitable_line、qr_code_key 和 qr_code_url）将为空。

1.1. 模拟：

        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. 创建：

        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\>"
	}
}

与模拟相比，创建操作的 Response Body 的区别在于包含了 amendment_key、amendment_status、document_key 和 document_url。

在创建延期修改操作时，amendment_status 始终返回为 "waiting_signature"。

2 - 查询延期修改操作

        Request

ENDPOINT

/amendment/[AMENDMENT_KEY]

MÉTODO

GET

执行 GET 请求时需要发送的 amendment_key 是在创建延期修改操作时返回的同名字段的值，代表该延期修改操作的唯一标识密钥。

        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 - 取消延期修改操作

        Request

ENDPOINT

/amendment/[AMENDMENT_KEY]

MÉTODO

DELETE

执行 DELETE 时需要发送的 amendment_key 是在创建延期修改操作时返回的同名字段的值，代表该延期修改操作的唯一标识密钥。

执行 DELETE 后，不返回响应负载，延期修改操作的状态将更改为 "canceled"。

4 - Webhooks

注意！

QI Tech 的 webhooks 不应被严格映射。 API 返回的 webhook 负载中可能会添加额外字段。

Webhook 重发

您可以按照文档中的详细说明查询和重发 webhooks：重发 Webhooks。

以下描述了在延期修改操作签署、放款和取消情况下将发送的 webhooks。

4.1. 签署：

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. 放款：

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. 取消：

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\>"
		}
	}
}

cancel_reason 遵循以下枚举值：Cancel Reason 枚举。

5 - 一般信息

calendar_days 或 workdays 字段中的"前一参考日期"是指：第一期的放款日期，以及其他期次中前一期的到期日。

installments 字段是一个填充了对象的列表。在此情况下，延期修改的每一期都应有一个包含相应信息的对象。

字段	类型	示例	备注
additional_data	json		非必填
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	枚举	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	非必填，默认为 False
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	这是新的 debt key
installment_number	int	3
installment_key	string	1b65d775-b5ab-49d5-a833-46980387afb1
interest_base	枚举	Interest Base 枚举
issue_amount	float	1000.00
monthly_rate	float	0.0012
number_of_installments	int	3
post_fixed_amount	int	0	始终为零，因为延期修改仅对固定利率操作有效
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

Interest Base 枚举

枚举值	描述
workdays	以工作日为基础计算利息，一年按 252 个工作日计算
calendar_days	以自然日为基础计算利息，一年按 360 天计算
calendar_days_365	以自然日为基础计算利息，一年按 365 天计算

Amendment Status 枚举

枚举值	描述
waiting_signature	等待签署
signed	已签署
disbursed	已放款
canceled	已取消
disbursing_error	放款时发生错误

注意！

'disbursing_error' 状态代表一个中间状态，延期修改合同将被取消或放款。

Cancel Reason 枚举

枚举值	描述
delete_amendment	对 DELETE 端点发起请求
non_signed_amendment	延期修改操作在发送的参考日期（amendment_date）前未签署
different_balance_due	创建延期修改操作与放款时的未偿余额不同
different_installments_number	创建延期修改操作与放款时的未偿期数不同