# QI Tech — Other Products Documentação da QI Tech em texto corrido, para colar em um LLM. Fonte: https://docs.qitech.com.br 40 página(s). Índice: - Credit Rights Assignment Manual (/en/documentation/iaas/negociacao_recebiveis/manual_api) - Homologation Roadmap - BNPL (/en/documentation/manual_bnpl_ecommerce/) - Inquiry - BNPL Issuance (/en/documentation/manual_bnpl_full/emissao/consulta) - BNPL Issuance (/en/documentation/manual_bnpl_full/emissao/) - Simulation - BNPL Issuance (/en/documentation/manual_bnpl_full/emissao/simulacao) - Webhooks - BNPL Issuance (/en/documentation/manual_bnpl_full/emissao/webhooks) - BNPL Reversal (/en/documentation/manual_bnpl_full/estorno/) - Refund via Amortization — equal_amount and full_settle (/en/documentation/manual_bnpl_full/estorno/estorno_amortizacao) - Webhooks - BNPL Reversal (/en/documentation/manual_bnpl_full/estorno/webhooks) - Present Value Inquiry - BNPL Refinancing (/en/documentation/manual_bnpl_full/refinanciamento/consulta_valor_presente) - Creation - BNPL Refinancing (/en/documentation/manual_bnpl_full/refinanciamento/criacao) - Introduction - BNPL Refinancing (/en/documentation/manual_bnpl_full/refinanciamento/introducao) - Simulation - BNPL Refinancing (/en/documentation/manual_bnpl_full/refinanciamento/simulacao) - Scenarios - BNPL Batch Renegotiation (/en/documentation/manual_bnpl_full/renegociacao/cenarios) - Inquiry - BNPL Batch Renegotiation (/en/documentation/manual_bnpl_full/renegociacao/consulta) - Renegotiation with IOF Spread and Interest-Only Discount - BNPL (/en/documentation/manual_bnpl_full/renegociacao/iof-spread-e-desconto-juros) - Batch Renegotiation Proposal - BNPL (/en/documentation/manual_bnpl_full/renegociacao/proposta) - Simulation - BNPL Batch Renegotiation (/en/documentation/manual_bnpl_full/renegociacao/simulacao) - Webhooks - BNPL Batch Renegotiation (/en/documentation/manual_bnpl_full/renegociacao/webhooks) - Integration Scripts - BNPL Full (/en/documentation/manual_bnpl_full/scripts_integracao) - Consulta - Emissão Crédito Clean (/en/documentation/manual_credito_clean/emissao/consulta) - Consulta de Cessão (/en/documentation/manual_credito_clean/emissao/consulta_cessao) - Emissão com Assinatura Posterior (/en/documentation/manual_credito_clean/emissao/emissao_dois_passos) - Issuance with Immediate Signature (/signed_debt) (/en/documentation/manual_credito_clean/emissao/emissao_signed_debt) - Simulação - Emissão Crédito Clean (/en/documentation/manual_credito_clean/emissao/simulacao) - Webhooks - Emissão Crédito Clean (/en/documentation/manual_credito_clean/emissao/webhooks) - Estorno Crédito Clean (/en/documentation/manual_credito_clean/estorno/) - Webhooks - Estorno Crédito Clean (/en/documentation/manual_credito_clean/estorno/webhooks) - Notificações - Crédito Clean (/en/documentation/manual_credito_clean/notificacoes) - Consulta de Valor Presente - Refinanciamento Crédito Clean (/en/documentation/manual_credito_clean/refinanciamento/consulta_valor_presente) - Criação - Refinanciamento Crédito Clean (/en/documentation/manual_credito_clean/refinanciamento/criacao) - Introdução - Refinanciamento Crédito Clean (/en/documentation/manual_credito_clean/refinanciamento/introducao) - Simulação - Refinanciamento Crédito Clean (/en/documentation/manual_credito_clean/refinanciamento/simulacao) - Cenários - Renegociação em Lote Crédito Clean (/en/documentation/manual_credito_clean/renegociacao/cenarios) - Consulta - Renegociação em Lote Crédito Clean (/en/documentation/manual_credito_clean/renegociacao/consulta) - Proposta de Renegociação em Lote - Crédito Clean (/en/documentation/manual_credito_clean/renegociacao/proposta) - Simulação - Renegociação em Lote Crédito Clean (/en/documentation/manual_credito_clean/renegociacao/simulacao) - Webhooks - Renegociação em Lote Crédito Clean (/en/documentation/manual_credito_clean/renegociacao/webhooks) - Scripts de Integração - Crédito Clean (/en/documentation/manual_credito_clean/scripts_integracao) - Manual QI Sign (/en/documentation/manual_qi_sign/) --- # Credit Rights Assignment Manual URL: /en/documentation/iaas/negociacao_recebiveis/manual_api This manual describes the step-by-step process involved in Credit Rights Assignment to Funds administered by QI CTVM. It also explains the business rules of the product and the key points that the integrating partner must be aware of for a faster and more efficient integration. ## Prerequisites 1. An Assignment Contract must have been established and the respective Product must have been activated (see **[Assignor Onboarding](/documentation/iaas/homologacao_cedente/contrato_de_cessao/pedido_de_contrato)** APIs); 2. Only the Fund Manager, the Assignor party to the Contract, and linked Originators can access this service. 3. The unique identification key of the Assignee Fund ( fund_class_key ) and the unique identification key of the Assignment Configuration ( assignment_configuration_key ) must be stored. ```python BASE_URL = "/fund_class/{fund_class_key}/assignment_configuration/{assignment_configuration_key}" ``` :::info The _**BASE_URL**_ will be the path used in all endpoints of this API. ::: ## State Flow The Assignment pipeline has two main entities with related state machines. On one side we have the Batch, called assignment , and on the other we have the Assets, called asset . For the former, the flow is as follows: ```mermaid graph TB LA[pending_assets_insertion] --> |Close Insertion| LB[completed_assets_insertion] LB --> |All Assets Pre-approved or Discarded| LC[pending_eligibility] LC --> |Not accepted| LZ[discarded] LC --> |Accepted| LD[pending_manager_approval] LD --> |Manager rejected| LZ LD --> |Manager approved| LE[pending_assignment_term_signature] LE --> |Term Signed| LG[pending_payment] LG --> |Payment| LH[pending_assets_wallet_inclusion] LH --> |All Assets in Portfolio| LI[completed] ``` For the Asset: ```mermaid graph TB LA[pending_eligibility] --> |Accepted| LB[pending_documentation] LA --> |Not accepted| LZ[discarded] LB --> |Documents Inserted| LC[pre_approved] LC --> |Manager approved| LE[pending_formalization] LE --> |Payment| LH[sending_to_wallet] LH --> |In Portfolio| LI[completed] ``` ## Integration Summary In summary, to reach Asset Portfolio Inclusion, the following steps apply: 1. Batch Creation; 2. Asset Insertion; 3. Close Asset Insertion; 4. Asset Eligibility Webhook; 5. Document Submission; 6. Batch Eligibility Webhook; 7. Manager Approval; 8. Assignment Term Signature; 9. Assignment Payment; 10. Asset Portfolio Inclusion; ## 1 - Batch Creation For **[Batch creation](/documentation/iaas/negociacao_recebiveis/assignment/criacao)**, only a unique identifier generated in the integrating partner's system is required. This will be the identifier used both in Webhook responses and in the routes for other features explained below. It is critically important that this identifier is unique — the QI CTVM system will not allow the partner to send the same Batch twice. ## 2 - Asset Insertion Asset insertion is the most delicate part of the entire integration. This section explains the business rules involved in creating Assets, both those independent of asset type and those specific to a particular type. It is important for understanding this API to understand the concept of Asset Value and Asset Purchase Value. For this, the following notation is used: **[A]** as the Asset Purchase Value, provided at the root of the object — it means how much the Fund should pay for this Asset. **[B]** as the total sum of Premiums for the operation. It can be obtained by summing all total_values of the premiums provided. **[C]** as the total sum of Discounts for the operation. It can be obtained by summing all total_values of the deductions provided. **[D]** as the Asset Value, which can be inferred using the following formula: :::tip Relationship [D] = [A] - [B] + [C] ::: ### 2.1 - Asset Type-Independent Rules #### 2.1.1 - Asset Type Compatibility with Assignment Configuration Each Assignment Configuration is unique per asset type. It is never possible to place CCBs and Invoices in the same batch, for example. The activated product that generated the assignment_configuration_key contains a specific asset type, and that will be the only type accepted in a given Configuration. If this is violated, the following error will be returned: Response Body STATUS 400 ```json title='Response Body' { "code": "TRC000025" } ``` #### 2.1.2 - Insertion into Closed Batches If an attempt is made to insert an asset into batches that have already been closed, the integrating partner will receive the following error: Response Body STATUS 400 ```json title='Response Body' { "code": "TRC000022" } ``` #### 2.1.3 - Postal Code Validation The postal code of the borrower's address object must be valid. If an invalid one is provided, the request will not be accepted and will return the following error: Response Body STATUS 404 ```json title='Response Body' { "code": "TRC000070" } ``` #### 2.1.4 - External ID Uniqueness The same asset cannot be assigned twice by the partner. Therefore, if the asset already exists in our database and has not been discarded, the following error will be raised: Response Body STATUS 409 ```json title='Response Body' { "code": "TRC000054" } ``` ### 2.2 - Rules for Credit Operations Credit Operations are assets that derive from a commitment made by a Borrower, who borrows money at a given rate and honors a payment commitment according to a specific flow. Therefore, these assets always have an outstanding principal and an interest rate that increases this value. The data structure required for creating a Credit Operation can be found **[on this page](/documentation/iaas/negociacao_recebiveis/asset/criacao_co)**. #### 2.2.1 - Asset Value vs Outstanding Principal Divergence For a Credit Operation, the Asset Value must always be greater than or equal to the Outstanding Principal (the principal_value field of the Credit Operation object). The error related to this business rule is: Response Body STATUS 409 ```json title='Response Body' { "code": "TRC000054" } ``` #### 2.2.2 - Contract Issue Value vs Outstanding Principal Divergence The Contract Issue Value must always be greater than or equal to the Outstanding Principal. The error related to this business rule is: Response Body STATUS 409 ```json title='Response Body' { "code": "TRC000054" } ``` #### 2.2.3 - Sequential Installments All installments of a credit operation must be ordered in ascending order by maturity date ( maturity_date ) with sequential numbers ( installment_number ). If the flow starts with installment number 1, the next must be 2, then 3, and so on. The errors related to these rules are respectively: Response Body STATUS 409 ```json title='Response Body' { "code": "TRC000054" } ``` Response Body STATUS 409 ```json title='Response Body' { "code": "TRC000054" } ``` #### 2.2.4 - Pre-fixed and Post-fixed Objects According to the interest rate type ( interest_rate_type ) of an operation, pre-fixed and/or post-fixed objects must be provided. If the interest rate type is pre-fixed, **only** the pre-fixed object is required. For post-fixed, the post-fixed object is **mandatory** and the pre-fixed is **optional**. ## 3 - Close Asset Insertion After all assets in the Batch have been created, the partner can trigger **[closure of Asset Insertion](/documentation/iaas/negociacao_recebiveis/assignment/fechamento)**. This process is important so that the QI CTVM system knows that from this point, once all assets have been properly analyzed by Eligibility with all documentation provided, the Eligibility of the entire Batch can be analyzed. :::info It is not necessary to wait for the Webhook of all Assets before performing this action. As soon as no more assets are to be inserted, this command can be executed. ::: ## 4 - Asset Eligibility Webhook As Assets are analyzed against the Fund's Eligibility rules, the system returns **[Webhooks](/documentation/iaas/negociacao_recebiveis/asset/webhooks)**, one by one. These Webhooks will be identified by the unique asset identifier provided by the partner at creation time. Only two outcomes can result from this analysis: asset **approval** or **rejection**. If the former occurs, the Asset will proceed in the pipeline, subject to document insertion. Otherwise, it moves to the discarded state and will not proceed to the next steps. ## 5 - Document Submission Upon approval of an asset in Eligibility, the partner can proceed with **[document insertion](/documentation/iaas/negociacao_recebiveis/asset/documents)** required by the product. Each required document must be submitted in a separate request. Content is transmitted as a Base64 binary, making it possible via JSON like all other APIs in our system. Note that this request requires, in addition to the file binary, the document type. The Asset will only proceed in the pipeline when all required documents have been submitted. When that happens, it will move to the Pre-Approved ( pre_approved ) state. :::warning Warning The required documents depend on the Product type and the Fund Regulations. This can be obtained by retrieving the Product from the Assignment Contract that was activated to obtain the assignment_configuration_key for this batch. ::: :::info It is not necessary to have triggered the Asset Insertion Closure. If you want to link the Document Submission logic to the Receipt of the Webhook, this is entirely possible and recommended. ::: ## 6 - Batch Eligibility Webhook As soon as a Batch that has had asset insertion closed, and all its Assets have been either discarded or pre-approved, it will proceed to a Batch-wide Eligibility analysis. Even if all Assets have been approved, the Batch as a whole may cause fund non-compliance. This is why a second eligibility step is needed. Similar to the Asset, there are two possible outcomes from Eligibility: approval or rejection. The result will be reported through a **[Webhook](/documentation/iaas/negociacao_recebiveis/assignment/webhooks)**, this time identified by the Batch external_id . If the Batch is rejected, it will be discarded and the process ends. Otherwise, it will proceed to a Manager review and approval step. ## 7 - Manager Approval Manager approval must be done through a **[specific request](/documentation/iaas/negociacao_recebiveis/assignment/aprovacao)**, or through our **[Portal](https://manager-dash.qidtvm.com.br/)**. If the Batch is denied, it will be discarded and the process ends. Otherwise, the system generates the Assignment Term and sends it for signature, putting the Batch in the pending_assignment_term_signature state, where it will remain until all related parties sign the Document. ## 8 - Assignment Term Signature Once signed, we send a **[Webhook](/documentation/iaas/negociacao_recebiveis/assignment/webhooks)** notifying that the Term has been signed and should proceed to payment, moving to pending_payment . ## 9 - Assignment Payment At this point, the system pays the Assignor the total amount of the Assignment — the sum of all total_purchase_value of non-discarded assets — to the account provided at the time of Product activation. Once this payment is confirmed, we send a **[Webhook](/documentation/iaas/negociacao_recebiveis/assignment/webhooks)** and assets begin to be included in the portfolio. ## 10 - Asset Portfolio Inclusion Finally, once all assets have been properly included in the portfolio, the Batch becomes completed . From this point, the integrating partner can be fully certain that all those assets are properly within the Fund's inventory. --- # Homologation Roadmap - BNPL URL: /en/documentation/manual_bnpl_ecommerce/ ## Summary The objective of this document is to guide all clients through the integration process of Buy Now Pay Later (BNPL) with QI Tech's platform. This document outlines the key steps involved and addresses potential questions. For further details, please refer to the full documentation provided in **[item 10](#10---references)**. ## 1. Document upload To receive the document_key for the debt issuance documents, you must upload them using the following request: ### Request Body Upload ENDPOINT /upload MÉTODO POST Response Body ```json { "document_key": "cfbc8469-89ea-4a80-9f64-ba7b1566c68b", "document_md5": "cd451103fa512frc98ce684d3896698c" } ``` :::caution Atenção Lembrar de salvar a **document_key**, chave essa necessária para a consulta do documento. ::: ### Exemplo de chamada Exemplo para upload de uma imagem a partir de uma URL. **Python** ```python import jwt import hashlib import requests from requests_toolbelt.multipart.encoder import MultipartEncoder import json from datetime import datetime BASE_URL = "https://api-auth.sandbox.qitech.app" API_KEY = "4c268c0a-53ff-429b-92b6-47ef98a6d89a" # Esta chave é um exemplo, por favor utilize sua própria chave CLIENT_PRIVATE_KEY = '''' -----BEGIN EC PRIVATE KEY----- MIHbAgEBBEHh1hIeOPE5XNNhn6bxRAmVswsPZ0wZCmzVvP8Tl/LZK9ofVmRVGzll srU1uezJEyHKYdOHrE2p52xUj+pHzjJvb6AHBgUrgQQAI6GBiQOBhgAEAAofUz1J hBSOyGHLsnV9Sz0DSWmhl7U+ljqbfa8PKVFWSV3w16I1v2zME5/UzUhHn1gWsjnv 7/ekcLLAQbvqMPNXAfjIhFXLAPzqbB9iCuVua1v0Vgy52rBemOWrJka/Ws2bnKR8 h1N1OxOYeYr6C2jqMygBLktKMAs+282CEiEb4bIv -----END EC PRIVATE KEY----- ''' # Esta chave é um exemplo, por favor utilize sua própria chave def get_document(url): try: response = requests.get(url) return response.content except Exception as error: print("Error fetching document:", error) raise def upload_document(array_buffer): endpoint = "/upload" method = "POST" timestamp = datetime.utcnow().strftime("%Y-%m-%dT%H:%M:%S.%f")[:-3] + "Z" md5_hash = hashlib.md5(array_buffer).hexdigest() jwt_header = { "typ": "JWT", "alg": "ES512", } jwt_body = { "payload_md5": md5_hash, "timestamp": timestamp, "method": method, "uri": endpoint, } encoded_header_token = jwt.encode(jwt_body, CLIENT_PRIVATE_KEY, algorithm="ES512", headers=jwt_header) signed_header = { "Authorization": encoded_header_token, "API-CLIENT-KEY": API_KEY, "Content-Type": "multipart/form-data", } url = f"{BASE_URL}{endpoint}" multipart_data = MultipartEncoder( fields={'file': ('image.jpeg', array_buffer, 'image/jpeg')} ) signed_header['Content-Type'] = multipart_data.content_type try: response = requests.post(url, headers=signed_header, data=multipart_data) response_data = response.json() document_key = response_data.get('document_key') print(f'Response data is: {response_data} and document_key is: {document_key}') return document_key except Exception as error: print('Error:', error) raise def main(): file_url = "{FILE_URL}" document_buffer = get_document(file_url) document_key = upload_document(document_buffer) print("document_key is", document_key) if __name__ == "__main__": main() ``` **Node.js** ```js const jwt = require('jsonwebtoken') const crypto = require('crypto') const axios = require('axios') const FormData = require('form-data') const fs = require('fs') const fetch = require('node-fetch') async function getDocument(url) { try { const response = await axios.get(url, { responseType: 'arraybuffer' }) return response.data } catch (error) { console.error('Error fetching document:', error) throw error } } async function uploadDocument(arrayBuffer) { const endpoint = '/upload' const method = 'POST' const timestamp = new Date().toISOString() const md5_hash = crypto.createHash('md5').update(arrayBuffer).digest('hex') const client_private_key = `-----BEGIN EC PRIVATE KEY----- MIHbAgEBBEHh1hIeOPE5XNNhn6bxRAmVswsPZ0wZCmzVvP8Tl/LZK9ofVmRVGzll srU1uezJEyHKYdOHrE2p52xUj+pHzjJvb6AHBgUrgQQAI6GBiQOBhgAEAAofUz1J hBSOyGHLsnV9Sz0DSWmhl7U+ljqbfa8PKVFWSV3w16I1v2zME5/UzUhHn1gWsjnv 7/ekcLLAQbvqMPNXAfjIhFXLAPzqbB9iCuVua1v0Vgy52rBemOWrJka/Ws2bnKR8 h1N1OxOYeYr6C2jqMygBLktKMAs+282CEiEb4bIv -----END EC PRIVATE KEY-----`; // Esta chave é um exemplo, por favor utilize sua própria chave const api_key = '4c268c0a-53ff-429b-92b6-47ef98a6d89a' // Esta chave é um exemplo, por favor utilize sua própria chave try { const jwt_header = { typ: 'JWT', alg: 'ES512', } const jwt_body = { payload_md5: md5_hash, timestamp: timestamp, method: method, uri: endpoint, } const encoded_header_token = jwt.sign(jwt_body, client_private_key, { algorithm: 'ES512', header: jwt_header, }) const signed_header = { AUTHORIZATION: encoded_header_token, 'API-CLIENT-KEY': api_key, 'Content-Type': 'multipart/form-data', } const url = `${base_url}${endpoint}` const formData = new FormData() formData.append('file', Buffer.from(arrayBuffer), { filename: 'image.jpeg', }) fetch(url, { method: 'POST', headers: signed_header, body: formData, }) .then(data => { console.log('Response data is: ' + data) return data.document_key }) .catch(error => { console.log('Error: ' + error) }) } catch (error) { console.error('Error:', error) } } async function main() { const fileUrl = '' const documentBuffer = await getDocument(fileUrl) const documentKey = await uploadDocument(documentBuffer) console.log('Document key is: ' + documentKey) } main() ``` - OBS: The example above uses the library [node-fetch](https://www.npmjs.com/package/node-fetch) to make the call, but you can use the library of your choice. The important thing is that the call must be made using the POST method, with the `Content-Type` header set to `multipart/form-data` and the body must be a FormData object with the key `file` and the value as the file binary to be sent. :::warning Aviso The 'Axios' library has a bug that causes FormData to be sent empty. The issue can be seen on the [GitHub repository](https://github.com/axios/axios/issues/5986). If this problem has not yet been resolved at the time of your integration, we suggest using the 'node-fetch' library to make this call. ::: ## 2. Debt Simulation ### Request Debt Simulation At QI Tech, we provide our clients with the ability to simulate the values of a credit operation before it is actually issued. The simulation follows the same pattern as the debt issuance request, but it is not necessary to provide the debtor’s registration and disbursement account details. The following endpoint is a simplified version of /debt_simulation, but much more optimized. It is used to calculate only one disbursement option. ENDPOINT /v2/credit_operation/simulation METHOD POST Request Body ```json { "credit_operation_type": "ccb", "disbursed_issue_amount": 2800, "disbursement_date": "2025-09-24", "first_due_date": "2025-10-24", "force_installments_on_workdays": true, "interest_type": "pre_price_days", "issuer_person_type": "natural", "monthly_interest_rate": 0.04488, "number_of_installments": 12, "principal_amortization_month_period": 1 } ``` ### Request Body Details | Field | Type | Description | Max. Char. | |---|--- |---|---| | **credit_operation_type*** | enum | **[Enumerator Credit Operation Type](#Enumerator-credit-operation-type)** - Type of credit agreement | - | | **disbursed_issue_amount*** | float | The value actually released to the borrower | - | | **disbursement_date*** | date | The specific date the loan funds are made available | - | | **first_due_date*** | date | Due date of the first installment | - | | **force_installments_on_workdays*** | boolean | _true_ - If true, all due dates will fall on business days | - | | **interest_type*** | enum | **[Enumerator Interest Type](#Enumerator-interest-type)** - Amortization method | - | | **issuer_person_type*** | enum | **[Enumerator Person Type](#Enumerator-person-type)** | - | | **monthly_interest_rate*** | float | Monthly interest rate | - | | **number_of_installments*** | int | Number of installments | - | | **principal_amortization_month_period*** | int | Period, in months, between installments | - | ### Response Debt Simulation STATUS 200 Response Body ```json { "additional_iof": 0.14, "annual_cet": 145.08, "assignment_amount": 36.21, "base_iof": 0.1, "cet": 7.76, "disbursed_amount": 35.9, "disbursement_date": "2024-09-06", "fees": [ { "amount": 0.0, "fee_amount": 0.0, "amount_type": "absolute", "fee_type": "tac", "type": "external" }, { "amount": 0.0, "fee_amount": 0.0, "amount_type": "absolute", "fee_type": "spread", "type": "external" }, { "amount": 0.2, "fee_amount": 0.07, "amount_type": "percentage", "fee_type": "spread", "type": "internal" } ], "first_due_date": "2024-09-25", "installments": [ { "due_date": "2024-09-25", "amount": 19.5, "due_principal": 36.14, "due_interest": 0.0, "has_interest": true, "period": 0.6129032258064516, "period_workdays": 0.6190476190476191, "calendar_days": 19, "workdays": 13, "installment_number": 1, "period_to_disbursement": 0.6129032258064516, "prefixed_amount": 1.58227236, "period_workdays_to_disbursement": 1.0, "calendar_days_to_disbursement": 19, "workdays_to_disbursement": 13, "tax_amount": 0.02791582, "principal_amortization_amount": 17.91772764 }, { "due_date": "2024-10-25", "amount": 19.5, "due_principal": 18.22227236, "due_interest": 0.0, "has_interest": true, "period": 1.0, "period_workdays": 1.0, "calendar_days": 30, "workdays": 22, "installment_number": 2, "period_to_disbursement": 1.6129032258064515, "prefixed_amount": 1.27772764, "period_workdays_to_disbursement": 2.0, "calendar_days_to_disbursement": 49, "workdays_to_disbursement": 35, "tax_amount": 0.07321709, "principal_amortization_amount": 18.22227236 } ], "interest_type": "pre_price_days", "issue_amount": 36.14, "prefixed_interest_rate": { "interest_base": "calendar_days", "annual_rate": 1.25219159, "daily_rate": 0.00225783, "monthly_rate": 0.07 }, "tax_configuration": { "additional_rate": 0.0038, "base_rate": 0.000082 }, "total_iof": 0.24 } ``` ### Response Body Details | Campo | Tipo | Description | Máx. Caract. | |-----------------------------------------|--------|-------------------------------------------------------------------------------------------------------------------------------|--------------| | **annual_cet** | float | Total effective cost expressed as a decimal per year | - | | **assignment_amount** | float | Acquisition value of the credit operation | - | | **cet** | float | Total effective cost expressed as a decimal per month. | - | | **fees** | object | **[Object Fees](#object-fees)** - List of QI Tech fees charged on the operation | - | | **disbursed_amount** | float | Amount disbursed in the credit operation | - | | **disbursement_date** | date | Disbursement date of the operation | - | | **installments** | list | **[Object Installments](#object-installments)** - Installments of the operation | - | | **interest_type** | enum | **[Enumerator Interest Type](#Enumerator-interest-type)** - Amortization method and interest calculation method | - | | **additional_iof** | float | Additional IOF amount | - | | **base_iof** | float | Base IOF amount | - | | **total_iof** | float | Total IOF amount | - | | **issue_amount** | float | Issue/nominal value of the credit operation | - | | **tax_configuration** | object | **[Object Tax Configuration](#object-tax-configuration)** - Rate iof values | - | | **first_due_date** | date | Due date of the first installment | - | | **prefixed_interest_rate** | object | **[Object Interest Rate](#object-interest-rate)** - Nominal interest rate | - | ### Object Fees | Campo | Tipo | Description | Máx. Caract. | |-----------------|-------|-----------------------------------------------------------------------------------------------------|--------------| | **amount** | float | Fee amount (in percentage or absolute value, depending on the value provided in the amount_type field)| - | | **amount_type** | enum | **[Enumerators amount_type](#Enumerator-amount-type)** - Fee value unit | - | | **fee_amount** | float | Absolute value of the fee charged in the operation | - | | **fee_type** | enum | **[Enumerator Fee Type](#Enumerator-fee-type)** - Type of fee charged in the operation | - | | **type** | enum | **[Enumerator Origin Type](#Enumerator-origin-type)** - Source of the fee charged in the operation | - | ### Object Installments | Campo | Tipo | Description | Máx. Caract. | |-----------------------------------|---------|--------------------------------------------------------------------------------|--------------| | **calendar_days** | int | Number of calendar days between installments | - | | **due_date** | date | Installment due date in calendar days | - | | **due_principal** | float | Remaining principal on the installment due date before its payment | - | | **has_interest** | boolean | _true_ - If true, interest applies to the installment | - | | **installment_number** | int | Installment number | - | | **prefixed_amount** | float | Fixed interest amount paid on the installment | - | | **principal_amortization_amount** | float | Principal amount paid on the installment | - | | **tax_amount** | float | Base IOF amount of installment | - | | **amount** | float | Installment total value | - | | **due_interest** | float | Remaining interest after the installment due date before its payment | - | | **period** | float | Installment period | - | | **period_workdays** | float | Installment period in business days | - | | **period_to_disbursement** | float | Period until disbursement | - | | **period_workdays_to_disbursement**| float | Business days until disbursement | - | | **calendar_days_to_disbursement** | int | Calendar days to disbursement | - | | **workdays** | int | Business days between installments | - | | **workdays_to_disbursement** | int | Business days until disbursement | - | ### Object Interest Rate | Campo | Description | Máx. Caract. | |-------------------|---------------------------------------------------------------------------------------|--------------| | **annual_rate** | Annual fixed/floating interest rate expressed as a decimal | - | | **daily_rate** | Daily fixed/floating interest rate expressed as a decimal | - | | **interest_base** | **[Enumerator Interest Base](#Enumerator-interest-base)** - Interest calculation basis | - | | **monthly_rate** | Monthly fixed/floating interest rate expressed as a decimal | - | ### Object Tax Configuration | Campo | Description | Máx. Caract. | |-----------------------|---------------------------------------------------------------------------------------|--------------| | **base_rate** | Base IOF rate value | - | | **additional_rate** | Additional IOF rate value | - | ### Enumeratores #### Enumerator _Person Type_ | Enumerator | Description | |------------------------|-----------------------| | **legal** | Legal person | | **natural** | Natural person | #### Enumerator _Account Type_ | Enumerator | Description | |------------------------|-----------------------| | **checking_account** | Checking account | | **deposit_account** | Deposit account | | **guaranteed_account** | Guaranteed account | | **investment_account** | Investment account | | **payment_account** | Payment account | | **saving_account** | Saving account | | **salary_account** | Salary account | #### Enumerator _Amount Type_ | Enumerator | Description | |------------------------|-----------------------| | **absolute** | Absolute value | | **percentage** | percentage value | #### Enumerator _Interest Type_ | Enumerator | Description | |----------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | **pre_price_days** | Price amortization method (equal installments) with daily fixed-rate interest calculation | | **pre_price** | Price amortization method (equal installments) with fixed-rate interest calculation over 30-day periods | | **pre_sac** | Constant principal amortization (SAC system) with interest calculated daily on a fixed-rate basis | | **post_sac** | Constant principal amortization (SAC system) with daily interest calculation based on a fixed rate plus a floating-rate index (e.g., CDI, IPCA, or IGPM) | | **post_price** | Price amortization method (equal installments) with interest calculated over 30-day periods based on a fixed rate plus a floating-rate index (e.g., CDI, IPCA, or IGPM) | | **post_price_days** | Price amortization method (equal installments) with daily interest calculation based on a fixed rate plus a floating-rate index (e.g., CDI, IPCA, or IGPM) | #### Enumerator _Credit Operation Type_ | Enumerator | Description | |---------------|--------------------------------| | **ccb** | CCB | | **cce** | CCE | | **cci** | CCI | | **nce** | NCE | #### Enumerator _Interest Base_ | Enumerator | Description | |-----------------------|---------------------------------------------------------------------------| | **workdays** | Interest calculation basis in business days, assuming a 252-day year | | **calendar_days** | Interest calculation basis in calendar days, assuming a 360-day year | | **calendar_days_365** | Interest calculation basis in calendar days, assuming a 365-day year | #### Enumerator _Fee Type_ Each fee type must be previously enabled and configured by QI Tech | Enumerator | Description | |-----------------------|----------------------------------------------------------------------------| | **tac** | Registration Fee | | **spread** | Premium included in the credit operation's acquisition value | | **warranty_analysis** | Collateral analysis fee | | **ted_fee** | TED transfer fee | | **spread_ted_fee** | Premium on the TED transfer fee | #### Enumerator _Origin Type_ Each fee type must be previously enabled and configured by QI Tech | Enumerator | Description | |-----------------------|----------------------------------------------------------------------------| | **internal** | Internal fee | | **external** | External fee | ## 3. Debt Issuance for Individuals This endpoint issues the debt and processes the contract signature via opt-in. Immediately after issuance, the debt is automatically disbursed. It is not necessary to pre-register the borrower; simply provide the registration details at the time of the debt request. ### Request ENDPOINT /signed_debt METHOD POST Request Body ```json { "simplified": true, "additional_data": { "contract": { "contract_number": "TIK11267101212", "signed": true, "signatures": [ { "signer": { "name": "Alan Mathison Turing", "phone": { "number": "912345678", "area_code": "11", "country_code": "055" }, "email": "alan.turing@email.com", "document_number": "96969879003" }, "signature": { "ip_address": "168.211.22.84", "timestamp": "27-10-2025 11:07:15", "signature_file": { "file_url": "http://qitech.com.br/signature.pdf", "file_type": "pdf" }, "geolocation": { "long": "", "lat": "" }, "fingerprint_device": null } } ] } }, "financial": { "number_of_installments": 3, "credit_operation_type": "ccb", "interest_type": "pre_price_days", "annual_interest_rate": 3.81790482, "disbursed_amount": 200, "fine_configuration": { "contract_fine_rate": 0.02, "monthly_rate": 0.15, "interest_base": "calendar_days" }, "interest_grace_period": 0, "rebates": null, "issue_date": "2025-10-27", "disbursement_date": "2025-10-27", "first_due_date": "2025-11-27", "principal_grace_period": 0 }, "disbursement_bank_accounts": [ { "account_digit": "5", "document_number": "32402502000135", "bank_code": "329", "account_number": "00002", "percentage_receivable": 100, "branch_number": "0001", "name": "CONTA LOJISTA" } ], "purchaser_document_number": "32402502000135", "borrower": { "email": "alan.turing@email.com", "document_identification": "494598fd-c226-4332-a500-591ae3884673", "document_identification_back": "494598fd-c226-4332-a500-591ae3884673", "birth_date": "1990-11-20", "person_type": "natural", "profession": "Public server", "individual_document_number": "96969879003", "address": { "city": "São Paulo", "neighborhood": "CENTRO", "street": "Avenida Feliz", "complement": "AP 801", "postal_code": "49026100", "state": "SP", "number": "1000" }, "phone": { "country_code": "055", "number": "912345678", "area_code": "11" }, "mother_name": "MARIA TURING", "marital_status": "married", "nationality": "", "document_identification_number": "96969879003", "name": "Alan Mathison Turing" } } ``` ### Response The response to this debt request will return the payment plan as well as a **DEBT-KEY**, which is the identifier of the debt in QI SCD. STATUS 201 Response Body ```json { "webhook_type": "debt", "key": "1ebd4a90-2721-4c39-a399-427fa16bca65", "status": "waiting_signature", "event_datetime": "2025-10-27 17:09:31", "data": { "borrower": { "name": "Alan Mathison Turing", "document_number": "96969879003", "related_party_key": "d6353266-30bc-4ab1-964e-2c7a643d8ba2" }, "contract": { "document_key": "c8b191cb-7b90-4e37-9280-397a597babc1", "number": "TIK11267101212", "urls": [ "https://storage.googleapis.com/sandbox-doc-api/documents/c8b191cb-7b90-4e37-9280-397a597babc1/RAFAELAEBENJAMINFINANCEIRALTDA-ALAN_MATHISON_TURING-CCB-TIK11267101212-20251027170925.pdf" ], "signature_information": [ { "signer_name": "Alan Mathison Turing", "signer_document_number": "96969879003", "signer_role": "issuer", "signer_email": "alan.turing@email.com", "signer_external_key": null, "signature_url": null } ] }, "requester_identifier_key": "1ebd4a90-2721-4c39-a399-427fa16bca65", "iof_charge_method": "financed", "collaterals": [], "contract_fees": [ { "fee_type": "spread", "fee_amount": 1.01 }, { "fee_type": "spread_ted_fee", "fee_amount": 0.5 } ], "external_contract_fees": [], "external_contract_fee_amount": 0, "net_external_contract_fee_amount": 0, "contract_fee_amount": 1.51, "issue_amount": 201.84, "assignment_amount": 203.35, "cet": "14,7500%", "annual_cet": "421,3334%", "number_of_installments": 3, "base_iof": 1.06, "additional_iof": 0.78, "total_iof": 1.84, "ipoc_code": "324025020203196969879003TIK11267101212", "prefixed_interest_rate": { "annual_rate": 3.81790482, "created_at": "2025-10-27T17:09:25", "daily_rate": 0.0043771607, "interest_base": "calendar_days", "monthly_rate": 0.14 }, "installments": [ { "accrual_reference_date": null, "additional_costs": [], "advanced_paid_amount": 0, "bank_slip_key": null, "business_due_date": "2025-11-28", "calendar_days": 31, "digitable_line": null, "due_date": "2025-11-27", "due_interest": 0, "due_principal": 201.84, "fine_amount": null, "has_interest": true, "installment_history": [], "installment_key": "e25fb146-0a61-4319-a722-d01b2213d0f9", "installment_number": 1, "installment_payment": [], "installment_status": "created", "installment_type": "principal", "original_due_principal": 201.84, "original_pre_fixed_amount": 29.26477451, "original_principal_amortization_amount": 58.16522549, "original_total_amount": 87.43, "paid_amount": 0, "paid_at": null, "post_fixed_amount": 0, "pre_fixed_amount": 29.26477451, "principal_amortization_amount": 58.16522549, "qr_code_key": null, "qr_code_url": null, "renegotiation_proposal_key": null, "tax_amount": 0.147856, "total_accrual_amount": null, "total_amount": 87.43, "total_paid_amount": 0, "workdays": 22 }, { "accrual_reference_date": null, "additional_costs": [], "advanced_paid_amount": 0, "bank_slip_key": null, "business_due_date": "2025-12-30", "calendar_days": 30, "digitable_line": null, "due_date": "2025-12-27", "due_interest": 0, "due_principal": 143.67477451, "fine_amount": null, "has_interest": true, "installment_history": [], "installment_key": "2557de2b-6df1-4a8a-b46a-59206ece157f", "installment_number": 2, "installment_payment": [], "installment_status": "created", "installment_type": "principal", "original_due_principal": 143.67477451, "original_pre_fixed_amount": 20.11446867, "original_principal_amortization_amount": 67.31553133, "original_total_amount": 87.43, "paid_amount": 0, "paid_at": null, "post_fixed_amount": 0, "pre_fixed_amount": 20.11446867, "principal_amortization_amount": 67.31553133, "qr_code_key": null, "qr_code_url": null, "renegotiation_proposal_key": null, "tax_amount": 0.33671229, "total_accrual_amount": null, "total_amount": 87.43, "total_paid_amount": 0, "workdays": 20 }, { "accrual_reference_date": null, "additional_costs": [], "advanced_paid_amount": 0, "bank_slip_key": null, "business_due_date": "2026-01-28", "calendar_days": 31, "digitable_line": null, "due_date": "2026-01-27", "due_interest": 0, "due_principal": 76.35924318, "fine_amount": null, "has_interest": true, "installment_history": [], "installment_key": "cc503d1d-6387-4a1f-bd78-62b248d02ec8", "installment_number": 3, "installment_payment": [], "installment_status": "created", "installment_type": "principal", "original_due_principal": 76.35924318, "original_pre_fixed_amount": 11.07075682, "original_principal_amortization_amount": 76.35924318, "original_total_amount": 87.43, "paid_amount": 0, "paid_at": null, "post_fixed_amount": 0, "pre_fixed_amount": 11.07075682, "principal_amortization_amount": 76.35924318, "qr_code_key": null, "qr_code_url": null, "renegotiation_proposal_key": null, "tax_amount": 0.57605413, "total_accrual_amount": null, "total_amount": 87.43, "total_paid_amount": 0, "workdays": 21 } ], "total_pre_fixed_amount": 60.45 } } ``` :::info **Main fields definitions*** For any doubts, feel free to consult QI Tech's **[documentation](https://docs.qitech.com.br/en/documentation/emissao_de_divida/emissao/emissao_de_divida_pf/index.html)** with the explanation of every field of Debt insuance API. ::: ## 4. Webhooks After the successful response, you will receive a webhook with the signed CCB and a webhook indicating the disbursement's success or failure. ### Signature webhook Response Body ```json { "webhook": { "key": "1ebd4a90-2721-4c39-a399-427fa16bca65", "status": "signature_finished", "webhook_type": "debt", "event_datetime": "2025-10-27 17:09:33", "signed_contract_url": "https://storage.googleapis.com/sandbox-doc-api/documents/c8b191cb-7b90-4e37-9280-397a597babc1/RAFAELAEBENJAMINFINANCEIRALTDA-ALAN_MATHISON_TURING-CCB-TIK11267101212-20251027170925_signed.pdf" } } ``` ### Disbursement webhook Response Body ```json { "webhook": { "key": "1ebd4a90-2721-4c39-a399-427fa16bca65", "data": { "installments": [ { "due_date": "2025-11-27", "total_amount": 87.43, "installment_key": "e25fb146-0a61-4319-a722-d01b2213d0f9", "pre_fixed_amount": 29.26477451, "installment_number": 1, "principal_amortization_amount": 58.16522549 }, { "due_date": "2025-12-27", "total_amount": 87.43, "installment_key": "2557de2b-6df1-4a8a-b46a-59206ece157f", "pre_fixed_amount": 20.11446867, "installment_number": 2, "principal_amortization_amount": 67.31553133 }, { "due_date": "2026-01-27", "total_amount": 87.43, "installment_key": "cc503d1d-6387-4a1f-bd78-62b248d02ec8", "pre_fixed_amount": 11.07075682, "installment_number": 3, "principal_amortization_amount": 76.35924318 } ], "ted_receipt_list": [], "requester_identifier_key": null }, "status": "disbursed", "webhook_type": "debt", "event_datetime": "2025-10-27 17:10:21" } } ``` If the debt fails to disburse, or is returned, you will receive a cancellation webhook. ### Cancelation webhook Response Body ```json { "webhook_type": "debt", "key":"1ebd4a90-2721-4c39-a399-427fa16bca65", "event_datetime": "2025-10-27 16:38:59", "data": { "cancel_reason": "Operacao cancelada manualmente", "cancel_reason_enumerator": "manual" }, "status":"canceled " } ``` ****Cancelation reasons**** | cancel_reason_enumerator | Description | |---|---| |disbursing_error|Operation canceled due to an error during disbursement. |waiting_signature |Operation canceled due to missing signature. |pix_max_retry|Operation canceled because the receiving bank could not process the disbursement. |manual|Operation canceled manually. |agencia_conta_invalida|Invalid agency or recipient account number. |invalid_account|The destination account number is nonexistent or invalid. |invalid_document_number|The CPF/CNPJ of the destination account is incorrect. |unsupported_transaction|The destination account does not support this type of transaction. |invalid_ispb|The ISPB number is invalid or nonexistent. |rejected_payment|Payment order was rejected by the receiving bank. | refund_after_payee_request | Refund requested by the payee | | invalid_account | The destination account number is nonexistent or invalid. | | invalid_document_number | The CPF/CNPJ of the destination account is incorrect. | | rejected_payment | Payment rejected by the receiving bank. | | blocked_account | The destination account is blocked. | | unsupported_transaction | The destination account does not support this type of transaction. | | amount_too_great | Payment/refund amount exceeds the limit for the credited destination account. | | invalid_ispb | The ISPB number is invalid or nonexistent. | | receiver_error | Transaction interrupted due to error on the receiver's PSP. | | closed_account | The destination account is closed. | | disbursing_hour_closed | Disbursement occurred outside of the allowed time frame. | | unregistered_pix_key | The Pix key is not being used. | | manual | Operation manually canceled. | | spi_timeout | Timeout control in SPI. | ## 5. Debt installments If QI Tech is the collection agent for the operation, there is a specific API to retrieve information about the installments. The statuses that can be configured are: - webhook_type: installment.status_change - Webhook status: opened, paid, waiting_payment, paid_early, paid_partial, overdue, paid_partial_overdue and paid_overdue ### Examples ****Paid Installment**** ```json { "webhook": { "key": "1ebd4a90-2721-4c39-a399-427fa16bca65", "data": { "status": "paid", "installment": { "events": [ { "amount": null, "created_at": null, "event_date": "2025-10-27T17:10:21", "old_due_date": null, "installment_event_type": { "enumerator": "open", "translation_path": "co.InstallmentEventType.open" }, "installment_old_status": { "enumerator": "created", "translation_path": "co.InstallmentStatus.created" } }, { "amount": 87.43, "created_at": "2025-10-27T17:10:21", "event_date": "2025-10-27T17:10:21", "old_due_date": null, "installment_event_type": { "enumerator": "payment", "translation_path": "co.InstallmentEventType.payment" }, "installment_old_status": { "enumerator": "opened", "translation_path": "co.InstallmentStatus.opened" } } ], "paid_at": "2025-10-27T17:10:21", "due_date": "2026-01-27", "workdays": 21, "created_at": "2025-10-27T17:09:25", "tax_amount": 0.57605413, "updated_at": "2025-10-27T17:10:21", "fine_amount": null, "paid_amount": 87.43, "qr_code_key": null, "qr_code_url": null, "due_interest": 0.0, "has_interest": true, "payment_type": { "enumerator": "bankslip", "translation_path": "co.PaymentType.bankslip" }, "total_amount": 87.43, "bank_slip_key": null, "calendar_days": 31, "due_principal": 76.35924318, "digitable_line": null, "installment_key": "cc503d1d-6387-4a1f-bd78-62b248d02ec8", "additional_costs": [], "installment_type": { "enumerator": "principal", "translation_path": "co.InstallmentType.principal" }, "pre_fixed_amount": 11.07075682, "business_due_date": "2026-01-28", "cetip_settlements": [], "post_fixed_amount": 0.0, "total_paid_amount": 0.0, "installment_number": 3, "installment_status": { "enumerator": "opened", "translation_path": "co.InstallmentStatus.opened" }, "installment_history": [], "installment_payment": [], "advanced_paid_amount": 0.0, "total_accrual_amount": null, "original_total_amount": 87.43, "accrual_reference_date": null, "original_due_principal": 76.35924318, "original_pre_fixed_amount": 11.07075682, "renegotiation_proposal_key": null, "principal_amortization_amount": 76.35924318, "original_principal_amortization_amount": 76.35924318 }, "is_finished": false }, "webhook_type": "installment.status_change" } } ``` ****Bank slips data**** ```json { "key": "1ebd4a90-2721-4c39-a399-427fa16bca65", "data": { "status": "update", "installments": [ { "due_date": "2025-11-27", "qr_code_key": "eeb4f5a6-6cba-4901-8113-21c7261b54ac", "qr_code_url": "00020126930014br.gov.bcb.pix2571qrcode-h.sandbox.qitech.app/bacen/cobv/eeb4f5a66cba4901811321c7261b54ac5204000053039865802BR5925QISOCIEDADEDECREDITODIRET6008SaoPaulo61080145200062070503***6304D300", "total_amount": 87.43, "bank_slip_key": "524440c0-302b-4553-8211-5cf012f2e718", "digitable_line": "32990001031000700326159000000204112780000008743", "installment_key": "e25fb146-0a61-4319-a722-d01b2213d0f9", "pre_fixed_amount": 29.26477451, "principal_amortization_amount": 58.16522549 }, { "due_date": "2025-12-27", "qr_code_key": "98781ab0-318a-43c4-9ce6-fdc22514c540", "qr_code_url": "00020126930014br.gov.bcb.pix2571qrcode-h.sandbox.qitech.app/bacen/cobv/98781ab0318a43c49ce6fdc22514c5405204000053039865802BR5925QISOCIEDADEDECREDITODIRET6008SaoPaulo61080145200062070503***63040687", "total_amount": 87.43, "bank_slip_key": "ece5355a-4b51-48af-aa4b-f074b93c9fef", "digitable_line": "32990001031000700326160000000202613080000008743", "installment_key": "2557de2b-6df1-4a8a-b46a-59206ece157f", "pre_fixed_amount": 20.11446867, "principal_amortization_amount": 67.31553133 }, { "due_date": "2026-01-27", "qr_code_key": "289792ad-3e5a-4308-8e3d-7b75afe0fea5", "qr_code_url": "00020126930014br.gov.bcb.pix2571qrcode-h.sandbox.qitech.app/bacen/cobv/289792ad3e5a43088e3d7b75afe0fea55204000053039865802BR5925QISOCIEDADEDECREDITODIRET6008SaoPaulo61080145200062070503***630443CC", "total_amount": 87.43, "bank_slip_key": "09888b40-6844-4c8c-a474-f22a94e463a9", "digitable_line": "32990001031000700326161000000200313390000008743", "installment_key": "cc503d1d-6387-4a1f-bd78-62b248d02ec8", "pre_fixed_amount": 11.07075682, "principal_amortization_amount": 76.35924318 } ] }, "webhook_type": "installment.status_change" } ``` Furthermore, there is an option to retrieve the duplicate copy of the installment: ENDPOINT /bank_slip/2-way/ BANK_SLIP_KEY* METHOD PATCH `*BANK_SLIP_KEY (string): Payment slip identification key.` ****Duplicate Copy**** ```json { "key": "1150f778-b479-42ab-b76b-c6a76cdfcf50", "data": { "status": "update", "installments": [ { "due_date": "2024-12-02", "qr_code_key": "56da9761-a425-488d-a65c-e54680346533", "qr_code_url": "00020126830014br.gov.bcb.pix2561qrcode.qitech.app/bacen/cobv/56da9761a425488da65ce543047339", "total_amount": 16.2, "bank_slip_key": "27e70d92-caee-4fe2-92f3-f967fd26ce70", "digitable_line": "32990001031000000000908001075103782160000759600", "installment_key": "e80a53c6-080a-48d6-ba12-dd01459650ed", "pre_fixed_amount": 16.2, "principal_amortization_amount": 0 }, { "due_date": "2025-03-05", "qr_code_key": "fbea5390-3a77-4432-b8f3-d174aff9c048", "qr_code_url": "00020126830014br.gov.bcb.pix2561qrcode.qitech.app/bacen/cobv/56da9761a425488da65ce543047339", "total_amount": 84.12, "bank_slip_key": "82f5741b-9cf6-4a9c-b9b4-8fcc29a94969", "digitable_line": "32990001031000000000908001075103782160000759600", "installment_key": "c8c43838-2ff0-4d4e-af1e-35ac20255030", "pre_fixed_amount": 47.5953627, "principal_amortization_amount": 36.5246373 } ] }, "webhook_type": "installment.status_change" } ``` ## 6. Debt inquiry You can also query the debt later to retrieve information or track its status: ENDPOINT /v2/credit_operation/ CREDIT-OPERATION-KEY MÉTODO GET ### Path params | Campo | Tipo | Descrição | Caracteres | |---|---|---|---| | `credit_operation_key` * | string | Chave da operação de crédito. | UUID | ### Response STATUS 200 Response Body ```json { "credit_operation_key": "1ebd4a90-2721-4c39-a399-427fa16bca65", "issue_amount": 201.84, "origin_key": "1ebd4a90-2721-4c39-a399-427fa16bca65", "total_iof": 1.84, "disbursement_start_date": "2025-10-27", "disbursement_end_date": "2025-10-27", "issue_date": "2025-10-27", "requester_identifier_key": "1ebd4a90-2721-4c39-a399-427fa16bca65", "installments": [ { "business_due_date": "2025-11-28", "due_date": "2025-11-27", "calendar_days": 31, "due_interest": 0, "due_principal": 201.84, "fine_amount": 0, "has_interest": true, "post_fixed_amount": 0, "pre_fixed_amount": 29.26, "principal_amortization_amount": 58.17, "tax_amount": 0.15, "total_amount": 87.43, "workdays": 22, "accrual_reference_date": null, "advanced_paid_amount": 0, "bank_slip_key": "524440c0-302b-4553-8211-5cf012f2e718", "digitable_line": "32990001031000700326159000000204112780000008743", "installment_key": "e25fb146-0a61-4319-a722-d01b2213d0f9", "installment_status": "opened", "installment_type": "principal", "original_due_principal": 201.84, "original_pre_fixed_amount": 29.26, "original_principal_amortization_amount": 58.17, "paid_amount": 0, "original_total_amount": 87.43, "qr_code_key": "eeb4f5a6-6cba-4901-8113-21c7261b54ac", "qr_code_url": "00020126930014br.gov.bcb.pix2571qrcode-h.sandbox.qitech.app/bacen/cobv/eeb4f5a66cba4901811321c7261b54ac5204000053039865802BR5925QISOCIEDADEDECREDITODIRET6008SaoPaulo61080145200062070503***6304D300", "renegotiation_proposal_key": null, "total_accrual_amount": 0, "total_paid_amount": 0, "installment_number": 1, "paid_at": null, "updated_at": "2025-10-27T17:10:21", "principal_amortization_payment_amount": 0, "prefixed_interest_payment_amount": 0 }, { "business_due_date": "2025-12-30", "due_date": "2025-12-27", "calendar_days": 30, "due_interest": 0, "due_principal": 143.67477451, "fine_amount": 0, "has_interest": true, "post_fixed_amount": 0, "pre_fixed_amount": 20.11, "principal_amortization_amount": 67.32, "tax_amount": 0.34, "total_amount": 87.43, "workdays": 20, "accrual_reference_date": null, "advanced_paid_amount": 0, "bank_slip_key": "ece5355a-4b51-48af-aa4b-f074b93c9fef", "digitable_line": "32990001031000700326160000000202613080000008743", "installment_key": "2557de2b-6df1-4a8a-b46a-59206ece157f", "installment_status": "opened", "installment_type": "principal", "original_due_principal": 143.67, "original_pre_fixed_amount": 20.11, "original_principal_amortization_amount": 67.32, "paid_amount": 0, "original_total_amount": 87.43, "qr_code_key": "98781ab0-318a-43c4-9ce6-fdc22514c540", "qr_code_url": "00020126930014br.gov.bcb.pix2571qrcode-h.sandbox.qitech.app/bacen/cobv/98781ab0318a43c49ce6fdc22514c5405204000053039865802BR5925QISOCIEDADEDECREDITODIRET6008SaoPaulo61080145200062070503***63040687", "renegotiation_proposal_key": null, "total_accrual_amount": 0, "total_paid_amount": 0, "installment_number": 2, "paid_at": null, "updated_at": "2025-10-27T17:10:21", "principal_amortization_payment_amount": 0, "prefixed_interest_payment_amount": 0 }, { "business_due_date": "2026-01-28", "due_date": "2026-01-27", "calendar_days": 31, "due_interest": 0, "due_principal": 76.35924318, "fine_amount": 0, "has_interest": true, "post_fixed_amount": 0, "pre_fixed_amount": 11.07, "principal_amortization_amount": 76.36, "tax_amount": 0.58, "total_amount": 87.43, "workdays": 21, "accrual_reference_date": null, "advanced_paid_amount": 0, "bank_slip_key": "09888b40-6844-4c8c-a474-f22a94e463a9", "digitable_line": "32990001031000700326161000000200313390000008743", "installment_key": "cc503d1d-6387-4a1f-bd78-62b248d02ec8", "installment_status": "opened", "installment_type": "principal", "original_due_principal": 76.36, "original_pre_fixed_amount": 11.07, "original_principal_amortization_amount": 76.36, "paid_amount": 0, "original_total_amount": 87.43, "qr_code_key": "289792ad-3e5a-4308-8e3d-7b75afe0fea5", "qr_code_url": "00020126930014br.gov.bcb.pix2571qrcode-h.sandbox.qitech.app/bacen/cobv/289792ad3e5a43088e3d7b75afe0fea55204000053039865802BR5925QISOCIEDADEDECREDITODIRET6008SaoPaulo61080145200062070503***630443CC", "renegotiation_proposal_key": null, "total_accrual_amount": 0, "total_paid_amount": 0, "installment_number": 3, "paid_at": null, "updated_at": "2025-10-27T17:10:21", "principal_amortization_payment_amount": 0, "prefixed_interest_payment_amount": 0 } ], "first_due_date": "2025-11-27", "requester_key": "6ca83592-ce8c-42f5-ac0d-5ce182dbe794", "original_total_iof": null, "contract_number": "TIK11267101212", "credit_operation_status_enumerator": "opened", "operation_type_enumerator": "structured_operation", "disbursement_date": "2025-10-27", "issuer_name": "Alan Mathison Turing", "issuer_document_number": "96969879003", "external_contract_fees": [], "cet": 14.75, "annual_cet": 421.33, "final_disbursement_amount": 200, "number_of_installments": 3, "disbursement_issue_amount": 200, "prefixed_interest_rate": { "annual_rate": 3.81790482, "daily_rate": 0.0043771607, "interest_base": { "enumerator": "calendar_days", "year_days": 360 }, "monthly_rate": 0.14 }, "fine_configuration": { "contract_fine_rate": 0.02, "fine_delay_rate": { "annual_rate": 4.35025011, "daily_rate": 0.0046696, "interest_base": { "enumerator": "calendar_days", "year_days": 360 }, "monthly_rate": 0.15 } }, "attached_documents": [ { "document_key": "494598fd-c226-4332-a500-591ae3884673", "document_url": "https://storage.googleapis.com/sandbox-doc-api/documents/494598fd-c226-4332-a500-591ae3884673/3d684e68e7df4e557d0480d98e26be92.jpg", "signature_url": null, "document_type": "document_identification", "signature_required": false, "signed": false }, { "document_key": "494598fd-c226-4332-a500-591ae3884673", "document_url": "https://storage.googleapis.com/sandbox-doc-api/documents/494598fd-c226-4332-a500-591ae3884673/3d684e68e7df4e557d0480d98e26be92.jpg", "signature_url": null, "document_type": "document_identification_back", "signature_required": false, "signed": false }, { "document_key": "c8b191cb-7b90-4e37-9280-397a597babc1", "document_url": "https://storage.googleapis.com/sandbox-doc-api/documents/c8b191cb-7b90-4e37-9280-397a597babc1/RAFAELAEBENJAMINFINANCEIRALTDA-ALAN_MATHISON_TURING-CCB-TIK11267101212-20251027170925.pdf", "signature_url": "https://storage.googleapis.com/sandbox-doc-api/documents/c8b191cb-7b90-4e37-9280-397a597babc1/RAFAELAEBENJAMINFINANCEIRALTDA-ALAN_MATHISON_TURING-CCB-TIK11267101212-20251027170925_signed.pdf", "document_type": "ccb_pre_price_days", "signature_required": true, "signed": true } ] } ``` STATUS 400 Response Body ```json { "data": "{\"title\": \"Bad Request\", \"description\": \"Invalid request body.\", \"translation\": \"Corpo da requisição inválido.\", \"extra_fields\": {}, \"code\": \"LEG000069\"}" } ``` --- # Inquiry - BNPL Issuance URL: /en/documentation/manual_bnpl_full/emissao/consulta # Inquiry - BNPL Issuance ## Summary You can query the debt at any time to retrieve information or track its current status. ## Query Credit Operation There are two ways to query an operation: - By `credit_operation_key` (DEBT-KEY) - By `requester_identifier_key` (identifier key sent during issuance) ### By Credit Operation Key ENDPOINT /v2/credit_operation/ CREDIT-OPERATION-KEY METHOD GET Test in Playground | Field | Type | Description | Max. Char. | |---|---|---|---| | `credit_operation_key`* | string | Credit operation key (DEBT-KEY) | UUID | ### By Requester Identifier Key ENDPOINT /v2/credit_operation/requester_identifier_key/ REQUESTER-IDENTIFIER-KEY METHOD GET | Field | Type | Description | Max. Char. | |---|---|---|---| | `requester_identifier_key`* | string | Identifier key sent during issuance | UUID | ### Response STATUS 200 Response Body ```json { "credit_operation_key": "72760166-4ddf-41fb-8a8c-605f8f4fc35c", "issue_amount": 1007.62, "origin_key": "72760166-4ddf-41fb-8a8c-605f8f4fc35c", "total_iof": 7.62, "assigned_at": null, "disbursement_start_date": "2026-04-07", "disbursement_end_date": "2026-04-07", "issue_date": "2026-04-07", "requester_identifier_key": "d1905ef5-19df-4183-bf0e-802b8229933c", "installments": [ { "business_due_date": "2026-05-07", "due_date": "2026-05-07", "calendar_days": 30, "due_interest": 0, "due_principal": 1007.62, "fine_amount": 0, "has_interest": true, "post_fixed_amount": 0, "pre_fixed_amount": 52.4, "principal_amortization_amount": 491.49, "tax_amount": 1.21, "total_amount": 543.89, "workdays": 20, "accrual_reference_date": null, "advanced_paid_amount": 0, "bank_slip_key": null, "digitable_line": null, "installment_key": "1dea396f-beb1-4df3-9822-35800b4c095a", "installment_status": "opened", "installment_type": "principal", "original_due_principal": 1007.62, "original_pre_fixed_amount": 52.4, "original_principal_amortization_amount": 491.49, "paid_amount": 0, "original_total_amount": 543.89, "qr_code_key": null, "qr_code_url": null, "renegotiation_proposal_key": null, "total_accrual_amount": 0, "total_paid_amount": 0, "installment_number": 1, "paid_at": null, "updated_at": "2026-04-07T23:59:27", "principal_amortization_payment_amount": 0, "prefixed_interest_payment_amount": 0 }, { "business_due_date": "2026-06-08", "due_date": "2026-06-07", "calendar_days": 31, "due_interest": 0, "due_principal": 516.1296159, "fine_amount": 0, "has_interest": true, "post_fixed_amount": 0, "pre_fixed_amount": 27.76, "principal_amortization_amount": 516.13, "tax_amount": 2.58, "total_amount": 543.89, "workdays": 20, "accrual_reference_date": null, "advanced_paid_amount": 0, "bank_slip_key": null, "digitable_line": null, "installment_key": "370e73d1-55d8-431e-9b22-d08fb8297999", "installment_status": "opened", "installment_type": "principal", "original_due_principal": 516.13, "original_pre_fixed_amount": 27.76, "original_principal_amortization_amount": 516.13, "paid_amount": 0, "original_total_amount": 543.89, "qr_code_key": null, "qr_code_url": null, "renegotiation_proposal_key": null, "total_accrual_amount": 0, "total_paid_amount": 0, "installment_number": 2, "paid_at": null, "updated_at": "2026-04-07T23:59:27", "principal_amortization_payment_amount": 0, "prefixed_interest_payment_amount": 0 } ], "first_due_date": "2026-05-07", "requester_key": "78287247-947d-4730-9bd1-7efb068175b6", "contract_number": "DWF1761222116", "credit_operation_status_enumerator": "opened", "operation_type_enumerator": "structured_operation", "disbursement_date": "2026-04-07", "issuer_name": "Dante Ferrarini", "issuer_document_number": "31057466093", "external_contract_fees": [ { "amount_type": "absolute", "fee_amount": 0, "tax_amount": 0, "irrf_amount": 0, "amount": 0, "pis_amount": 0, "amount_released": 0, "fee_type": "tac", "cofins_amount": 0, "csll_amount": 0, "description": null, "net_fee_amount": 0, "rebate_account": null } ], "cet": 5.82, "annual_cet": 97.05, "final_disbursement_amount": 1000, "number_of_installments": 2, "disbursement_issue_amount": 1000, "prefixed_interest_rate": { "annual_rate": 0.8373372409, "daily_rate": 0.0016911989, "interest_base": { "enumerator": "calendar_days", "year_days": 360 }, "monthly_rate": 0.052 }, "fine_configuration": { "contract_fine_rate": 0.02, "fine_delay_rate": { "annual_rate": 0.12682503, "daily_rate": 0.00033173, "interest_base": { "enumerator": "calendar_days", "year_days": 360 }, "monthly_rate": 0.01 } }, "attached_documents": [ { "document_key": "d6705fc4-80e0-4c8e-9aff-f3875024e6a4", "document_url": "https://storage.googleapis.com/sandbox-doc-api/documents/...", "signature_url": "https://storage.googleapis.com/sandbox-doc-api/documents/..._signed.pdf", "document_type": "ccb_pre_price_days", "signature_required": true, "signed": true } ], "related_parties": [ { "related_party_key": "24fac77e-7782-4f72-b31a-daee288e34ed", "role_type": "issuer", "person_type": "natural", "name": "Dante Ferrarini", "email": "", "individual_document_number": "31057466093" } ], "base_iof": 3.79, "additional_iof": 3.83, "assignment_amount": 1010.64, "created_at": "2026-04-07T23:59:22Z", "total_prefixed_amount": 80.16 } ``` STATUS 400 Response Body ```json { "data": "{\"title\": \"Bad Request\", \"description\": \"Invalid request body.\", \"translation\": \"Corpo da requisição inválido.\", \"extra_fields\": {}, \"code\": \"LEG000069\"}" } ``` --- ## Query Operation Events You can also query the event history (status log) of the operation: ENDPOINT /v2/credit_operation/ CREDIT-OPERATION-KEY /events METHOD GET Test in Playground ### Path Params | Field | Type | Description | Max. Char. | |---|---|---|---| | `credit_operation_key`* | string | Credit operation key | UUID | ### Response STATUS 200 Response Body ```json { "data": [ { "status": "waiting_signature", "reason": null, "cancel_reason": null, "event_date": "2026-03-13T17:19:59Z" }, { "status": "issued", "reason": null, "cancel_reason": null, "event_date": "2026-03-13T17:19:59Z" }, { "status": "waiting_disbursement", "reason": null, "cancel_reason": null, "event_date": "2026-03-13T17:19:59Z" }, { "status": "opened", "reason": null, "cancel_reason": null, "event_date": "2026-03-13T17:19:59Z" } ], "pagination": { "current_page": 1, "next_page": null, "rows_per_page": 10 } } ``` ### Operation Status Enumerators | Status | Description | |---|---| | `waiting_signature` | Waiting for contract signature | | `issued` | Operation issued | | `waiting_disbursement` | Waiting for disbursement | | `opened` | Operation opened (disbursement completed) | | `canceled` | Operation canceled | | `settled` | Operation settled (all installments paid) | --- # BNPL Issuance URL: /en/documentation/manual_bnpl_full/emissao/ # BNPL Issuance ## Summary This endpoint issues the debt and processes the contract signature via opt-in. Disbursement occurs automatically immediately after issuance. Pre-registration is not required; simply provide the borrower's details during the debt request. ## Request ENDPOINT /signed_debt METHOD POST Test in Playground Request Body ```json { "borrower": { "name": "Dante Ferrarini", "email": "", "phone": { "number": "185633631", "area_code": "15", "country_code": "086" }, "is_pep": false, "address": { "city": "São Paulo", "state": "SP", "number": "", "street": "Rua Gilberto Sabino", "postal_code": "05425020", "neighborhood": "Pinheiros", "complement": "" }, "role_type": "issuer", "birth_date": "1993-09-10", "person_type": "natural", "attached_documents_list": [ { "selfie": "250e7e95-57c8-40bd-a0cd-0be8eb172916" } ], "individual_document_number": "31057466093" }, "financial": { "interest_type": "pre_price_days", "disbursement_date": "2026-04-07", "fine_configuration": { "monthly_rate": 0.01, "interest_base": "calendar_days", "contract_fine_rate": 0.02 }, "disbursed_amount": 1000, "credit_operation_type": "ccb", "interest_grace_period": 0, "number_of_installments": 2, "principal_grace_period": 0, "monthly_interest_rate": 0.052 }, "simplified": true, "additional_data": { "contract": { "contract_number": "DWF1761222116", "signatures": [ { "signer": { "name": "Dante Ferrarini", "email": "", "phone": { "number": "185633631", "area_code": "15", "country_code": "086" }, "document_number": "31057466093" }, "signature": { "timestamp": "28-01-2026 06:36:35", "ip_address": "192.168.1.1", "signature_file": { "file_url": "https://qitech.com.br/signature.pdf", "file_type": "pdf" } } } ] } }, "requester_identifier_key": "d1905ef5-19df-4183-bf0e-802b8229933c", "purchaser_document_number": "32402502000135", "disbursement_bank_accounts": [ { "name": "company name", "ispb_number": "32402502", "account_digit": "5", "branch_number": "0001", "account_number": "7617846", "document_number": "32246162000281", "percentage_receivable": 100 } ] } ``` ### Request Body Details | Field | Type | Description | Max. Char. | |---|---|---|---| | **borrower*** | object | Borrower Object - The debtor of the credit operation | **[Borrower Object](#borrower-object)** | | **financial*** | object | Contains all financial details and calculation parameters for the operation | **[Financial Object](#financial-object)** | | **simplified** | boolean | If true, uses the simplified issuance flow | - | | **additional_data*** | object | Additional contract data, including signatures | **[Additional Data Object](#additional-data-object)** | | **requester_identifier_key** | string | Requester identifier key | UUID | | **purchaser_document_number*** | string | Assignee's Tax ID – The buyer of the credit operation (FIDC/Receivables Investment Fund) | 14 | | **disbursement_bank_accounts*** | array | Technical details of the bank account where the operation funds will be deposited | **[Disbursement Bank Account Object](#disbursement-bank-account-object)** | ### Borrower Object | Field | Type | Description | Max. Char. | |---|---|---|---| | name* | string | Full name of the borrower | 100 | | email | string | Borrower's email address | 254 | | phone | object | Borrower's contact telephone details | **[Phone Object](#phone-object)** | | is_pep* | boolean | Politically Exposed Person (PEP) indicator | 5 | | address* | object | Borrower's residential address details | **[Address Object](#address-object)** | | role_type | string | The role of the person in the operation (e.g., "issuer") | 10 | | birth_date* | date | Borrower's date of birth (Format: "YYYY-MM-DD") | 10 | | person_type* | string | Person classification (natural or legal) | 7 | | attached_documents_list | array | List of attached documents (e.g., selfie) | **[Attached Documents Object](#attached-documents-object)** | | individual_document_number* | string | Borrower's Tax ID (CPF) - numbers only | 11 | ### Attached Documents Object | Field | Type | Description | Max. Char. | |---|---|---|---| | selfie | string | DOCUMENT_KEY of the selfie document uploaded via upload | UUID | ### Address Object | Field | Type | Description | Max. Char. | |---|---|---|---| | city* | string | City name of the address | 100 | | state* | string | State abbreviation (two uppercase characters) | 2 | | number | string | Street number | 10 | | street* | string | Street name | 100 | | complement | string | Address complement (free text) | 100 | | postal_code* | string | Postal code (CEP) - numbers only | 8 | | neighborhood* | string | Neighborhood or district name | 100 | ### Phone Object | Field | Type | Description | Max. Char. | |---|---|---|---| | number* | string | Subscriber's phone number | 9 | | area_code* | string | Two-digit regional area code (e.g., "11") | 2 | | country_code* | string | International dialing code (e.g., "055") | 3 | ### Financial Object | Field | Type | Description | Max. Char. | |---|---|---|---| | interest_type* | string | Amortization method | 20 | | disbursement_date* | string | Disbursement date | 10 | | fine_configuration* | object | Fine and penalty configuration | **[Fine Configuration Object](#fine-configuration-object)** | | disbursed_amount* | float | Amount to be disbursed | 15,2 | | credit_operation_type* | string | Type of credit operation (e.g., "ccb") | 10 | | interest_grace_period | integer | Interest grace period (in months) | 3 | | number_of_installments* | integer | Number of installments | 3 | | principal_grace_period | integer | Principal grace period (in months) | 3 | | monthly_interest_rate* | float | Monthly interest rate | 10,6 | ### Fine Configuration Object | Field | Type | Description | Max. Char. | |---|---|---|---| | monthly_rate* | float | Monthly penalty rate | 10,6 | | interest_base* | string | Penalty calculation base (e.g., "calendar_days") | 20 | | contract_fine_rate* | float | Contractual fine rate | 10,6 | ### Disbursement Bank Account Object | Field | Type | Description | Max. Char. | |---|---|---|---| | name | string | Account holder's full name | 50 | | ispb_number | string | Financial institution's ISPB code | 8 | | account_digit* | string | Account check digit (use zero instead of letters) | 1 | | branch_number* | string | Branch number (do not include the branch check digit!) | 4 | | account_number* | string | Account number (do not include the account check digit!) | 10 | | document_number | string | Account holder's Tax ID (CPF/CNPJ) | 14 | | percentage_receivable* | float | Disbursement percentage for this account | 3 | ### Additional Data Object | Field | Type | Description | Max. Char. | |---|---|---|---| | contract* | object | Contract data | **[Contract Object](#contract-object)** | ### Contract Object | Field | Type | Description | Max. Char. | |---|---|---|---| | contract_number* | string | The unique identifier or reference number of the contract | 20 | | signatures* | array | List of digital signature evidence objects (Opt-in) | **[Signature Object](#signature-object)** | ### Signature Object | Field | Type | Description | Max. Char. | |---|---|---|---| | signer* | object | Signer identification data | **[Signer Object](#signer-object)** | | signature* | object | Digital signature evidence data | **[Signature Details Object](#signature-details-object)** | ### Signer Object | Field | Type | Description | Max. Char. | |---|---|---|---| | name* | string | Full name of the signer | 255 | | document_number* | string | Signer's tax identification number (CPF) | 11 | | email | string | Electronic mail address of the signer | 100 | | phone | object | Signer's contact telephone details | **[Phone Object](#phone-object)** | ### Signature Details Object | Field | Type | Description | Max. Char. | |---|---|---|---| | ip_address* | string | The IP address used during the signature process | 45 | | timestamp* | string | Date and time of the signature (ISO 8601: YYYY-MM-DDTHH:mm:ssZ) | 24 | | signature_file* | object | Digital signature file | **[Signature File Object](#signature-file-object)** | ### Signature File Object | Field | Type | Description | Max. Char. | |---|---|---|---| | file_url* | string | Direct link to the signed contract document (PDF) | 2048 | | file_type* | string | Format of the signature file (e.g., "pdf") | 4 | ## Response The response to this debt request will return the payment plan as well as a **DEBT-KEY**, which is the identifier of the debt in QI SCD. STATUS 201 Response Body ```json { "webhook_type": "debt", "key": "72760166-4ddf-41fb-8a8c-605f8f4fc35c", "status": "issued", "event_datetime": "2026-04-07 23:59:28", "data": { "borrower": { "name": "Dante Ferrarini", "document_number": "31057466093", "related_party_key": "24fac77e-7782-4f72-b31a-daee288e34ed" }, "contract": { "document_key": null, "number": "DWF1761222116", "urls": [], "signature_information": [ { "signer_name": "Dante Ferrarini", "signer_document_number": "31057466093", "signer_role": "issuer", "signer_email": null, "signer_external_key": null, "signature_url": null } ] }, "requester_identifier_key": "d1905ef5-19df-4183-bf0e-802b8229933c", "iof_charge_method": "financed", "collaterals": [], "contract_fees": [ { "fee_type": "spread", "fee_amount": 3.02 } ], "external_contract_fees": [ { "fee_type": "tac", "fee_amount": 0, "tax_amount": 0, "net_fee_amount": 0 } ], "external_contract_fee_amount": 0, "net_external_contract_fee_amount": 0, "contract_fee_amount": 3.02, "issue_amount": 1007.62, "assignment_amount": 1010.64, "cet": "5,8200%", "annual_cet": "97,0501%", "number_of_installments": 2, "base_iof": 3.79, "additional_iof": 3.83, "total_iof": 7.62, "ipoc_code": "324025020203131057466093DWF1761222116", "prefixed_interest_rate": { "annual_rate": 0.8373372409, "created_at": "2026-04-07T23:59:22", "daily_rate": 0.0016911989, "interest_base": "calendar_days", "monthly_rate": 0.052 }, "installments": [ { "accrual_reference_date": null, "additional_costs": [], "advanced_paid_amount": 0, "bank_slip_key": null, "business_due_date": "2026-05-07", "calendar_days": 30, "digitable_line": null, "due_date": "2026-05-07", "due_interest": 0, "due_principal": 1007.62, "fine_amount": null, "has_interest": true, "installment_history": [], "installment_key": "1dea396f-beb1-4df3-9822-35800b4c095a", "installment_number": 1, "installment_payment": [], "installment_status": "created", "installment_type": "principal", "original_due_principal": 1007.62, "original_pre_fixed_amount": 52.3996159, "original_principal_amortization_amount": 491.4903841, "original_total_amount": 543.89, "paid_amount": 0, "paid_at": null, "post_fixed_amount": 0, "pre_fixed_amount": 52.3996159, "principal_amortization_amount": 491.4903841, "qr_code_key": null, "qr_code_url": null, "renegotiation_proposal_key": null, "tax_amount": 1.20906634, "total_accrual_amount": null, "total_amount": 543.89, "total_paid_amount": 0, "workdays": 20 }, { "accrual_reference_date": null, "additional_costs": [], "advanced_paid_amount": 0, "bank_slip_key": null, "business_due_date": "2026-06-08", "calendar_days": 31, "digitable_line": null, "due_date": "2026-06-07", "due_interest": 0, "due_principal": 516.1296159, "fine_amount": null, "has_interest": true, "installment_history": [], "installment_key": "370e73d1-55d8-431e-9b22-d08fb8297999", "installment_number": 2, "installment_payment": [], "installment_status": "created", "installment_type": "principal", "original_due_principal": 516.1296159, "original_pre_fixed_amount": 27.7603841, "original_principal_amortization_amount": 516.1296159, "original_total_amount": 543.89, "paid_amount": 0, "paid_at": null, "post_fixed_amount": 0, "pre_fixed_amount": 27.7603841, "principal_amortization_amount": 516.1296159, "qr_code_key": null, "qr_code_url": null, "renegotiation_proposal_key": null, "tax_amount": 2.58168034, "total_accrual_amount": null, "total_amount": 543.89, "total_paid_amount": 0, "workdays": 20 } ], "total_pre_fixed_amount": 80.16 } } ``` :::caution Attention Remember to save the **DEBT-KEY** returned in the response, as it will be required for queries, renegotiations, and reversals of the operation. ::: ### Response Body Details | Field | Type | Description | |---|---|---| | **webhook_type** | string | Event type identifier | | **key** | string | DEBT-KEY — unique identifier of the debt in QI SCD (UUID) | | **status** | string | Current status of the debt | | **event_datetime** | string | Date and time of the event (ISO 8601) | | **data** | object | **[Data Object](#data-object)** — Operation data | ### Data Object | Field | Type | Description | |---|---|---| | **borrower** | object | **[Borrower Response Object](#borrower-response-object)** — Borrower data | | **contract** | object | **[Contract Response Object](#contract-response-object)** — Contract data | | **requester_identifier_key** | string | Requester identifier key (UUID) | | **iof_charge_method** | string | IOF charge method — always "financed" | | **collaterals** | array | List of collaterals associated with the operation | | **contract_fees** | array | **[Contract Fees Object](#contract-fees-object)** — QI Tech fees charged on the operation | | **external_contract_fees** | array | **[External Contract Fees Object](#external-contract-fees-object)** — External fees charged on the operation | | **external_contract_fee_amount** | float | Total external contract fee amount | | **net_external_contract_fee_amount** | float | Net external contract fee amount after taxes | | **contract_fee_amount** | float | Total QI Tech contract fee amount | | **issue_amount** | float | Nominal/issue value of the credit operation | | **assignment_amount** | float | Acquisition value of the credit operation | | **cet** | string | Monthly total effective cost (CET) | | **annual_cet** | string | Annual total effective cost (CET) | | **number_of_installments** | integer | Number of installments | | **base_iof** | float | Base IOF amount | | **additional_iof** | float | Additional IOF amount | | **total_iof** | float | Total IOF amount | | **ipoc_code** | string | Brazilian credit registry code generated by QI Tech | | **prefixed_interest_rate** | object | **[Interest Rate Response Object](#interest-rate-response-object)** — Nominal interest rate details | | **installments** | array | **[Installments Response Object](#installments-response-object)** — Operation installments | | **total_pre_fixed_amount** | float | Total pre-fixed interest amount across all installments | ### Borrower Response Object | Field | Type | Description | |---|---|---| | **name** | string | Full name of the borrower | | **document_number** | string | Borrower's tax ID (CPF) | | **related_party_key** | string | Borrower's unique identifier in QI Tech (UUID) | ### Contract Response Object | Field | Type | Description | |---|---|---| | **document_key** | string | Contract document key | | **number** | string | Contract number | | **urls** | array | List of contract document URLs | | **signature_information** | array | **[Signature Information Object](#signature-information-object)** — Signature details | ### Signature Information Object | Field | Type | Description | |---|---|---| | **signer_name** | string | Signer's full name | | **signer_document_number** | string | Signer's tax ID (CPF) | | **signer_role** | string | Signer's role in the operation | | **signer_email** | string | Signer's email address | | **signer_external_key** | string | External signer key | | **signature_url** | string | URL of the signed document | ### Contract Fees Object | Field | Type | Description | |---|---|---| | **fee_type** | string | Fee type | | **fee_amount** | float | Fee amount | ### External Contract Fees Object | Field | Type | Description | |---|---|---| | **fee_type** | string | External fee type | | **fee_amount** | float | External fee amount | | **tax_amount** | float | Tax amount on the fee | | **net_fee_amount** | float | Net fee amount after taxes | ### Interest Rate Response Object | Field | Type | Description | |---|---|---| | **annual_rate** | float | Annual interest rate | | **created_at** | string | Rate creation timestamp (ISO 8601) | | **daily_rate** | float | Daily interest rate | | **interest_base** | string | Interest calculation base | | **monthly_rate** | float | Monthly interest rate | ### Installments Response Object | Field | Type | Description | |---|---|---| | **accrual_reference_date** | string | Reference date for installment calculations | | **additional_costs** | array | List of additional costs on the installment | | **advanced_paid_amount** | float | Amount paid in advance | | **bank_slip_key** | string | Bank slip (boleto) key | | **business_due_date** | string | Due date adjusted to the next business day | | **calendar_days** | integer | Calendar days between installments | | **digitable_line** | string | Boleto digitable line | | **due_date** | string | Installment due date | | **due_interest** | float | Remaining interest before payment on due date | | **due_principal** | float | Outstanding balance at time of installment | | **fine_amount** | float | Fine amount applied | | **has_interest** | boolean | Indicator of interest incidence on the installment | | **installment_history** | array | History of installment events | | **installment_key** | string | Unique installment identifier (UUID) | | **installment_number** | integer | Installment number | | **installment_payment** | array | List of payments made on this installment | | **installment_status** | string | Current installment status | | **installment_type** | string | Installment type — always "principal" | | **original_due_principal** | float | Original outstanding balance at issuance | | **original_pre_fixed_amount** | float | Original pre-fixed interest amount at issuance | | **original_principal_amortization_amount** | float | Original principal amortization amount at issuance | | **original_total_amount** | float | Original total installment amount at issuance | | **paid_amount** | float | Amount already paid | | **paid_at** | string | Date of payment | | **post_fixed_amount** | float | Post-fixed interest amount — always 0 | | **pre_fixed_amount** | float | Current pre-fixed interest amount | | **principal_amortization_amount** | float | Principal amortization amount | | **qr_code_key** | string | PIX QR code key | | **qr_code_url** | string | PIX QR code URL | | **renegotiation_proposal_key** | string | Renegotiation proposal key, if applicable | | **tax_amount** | float | IOF amount on the installment | | **total_accrual_amount** | float | Total accrual amount | | **total_amount** | float | Total installment amount | | **total_paid_amount** | float | Total amount paid on this installment so far | | **workdays** | integer | Business days between installments | --- # Simulation - BNPL Issuance URL: /en/documentation/manual_bnpl_full/emissao/simulacao # Simulation - BNPL Issuance ## Summary At QI Tech, we provide our clients with the ability to simulate the values of a credit operation before it is actually issued. The simulation follows the same pattern as the debt issuance request, but it is not necessary to provide the borrower's registration and disbursement account details. ## Request ENDPOINT /v2/credit_operation/simulation METHOD POST Test in Playground Request Body ```json { "credit_operation_type": "ccb", "disbursed_issue_amount": 2800, "disbursement_date": "2025-09-24", "first_due_date": "2025-10-24", "force_installments_on_workdays": true, "interest_type": "pre_price_days", "issuer_person_type": "natural", "monthly_interest_rate": 0.04488, "number_of_installments": 2, "principal_amortization_month_period": 1 } ``` ### Request Body Details | Field | Type | Description | Max. Char. | |---|---|---|---| | **credit_operation_type*** | string | Type of credit operation | **[Credit Operation Type Enumerator](#credit-operation-type-enumerator)** | | **disbursed_issue_amount*** | float | The value actually released to the borrower | 15,2 | | **disbursement_date*** | string | The specific date the loan funds are made available | 10 | | **first_due_date*** | string | Due date of the first installment | 10 | | **force_installments_on_workdays*** | boolean | If true, ensures all installment due dates are moved to the next business day | - | | **interest_type*** | string | Amortization method | **[Interest Type Enumerator](#interest-type-enumerator)** | | **issuer_person_type*** | string | Defines whether the issuer is an individual or a legal entity | **[Person Type Enumerator](#person-type-enumerator)** | | **monthly_interest_rate*** | float | The percentage charged on a principal balance over a one-month period | 10,6 | | **number_of_installments*** | integer | Number of installments | 3 | | **principal_amortization_month_period*** | integer | Period, in months, between installments | 1 | ### Credit Operation Type Enumerator | Value | Description | |---|---| | `ccb` | Bank Credit Certificate (Cédula de Crédito Bancário) | ### Interest Type Enumerator | Value | Description | |---|---| | `pre_price_days` | Pre-fixed interest with Price amortization by calendar days | | `pre_price` | Pre-fixed interest with Price amortization by months | | `pre_sac` | Pre-fixed interest with SAC amortization | ### Person Type Enumerator | Value | Description | |---|---| | `natural` | Individual (natural person) | | `legal` | Legal entity (corporation/business) | ## Response STATUS 200 Response Body ```json { "disbursement_date": "2025-09-24", "issue_amount": 2821.32, "interest_type": "pre_price_days", "assignment_amount": 2829.78, "base_iof": 10.6, "total_iof": 21.32, "additional_iof": 10.72, "cet": 5.09, "annual_cet": 81.39, "first_due_date": "2025-10-24", "disbursed_amount": 2800, "prefixed_interest_rate": { "annual_rate": 0.6935459998, "daily_rate": 0.0014644728, "interest_base": "calendar_days", "monthly_rate": 0.04488 }, "tax_configuration": { "base_rate": 8.2e-05, "additional_rate": 0.0038 }, "fees": [ { "amount": 0.3, "fee_amount": 8.46, "amount_type": "percentage", "fee_type": "spread", "type": "internal" } ], "installments": [ { "due_date": "2025-10-24", "amount": 1507.4, "due_principal": 2821.32, "due_interest": 0, "has_interest": true, "period": 1, "period_workdays": 1.1, "calendar_days": 30, "workdays": 22, "installment_number": 1, "period_to_disbursement": 1, "prefixed_amount": 126.62248868, "period_workdays_to_disbursement": 1.1, "calendar_days_to_disbursement": 30, "workdays_to_disbursement": 22, "tax_amount": 3.39671268, "principal_amortization_amount": 1380.77751132 }, { "due_date": "2025-11-24", "amount": 1507.4, "due_principal": 1440.54248868, "due_interest": 0, "has_interest": true, "period": 1, "period_workdays": 1, "calendar_days": 31, "workdays": 20, "installment_number": 2, "period_to_disbursement": 2, "prefixed_amount": 66.85751132, "period_workdays_to_disbursement": 2.1, "calendar_days_to_disbursement": 61, "workdays_to_disbursement": 42, "tax_amount": 7.20559353, "principal_amortization_amount": 1440.54248868 } ] } ``` ### Response Body Details | Field | Type | Description | |---|---|---| | **annual_cet** | float | Total effective cost expressed as a decimal per year | | **assignment_amount** | float | Acquisition value of the credit operation | | **cet** | float | Total effective cost expressed as a decimal per month | | **fees** | array | **[Fees Object](#fees-object)** - List of QI Tech fees charged on the operation | | **disbursed_amount** | float | Amount disbursed in the credit operation | | **disbursement_date** | string | Disbursement date of the operation | | **installments** | array | **[Installments Object](#installments-object)** - Installments of the operation | | **interest_type** | string | Amortization method and interest calculation method | | **additional_iof** | float | A fixed-rate tax applied to the transaction principal | | **base_iof** | float | The taxable amount used as the basis for calculating the Tax on Financial Operations | | **total_iof** | float | The total amount of Tax on Financial Operations applied to the transaction | | **issue_amount** | float | Issue/nominal value of the credit operation | | **tax_configuration** | object | **[Tax Configuration Object](#tax-configuration-object)** - IOF rate values | | **first_due_date** | string | Due date of the first installment | | **prefixed_interest_rate** | object | **[Interest Rate Object](#interest-rate-object)** - Nominal interest rate | ### Fees Object | Field | Type | Description | |---|---|---| | **amount** | float | Fee value or percentage | | **fee_amount** | float | Monetary fee value | | **amount_type** | string | Value type (percentage or fixed) | | **fee_type** | string | Fee type | | **type** | string | Fee classification (internal or external) | ### Installments Object | Field | Type | Description | |---|---|---| | **due_date** | string | Installment due date | | **amount** | float | Total installment amount | | **due_principal** | float | Outstanding balance at the time of the installment | | **due_interest** | float | Remaining interest after the installment due date before its payment | | **has_interest** | boolean | Indicator of interest incidence on the installment | | **installment_number** | integer | Installment number | | **prefixed_amount** | float | Pre-fixed interest amount paid in the installment | | **tax_amount** | float | IOF amount on the installment | | **principal_amortization_amount** | float | Principal amortization amount | | **period** | float | Installment period | | **period_workdays** | float | Installment period in workdays | | **period_to_disbursement** | float | Number of accumulated periods from disbursement to this installment | | **period_workdays_to_disbursement** | float | Number of accumulated periods in workdays from disbursement to this installment | | **calendar_days** | integer | Calendar days between installments | | **calendar_days_to_disbursement** | integer | Accumulated calendar days from disbursement to this installment | | **workdays** | integer | Business days between installments | | **workdays_to_disbursement** | integer | Accumulated business days from disbursement to this installment | ### Tax Configuration Object | Field | Type | Description | |---|---|---| | **base_rate** | float | Base IOF rate | | **additional_rate** | float | Additional IOF rate | ### Interest Rate Object | Field | Type | Description | |---|---|---| | **annual_rate** | float | Annual interest rate | | **daily_rate** | float | Daily interest rate | | **interest_base** | string | Interest calculation base | | **monthly_rate** | float | Monthly interest rate | --- # Webhooks - BNPL Issuance URL: /en/documentation/manual_bnpl_full/emissao/webhooks ## Summary After a successful issuance response, you will receive webhooks notifying you about the events in the operation lifecycle: contract signature, disbursement, and eventually cancellation. :::danger Attention! Webhooks should not be strictly mapped. New fields may be added to the payload without prior notice. ::: ## Signature Webhook This webhook is sent when the contract (CCB) is successfully signed. WEBHOOK_TYPE debt STATUS signature_finished Webhook Body ```json { "key": "1ebd4a90-2721-4c39-a399-427fa16bca65", "status": "signature_finished", "webhook_type": "debt", "event_datetime": "2025-10-27T17:09:33Z", "signed_contract_url": "https://storage.googleapis.com/sandbox-doc-api/documents/c8b191cb-7b90-4e37-9280-397a597babc1/CCB-TIK11267101212-20251027170925_signed.pdf" } ``` ### Signature Webhook Fields | Field | Type | Description | |---|---|---| | **key** | string | Unique debt key (DEBT-KEY) | | **status** | string | Event status: `signature_finished` | | **webhook_type** | string | Webhook type: `debt` | | **event_datetime** | string | Event date and time | | **signed_contract_url** | string | URL of the signed contract (PDF) | ## Disbursement Webhook This webhook confirms that the disbursement was successfully completed. WEBHOOK_TYPE debt STATUS disbursed Webhook Body ```json { "key": "1ebd4a90-2721-4c39-a399-427fa16bca65", "data": { "installments": [ { "due_date": "2025-11-27", "total_amount": 87.43, "installment_key": "e25fb146-0a61-4319-a722-d01b2213d0f9", "pre_fixed_amount": 29.26477451, "installment_number": 1, "principal_amortization_amount": 58.16522549 }, { "due_date": "2025-12-27", "total_amount": 87.43, "installment_key": "2557de2b-6df1-4a8a-b46a-59206ece157f", "pre_fixed_amount": 20.11446867, "installment_number": 2, "principal_amortization_amount": 67.31553133 }, { "due_date": "2026-01-27", "total_amount": 87.43, "installment_key": "cc503d1d-6387-4a1f-bd78-62b248d02ec8", "pre_fixed_amount": 11.07075682, "installment_number": 3, "principal_amortization_amount": 76.35924318 } ], "ted_receipt_list": [], "requester_identifier_key": null }, "status": "disbursed", "webhook_type": "debt", "event_datetime": "2025-10-27T17:10:21Z" } ``` ### Disbursement Webhook Fields | Field | Type | Description | |---|---|---| | **key** | string | Unique debt key (DEBT-KEY) | | **status** | string | Event status: `disbursed` | | **webhook_type** | string | Webhook type: `debt` | | **event_datetime** | string | Event date and time | | **data.installments** | array | List of installments with their keys and amounts | | **data.ted_receipt_list** | array | List of TED receipts (when applicable) | ## Cancellation Webhook If the debt fails to disburse, or is returned, you will receive a cancellation webhook. WEBHOOK_TYPE debt STATUS canceled Webhook Body ```json { "webhook_type": "debt", "key": "1ebd4a90-2721-4c39-a399-427fa16bca65", "event_datetime": "2025-10-27T16:38:59Z", "data": { "cancel_reason": "Operacao cancelada manualmente", "cancel_reason_enumerator": "manual" }, "status": "canceled" } ``` ### Cancellation Webhook Fields | Field | Type | Description | |---|---|---| | **key** | string | Unique debt key (DEBT-KEY) | | **status** | string | Event status: `canceled` | | **webhook_type** | string | Webhook type: `debt` | | **event_datetime** | string | Event date and time | | **data.cancel_reason** | string | Textual description of the cancellation reason | | **data.cancel_reason_enumerator** | string | Cancellation reason enumerator | ### Cancellation Enumerators | Enumerator | Description | |---|---| | `disbursing_error` | Operation canceled due to an error during disbursement | | `waiting_signature` | Operation canceled due to missing signature | | `pix_max_retry` | Operation canceled because the receiving bank could not process the disbursement | | `manual` | Operation canceled manually | | `agencia_conta_invalida` | Invalid agency or recipient account number | | `invalid_account` | The destination account number is nonexistent or invalid | | `invalid_document_number` | The CPF/CNPJ of the destination account is incorrect | | `unsupported_transaction` | The destination account does not support this type of transaction | | `invalid_ispb` | The ISPB number is invalid or nonexistent | | `rejected_payment` | Payment order was rejected by the receiving bank | | `refund_after_payee_request` | Refund requested by the payee | | `blocked_account` | The destination account is blocked | | `amount_too_great` | Payment/refund amount exceeds the limit for the credited destination account | | `receiver_error` | Transaction interrupted due to error on the receiver's PSP | | `closed_account` | The destination account is closed | | `disbursing_hour_closed` | Disbursement occurred outside of the allowed time frame | | `unregistered_pix_key` | The Pix key is not registered | | `spi_timeout` | Timeout control in SPI | --- # BNPL Reversal URL: /en/documentation/manual_bnpl_full/estorno/ # BNPL Reversal ## Summary The reversal of a BNPL operation allows you to reverse the disbursement. There are two cancellation/reversal scenarios: 1. **Cancellation before disbursement**: Cancels the operation before the funds are transferred 2. **Reversal after disbursement (up to 7 days)**: Generates a Pix refund so the borrower can return the funds --- ## 1. Cancellation Before Disbursement Cancels a credit operation that has not yet been disbursed. ### Request ENDPOINT /debt/ DEBT-KEY /cancel METHOD PATCH Test in Playground ### Path Params | Field | Type | Description | Max. Char. | |---|---|---|---| | `debt_key`* | string | Unique debt key returned at the time of the credit operation creation | UUID | ### Response STATUS 200 Response Body ```json {} ``` :::caution Attention This endpoint can only be used for operations that have **not yet been disbursed**. For already disbursed operations, use the reversal endpoint below. ::: --- ## 2. Reversal After Disbursement (Up to 7 Days) Reverses a BNPL operation that has already been disbursed, within 7 calendar days after disbursement. The system generates a copy-and-paste Pix code so the borrower can return the funds. ### Request ENDPOINT /debt/reversal METHOD POST Test in Playground Request Body ```json { "credit_operation_key": "72760166-4ddf-41fb-8a8c-605f8f4fc35c" } ``` ### Body Params | Field | Type | Description | Max. Char. | |---|---|---|---| | `credit_operation_key`* | string | Credit operation key (DEBT-KEY) | UUID | ### Response STATUS 200 Response Body ```json { "payer_name": "Dante Ferrarini", "payer_document_number": "31057466093", "amount": 1000, "expiration_date": "2026-04-28", "copy_paste_pix": "00020126930014br.gov.bcb.pix2571qrcode-h.sandbox.qitech.app/bacen/cobv/fb1906ab2eff40109609855ac104f60e5204000053039865802BR5925QISOCIEDADEDECREDITODIRET6008SaoPaulo61080145200062070503***63046387", "reversal_key": "7a18fdb6-a3e7-4fc9-833e-0f6d8e98de3b", "status": "active", "debt_key": "72760166-4ddf-41fb-8a8c-605f8f4fc35c", "qr_code_key": "fb1906ab-2eff-4010-9609-855ac104f60e" } ``` ### Response Details | Field | Type | Description | |---|---|---| | **payer_name** | string | Borrower's name | | **payer_document_number** | string | Borrower's CPF/CNPJ | | **amount** | float | Total amount to be returned | | **expiration_date** | string | Expiration date of the refund Pix | | **copy_paste_pix** | string | Pix copy-and-paste code for fund return | | **reversal_key** | string | Unique reversal key (UUID) | | **status** | string | Reversal status: `active` | | **debt_key** | string | Debt key (DEBT-KEY) | | **qr_code_key** | string | Pix QR Code key (UUID) | :::warning Important - Reversal can only be performed within **7 calendar days** after disbursement - The generated `copy_paste_pix` has an **expiration date**. After this date, the Pix can no longer be used - After the borrower pays the Pix, the operation will be automatically canceled and you will receive a cancellation webhook ::: --- # Refund via Amortization — equal_amount and full_settle URL: /en/documentation/manual_bnpl_full/estorno/estorno_amortizacao ## Summary In addition to the cancel-before-disbursement and 7-day Pix reversal flows (see [BNPL Refund](./estorno.md)), BNPL Full offers **two amortization-based refund modes** that return funds by debiting an internal partner account directly: - **`equal_amount`** — **partial** refund. Distributes the informed amount proportionally across the operation's installments, reducing the outstanding balance. The operation remains active, with remaining installments still open. - **`full_settle`** — **total** refund. Settles the operation in full in a single transaction, calculating the present value of all installments as of `reference_date`. After settlement, the operation is marked as `settled` and no remaining installments exist. Both modes use the `POST /renegotiation/proposal` endpoint with `payment_type: "internal"`, which means the amount is moved directly from the account informed in `account_key`, without generating a bank slip or Pix. --- ## When to use each mode ### `equal_amount` — Partial Refund Use when the borrower wants to **reduce** the outstanding balance without closing the operation. The `payment_amount` is distributed across installments, amortizing principal, interest, and any applicable fine. Installments that have not been fully amortized remain in `remaining_installments` to be collected on their upcoming due dates. Typical cases: - Borrower overpaid and wants to offset part of the debt only. - Partial return of funds negotiated between partner and borrower. - Application of credits or one-off refunds on active operations. ### `full_settle` — Total Refund Use when the goal is to **pay off** the operation completely. The system calculates the present value of all open installments as of `reference_date` (principal + accrued interest + any applicable fine) and distributes the `payment_amount` to zero out the balance. The operation transitions to `settled`. Typical cases: - Refund after the 7-day `POST /debt/reversal` window. - Early payoff requested by the borrower. - Administrative closure of the operation with full return of funds. :::info Sequencing The two modes can be combined. For example: several `equal_amount` calls for partial amortizations, followed by a final `full_settle` to close out the remaining balance. ::: --- ## Request ENDPOINT /renegotiation/proposal METHOD POST Try in Playground Request Body **equal_amount (partial)** ```json { "debt_key": "72760166-4ddf-41fb-8a8c-605f8f4fc35c", "payment_type": "internal", "amortization_type": "equal_amount", "reference_date": "2026-04-13", "payment_amount": 50.00, "account_key": "5ae72355-1e47-4624-9915-ceb93d872194", "request_control_key": "94b31045-c8e7-45be-a88d-2ae25c5df5db" } ``` **full_settle (total)** ```json { "debt_key": "72760166-4ddf-41fb-8a8c-605f8f4fc35c", "payment_type": "internal", "amortization_type": "full_settle", "reference_date": "2026-04-13", "payment_amount": 1043.55, "account_key": "5ae72355-1e47-4624-9915-ceb93d872194", "request_control_key": "e5f6c3d4-e5f6-7890-abcd-ef1234567890" } ``` ### Body Params | Field | Type | Description | Characters | |---|---|---|---| | `debt_key`* | string | Unique key of the credit operation to be refunded | UUID | | `payment_type`* | string | Must be `internal` for refunds via internal account | 8 | | `amortization_type`* | string | Refund mode | **[Amortization Type Enumerators](#amortization-type-enumerators)** | | `reference_date`* | string | Reference date for present-value calculation (format `YYYY-MM-DD`) | 10 | | `payment_amount`* | float | Refund amount in BRL (R$). In `equal_amount`, it is the partial amount to be offset. In `full_settle`, it must cover the total balance on `reference_date` | 15,2 | | `account_key`* | string | Internal account key from which the amount will be debited | UUID | | `request_control_key`* | string | Request control key (idempotency) | UUID | ### Amortization Type Enumerators | Value | Description | |---|---| | **`equal_amount`** | Partial refund. `payment_amount` is distributed proportionally across installments; the operation remains active with the remaining installments still open. | | **`full_settle`** | Total refund. Fully settles the operation on `reference_date`. The operation transitions to `settled` and no remaining installments exist. | --- ## Response STATUS 201 Response Body ```json { "proposal_key": "bcc16a6d-ce21-4cd4-8d8c-d26f89ccc685", "contract_number": "DWF1761222116", "amortization_type": "equal_amount", "payment_amount": 50.00, "discount_percentage": 0, "discount_amount": 0, "requester_name": "Dante Ltda", "requester_key": "78287247-947d-4730-9bd1-7efb068175b6", "origin_key": null, "issuer_name": "Dante Ferrarini", "issuer_document_number": "31057466093", "affected_installments": [ { "installment_key": "ca5741c7-99a2-42e7-92a1-9328a36e4e88", "due_date": "2026-05-07", "principal_amount": 15.71, "interest_amount": 4.07, "fine_amount": 0, "total_amount": 19.78, "present_amount": 18.00, "paid_amount": 18.00, "principal_amortization_payment_amount": 18.00, "prefixed_interest_payment_amount": 0, "fine_payment_amount": 0 } ], "remaining_installments": [ { "installment_key": "370e73d1-55d8-431e-9b22-d08fb8297999", "due_date": "2026-06-07", "principal_amount": 15.71, "interest_amount": 4.07, "fine_amount": 0, "total_amount": 19.78 } ], "proposal_status": "pending_payment", "payment_type": "internal", "payment": { "digitable_line": null, "qr_code_url": null, "qr_code_key": null, "bank_slip_key": null, "paid_method_type": "internal", "source_account_key": "5ae72355-1e47-4624-9915-ceb93d872194", "payment_data": { "target_account_key": "6108dd45-580d-48c4-b3bb-74c1e843be49", "transaction_amount": 50.00 } }, "proposal_due_date": "2026-04-13", "reference_date": "2026-04-13", "devolution_amount": 0, "request_control_key": "94b31045-c8e7-45be-a88d-2ae25c5df5db" } ``` ### Response Details | Field | Type | Description | |---|---|---| | `proposal_key` | string | Unique key of the refund proposal (UUID). Save it for queries and webhooks. | | `amortization_type` | string | Mode used (`equal_amount` or `full_settle`). | | `payment_amount` | float | Amount effectively applied in the refund. | | `proposal_status` | string | Proposal state. Starts at `pending_payment` and transitions to `paid` after the internal debit. | | `affected_installments` | array | Installments that received the refund amount. For each installment, shows the `paid_amount` split across principal, interest, and fine. | | `remaining_installments` | array | Installments that remain open after the refund. Empty in `full_settle`. | | `payment.payment_data.target_account_key` | string | Destination account of the internal debit. | | `payment.payment_data.transaction_amount` | float | Amount effectively moved from `account_key`. | | `devolution_amount` | float | Overpayment amount returned to the fund. Only non-zero when a prior payment already exists on the operation and the refund plus that payment together exceed the outstanding balance — the excess is returned via this field. | | `request_control_key` | string | Echo of the idempotency key sent in the request. | --- ## Rules and notes :::caution Attention - **Operation state**: the operation must be active and disbursed. Operations not yet disbursed must be cancelled via `PATCH /debt/{debt_key}/cancel`. - **`reference_date`**: drives interest and fine calculation. In `full_settle`, the entire balance is brought to present value on this date. **Cannot be earlier than the operation's disbursement date** — that is the minimum allowed value. - **Overdue installments**: when there are overdue installments, the `paid_amount` of the affected installment is split across `principal_amortization_payment_amount`, `prefixed_interest_payment_amount`, and `fine_payment_amount`. Check the breakdown in the `affected_installments` array. - **Idempotency**: `request_control_key` is mandatory. Use a unique UUID per attempt to avoid duplicates. - **`full_settle` with insufficient amount**: if `payment_amount` is lower than the calculated total balance, the debit is still processed and distributed proportionally — check the operation's final status to confirm settlement. ::: :::info Combining modes - Several `equal_amount` proposals can be made in sequence, each offsetting part of the balance. - A `full_settle` can be made after one or more `equal_amount` proposals to close out the remaining balance. - Each proposal is independent and must use a distinct `request_control_key`. ::: --- ## Query proposal status After creating the proposal, query its status by the `request_control_key` sent in the request. ENDPOINT /renegotiation/proposal/request_control_key/ REQUEST-CONTROL-KEY METHOD GET ### Path Params | Field | Type | Description | Characters | |---|---|---|---| | `request_control_key`* | string | Control key sent on proposal creation | UUID | The response follows the same format as the `POST` return. The `proposal_status` field indicates progress: | Status | Description | |---|---| | `pending_payment` | Proposal created, awaiting internal debit processing. | | `paid` | Debit processed. In `full_settle`, the operation is already `settled`. | --- ## Settlement Webhook When a refund fully settles the operation — typically in `full_settle`, but also in cases where the cumulative `equal_amount` amortizations zero out the balance — the system sends a `debt` webhook with status `settled`. WEBHOOK_TYPE debt STATUS settled Use this webhook to asynchronously confirm that the operation was closed after the internal debit is processed. The full payload and fields follow the pattern described in [Webhooks - BNPL Refund](./webhooks.md). --- # Webhooks - BNPL Reversal URL: /en/documentation/manual_bnpl_full/estorno/webhooks ## Summary After creating a reversal request, the system will send webhooks to notify you about the events in the reversal process. :::danger Attention! Webhooks should not be strictly mapped. New fields may be added to the payload without prior notice. ::: ## Cancellation by Reversal Webhook When the borrower makes the Pix refund payment generated by the reversal, the credit operation is automatically canceled and the following webhook is sent: WEBHOOK_TYPE debt STATUS canceled Webhook Body ```json { "webhook_type": "debt", "key": "1ebd4a90-2721-4c39-a399-427fa16bca65", "event_datetime": "2025-10-27T16:38:59Z", "data": { "cancel_reason": "Operacao cancelada por estorno", "cancel_reason_enumerator": "refund_after_payee_request" }, "status": "canceled" } ``` ### Webhook Fields | Field | Type | Description | |---|---|---| | **webhook_type** | string | Webhook type: `debt` | | **key** | string | Unique debt key (DEBT-KEY) | | **event_datetime** | string | Event date and time | | **status** | string | Event status: `canceled` | | **data.cancel_reason** | string | Textual description of the cancellation reason | | **data.cancel_reason_enumerator** | string | Cancellation reason enumerator | ### Reversal-Related Cancellation Enumerators | Enumerator | Description | |---|---| | `refund_after_payee_request` | Refund requested by the payee | | `manual` | Operation canceled manually | | `disbursing_error` | Operation canceled due to an error during disbursement | --- ## Transaction Reversal Settlement Webhook For reversals processed via the `transaction_reversal` endpoint, the confirmation webhook follows the format below: WEBHOOK_TYPE transaction_reversal.transaction_reversal_status_change STATUS paid Webhook Body ```json { "data": { "transaction_reversal_key": "b6da1a84-5bb3-4d71-9912-cbbcfe7189c1", "amount": 123.45, "status": "paid", "description": "Valor de liquidação indevido", "reference_date": "2025-03-23", "fund_class_document_number": "12.345.678/0009-10", "fund_class_key": "0619574f-2815-419d-8208-630b0dc30487", "source_account": { "account_digit": "7", "account_branch": "0001", "account_number": "0099999", "owner": { "name": "FUNDO DE INVESTIMENTO", "document_number": "12.345.678/0009-10" }, "financial_institution": { "code": "329", "ispb": "32402502", "name": "QI Sociedade de Crédito Direto" } }, "target_account": { "owner": { "name": "Nome fictício", "document_number": "111.202.188-99" }, "account_digit": "0", "account_branch": "0001", "account_number": "1029490", "target_pix_key": "1232221", "financial_institution": { "code": "033", "ispb": "90400888", "name": "BCO SANTANDER (BRASIL) S.A." } }, "external_key": "40054daa-c3c5-49cd-add7-858b576c5887" }, "webhook_type": "transaction_reversal.transaction_reversal_status_change", "webhook_datetime": "2025-03-23T15:08:30Z" } ``` ### Transaction Reversal Webhook Fields | Field | Type | Description | |---|---|---| | **webhook_type** | string | Webhook type: `transaction_reversal.transaction_reversal_status_change` | | **webhook_datetime** | string | Webhook send date and time | | **data.transaction_reversal_key** | string | Unique reversal key | | **data.amount** | float | Reversed amount | | **data.status** | string | Reversal status: `paid` | | **data.description** | string | Reversal description | | **data.reference_date** | string | Processing reference date | | **data.fund_class_key** | string | Fund key | | **data.source_account** | object | Reversal source account details | | **data.target_account** | object | Reversal target account details | | **data.external_key** | string | External key of the reversed transaction | --- # Present Value Inquiry - BNPL Refinancing URL: /en/documentation/manual_bnpl_full/refinanciamento/consulta_valor_presente # Present Value Inquiry - BNPL Refinancing ## Summary To find out the present value that will be used in the refinancing of an operation, you can use the debt inquiry endpoint with the query params listed below. ## Request ENDPOINT /debt METHOD GET ### Query Params | Field | Type | Description | |---|---|---| | `key`* | string | Debt key (DEBT-KEY) returned at the time of the credit operation creation | | `eval_present_value`* | string | Indicates that the current value of each installment should be calculated and displayed (`true`) | | `calculate_delay`* | string | Indicates that, if the installment is overdue, penalty interest and fines should be calculated with the present value (`true`) | | `calculate_spread`* | string | Indicates whether the spread value of the operation should be added to the present value. For refinancing operations should be `false` | ### URL Example ``` /debt?key=72760166-4ddf-41fb-8a8c-605f8f4fc35c&eval_present_value=true&calculate_delay=true&calculate_spread=false ``` ### Response STATUS 200 Response Body ```json { "webhook_type": "debt", "operation_key": "72760166-4ddf-41fb-8a8c-605f8f4fc35c", "status": "opened", "data": { "credit_operation_key": "72760166-4ddf-41fb-8a8c-605f8f4fc35c", "contract_number": "DWF1761222116", "annual_cet": 97.05, "cet": 5.82, "disbursed_issue_amount": 1000, "disbursement_date": "2026-04-07", "issue_amount": 1007.62, "final_disbursement_amount": 1000, "number_of_installments": 2, "total_iof": 7.62, "base_iof": 3.79, "additional_iof": 3.83, "assignment_amount": 1007.63, "issuer_name": "Dante Ferrarini", "issuer_document_number": "31057466093", "prefixed_interest_rate": { "annual_rate": 0.8373372409, "daily_rate": 0.0016911989, "interest_base": { "enumerator": "calendar_days", "year_days": 360 }, "monthly_rate": 0.052 }, "installments": [ { "installment_key": "1dea396f-beb1-4df3-9822-35800b4c095a", "installment_number": 1, "due_date": "2026-05-07", "business_due_date": "2026-05-07", "calendar_days": 30, "total_amount": 543.89, "due_principal": 1007.62, "pre_fixed_amount": 52.3996159, "principal_amortization_amount": 491.4903841, "tax_amount": 1.20906634, "installment_status": { "enumerator": "opened" }, "paid_amount": 0, "present_amount": 517.01, "workdays": 20 }, { "installment_key": "370e73d1-55d8-431e-9b22-d08fb8297999", "installment_number": 2, "due_date": "2026-06-07", "business_due_date": "2026-06-08", "calendar_days": 31, "total_amount": 543.89, "due_principal": 516.1296159, "pre_fixed_amount": 27.7603841, "principal_amortization_amount": 516.1296159, "tax_amount": 2.58168034, "installment_status": { "enumerator": "opened" }, "paid_amount": 0, "present_amount": 490.62, "workdays": 20 } ] } } ``` :::tip Refinancing Value The total value to be used as `disbursed_amount` in the refinancing simulation/creation is the sum of the `present_amount` of all installments. In this example: 517.01 + 490.62 = **1007.63**. ::: :::caution Attention For refinancing operations, the `calculate_spread` field should always be `false`, as the spread value should not be considered in the present value calculation for settlement. ::: --- # Creation - BNPL Refinancing URL: /en/documentation/manual_bnpl_full/refinanciamento/criacao # Creation - BNPL Refinancing ## Summary Creating a refinancing uses the same endpoint and payload as the issuance (`/signed_debt`), with the addition of the `refinanced_credit_operations` object containing the list of operations to be settled. The sum of the present value of the previous contracts will be retained and only the surplus will be released to the borrower's account. ## Request ENDPOINT /signed_debt METHOD POST Test in Playground Request Body ```json { "borrower": { "name": "Dante Ferrarini", "email": "", "phone": { "number": "185633631", "area_code": "15", "country_code": "086" }, "is_pep": false, "address": { "city": "São Paulo", "state": "SP", "number": "", "street": "Rua Gilberto Sabino", "postal_code": "05425020", "neighborhood": "Pinheiros", "complement": "" }, "role_type": "issuer", "birth_date": "1993-09-10", "person_type": "natural", "attached_documents_list": [ { "selfie": "250e7e95-57c8-40bd-a0cd-0be8eb172916" } ], "individual_document_number": "31057466093" }, "financial": { "final_disbursement_amount": 0, "interest_type": "pre_price_days", "credit_operation_type": "ccb", "annual_interest_rate": 2.32, "disbursement_date": "2026-04-07", "interest_grace_period": 0, "principal_grace_period": 0, "number_of_installments": 3, "fine_configuration": { "contract_fine_rate": 0.02, "interest_base": "calendar_days", "monthly_rate": 0.01 } }, "simplified": true, "additional_data": { "contract": { "contract_number": "DWFR00000012", "signatures": [ { "signer": { "name": "Dante Ferrarini", "email": "", "phone": { "number": "185633631", "area_code": "15", "country_code": "086" }, "document_number": "31057466093" }, "signature": { "timestamp": "2026-04-08T00:40:30Z", "ip_address": "192.168.1.1", "signature_file": { "file_url": "https://qitech.com.br/signature.pdf", "file_type": "pdf" } } } ] } }, "refinanced_credit_operations": [ { "operation_key": "72760166-4ddf-41fb-8a8c-605f8f4fc35c" } ], "requester_identifier_key": "d2107ef5-19df-4183-bf0e-802b8229933c", "purchaser_document_number": "32402502000135", "disbursement_bank_accounts": [ { "name": "company name", "ispb_number": "32402502", "account_digit": "5", "branch_number": "0001", "account_number": "7617846", "document_number": "32246162000281", "percentage_receivable": 100 } ] } ``` :::caution Attention The payload is **identical** to the issuance (`/signed_debt`), with the addition of the **`refinanced_credit_operations`** field containing the list of operations to be settled. ::: ### Request Body Details The payload contains all fields from the [BNPL Issuance](../emissao/emissao), with the addition of: | Field | Type | Description | Max. Char. | |---|---|---|---| | **refinanced_credit_operations*** | array | List of operations to be refinanced | **[Refinanced Credit Operations Object](#refinanced-credit-operations-object)** | All other fields follow the same specification as the issuance: - **[Borrower Object](../emissao/emissao#borrower-object)** - **[Additional Data Object](../emissao/emissao#additional-data-object)** - **[Disbursement Bank Account Object](../emissao/emissao#disbursement-bank-account-object)** :::info Financial Object Difference In refinancing, the `financial` field uses `annual_interest_rate` instead of `monthly_interest_rate`, and the `disbursed_amount` should be the total present value of the operation to be refinanced (obtained from the present value inquiry). ::: ### Refinanced Credit Operations Object | Field | Type | Description | Max. Char. | |---|---|---|---| | `operation_key`* | string | Key of the operation to be refinanced (DEBT-KEY of the original operation) | UUID | ## Response The response follows the same format as the debt issuance, returning the **DEBT-KEY** of the new contract. STATUS 201 Response Body ```json { "webhook_type": "debt", "key": "290f042f-eedd-4d9d-b621-3a81df0181b6", "status": "opened", "event_datetime": "2026-04-08 00:40:37", "data": { "borrower": { "name": "Dante Ferrarini", "document_number": "31057466093", "related_party_key": "3d62f3c6-1ae5-49f9-aa5d-21a08d95aad6" }, "contract": { "document_key": null, "number": "DWFR00000012", "urls": [], "signature_information": [ { "signer_name": "Dante Ferrarini", "signer_document_number": "31057466093", "signer_role": "issuer", "signer_email": null, "signer_external_key": null, "signature_url": null } ] }, "requester_identifier_key": "d2107ef5-19df-4183-bf0e-802b8229933c", "iof_charge_method": "financed", "collaterals": [], "contract_fees": [ { "fee_type": "spread", "fee_amount": 3.05 }, { "fee_type": "spread_refinancing", "fee_amount": 3.02 } ], "external_contract_fees": [ { "fee_type": "tac", "fee_amount": 0, "tax_amount": 0, "net_fee_amount": 0 } ], "external_contract_fee_amount": 0, "net_external_contract_fee_amount": 0, "contract_fee_amount": 6.07, "issue_amount": 1016.72, "assignment_amount": 1022.79, "cet": "11,1900%", "annual_cet": "256,9982%", "number_of_installments": 3, "base_iof": 5.23, "additional_iof": 3.86, "total_iof": 9.09, "ipoc_code": "324025020203131057466093DWFR00000012", "prefixed_interest_rate": { "annual_rate": 2.32, "created_at": "2026-04-08T00:40:30", "daily_rate": 0.0033387969, "interest_base": "calendar_days", "monthly_rate": 0.1051676747 }, "installments": [ { "accrual_reference_date": null, "additional_costs": [], "advanced_paid_amount": 0, "bank_slip_key": null, "business_due_date": "2026-05-07", "calendar_days": 30, "digitable_line": null, "due_date": "2026-05-07", "due_interest": 0, "due_principal": 1016.72, "fine_amount": null, "has_interest": true, "installment_history": [], "installment_key": "52810e9d-0815-4fd1-ab20-d8b37dcd936e", "installment_number": 1, "installment_payment": [], "installment_status": "created", "installment_type": "principal", "original_due_principal": 1016.72, "original_pre_fixed_amount": 106.92260459, "original_principal_amortization_amount": 306.50739541, "original_total_amount": 413.43, "paid_amount": 0, "paid_at": null, "post_fixed_amount": 0, "pre_fixed_amount": 106.92260459, "principal_amortization_amount": 306.50739541, "qr_code_key": null, "qr_code_url": null, "renegotiation_proposal_key": null, "tax_amount": 0.75400819, "total_accrual_amount": null, "total_amount": 413.43, "total_paid_amount": 0, "workdays": 20 }, { "accrual_reference_date": null, "additional_costs": [], "advanced_paid_amount": 0, "bank_slip_key": null, "business_due_date": "2026-06-08", "calendar_days": 31, "digitable_line": null, "due_date": "2026-06-07", "due_interest": 0, "due_principal": 710.21260459, "fine_amount": null, "has_interest": true, "installment_history": [], "installment_key": "2bcfe19e-9847-4c8f-be80-17f646a897c4", "installment_number": 2, "installment_payment": [], "installment_status": "created", "installment_type": "principal", "original_due_principal": 710.21260459, "original_pre_fixed_amount": 77.30856978, "original_principal_amortization_amount": 336.12143022, "original_total_amount": 413.43, "paid_amount": 0, "paid_at": null, "post_fixed_amount": 0, "pre_fixed_amount": 77.30856978, "principal_amortization_amount": 336.12143022, "qr_code_key": null, "qr_code_url": null, "renegotiation_proposal_key": null, "tax_amount": 1.68127939, "total_accrual_amount": null, "total_amount": 413.43, "total_paid_amount": 0, "workdays": 20 }, { "accrual_reference_date": null, "additional_costs": [], "advanced_paid_amount": 0, "bank_slip_key": null, "business_due_date": "2026-07-07", "calendar_days": 30, "digitable_line": null, "due_date": "2026-07-07", "due_interest": 0, "due_principal": 374.09117437, "fine_amount": null, "has_interest": true, "installment_history": [], "installment_key": "7cf785c9-b6cf-4e9b-9c09-61d917bc72b8", "installment_number": 3, "installment_payment": [], "installment_status": "created", "installment_type": "principal", "original_due_principal": 374.09117437, "original_pre_fixed_amount": 39.33882563, "original_principal_amortization_amount": 374.09117437, "original_total_amount": 413.43, "paid_amount": 0, "paid_at": null, "post_fixed_amount": 0, "pre_fixed_amount": 39.33882563, "principal_amortization_amount": 374.09117437, "qr_code_key": null, "qr_code_url": null, "renegotiation_proposal_key": null, "tax_amount": 2.79146834, "total_accrual_amount": null, "total_amount": 413.43, "total_paid_amount": 0, "workdays": 22 } ], "total_pre_fixed_amount": 223.57 } } ``` :::info Note - The present value of the operations listed in `refinanced_credit_operations` will be automatically retained to settle the previous contracts - Only the surplus (difference between the disbursed amount and the retained amount) will be released to the borrower's account - After creation, the refinanced contracts will be automatically settled - The issuance webhooks (signature, disbursement, cancellation) follow the same pattern described in the [Issuance Webhooks](../emissao/webhooks) section ::: --- # Introduction - BNPL Refinancing URL: /en/documentation/manual_bnpl_full/refinanciamento/introducao ## Summary Refinancing consists of generating a new credit contract to settle a previous one. The flow works the same way as a simple debt issuance, however, when the operation values are provided, the sum of the present value of the previous contracts will be retained and only the surplus, if any, will be released to the borrower's account. ## Refinancing Flow 1. **Present value inquiry**: Query the present value of the original operation to determine the amount needed for settlement 2. **Simulation**: Simulate the refinancing with the new operation data and the reference to the original operation 3. **Creation**: Create the refinancing by providing the list of operations to be settled in `refinanced_credit_operations` :::info Important The payload used for both simulation and creation of a refinancing is the same as a simple debt, with the addition of the list of operations to be settled in **`refinanced_credit_operations`**. ::: --- # Simulation - BNPL Refinancing URL: /en/documentation/manual_bnpl_full/refinanciamento/simulacao # Simulation - BNPL Refinancing ## Summary Before creating a refinancing, you can simulate the values of the new operation. The simulation uses the same payload as a simple debt simulation, with the addition of the `refinanced_credit_operations` field. ## Request ENDPOINT /debt_simulation METHOD POST Request Body ```json { "borrower": { "person_type": "natural" }, "refinanced_credit_operations": [ { "operation_key": "72760166-4ddf-41fb-8a8c-605f8f4fc35c" } ], "financial": { "disbursed_amount": 1007.63, "interest_type": "pre_price_days", "credit_operation_type": "ccb", "annual_interest_rate": 2.32, "disbursement_date": "2026-04-07", "interest_grace_period": 0, "principal_grace_period": 0, "number_of_installments": 3, "fine_configuration": { "contract_fine_rate": 0.02, "interest_base": "calendar_days", "monthly_rate": 0.01 } } } ``` ### Body Params | Field | Type | Description | |---|---|---| | **borrower*** | object | Borrower data (minimum: `person_type`) | | **refinanced_credit_operations*** | array | List of operations to be refinanced | | **financial*** | object | Financial data for the new operation | ### refinanced_credit_operations Object | Field | Type | Description | |---|---|---| | `operation_key`* | string | Key of the operation to be refinanced (DEBT-KEY) | ## Response STATUS 200 Response Body ```json { "type": "debt", "key": "daa5173d-ae44-44c5-87bc-f9115cfbcaa1", "status": "finished", "event_datetime": "2026-04-08 00:36:02", "data": { "interest_type": "pre_price_days", "credit_operation_type": "ccb", "interest_grace_period": 0, "interest_payment_month_period": 1, "principal_grace_period": 0, "principal_amortization_month_period": 1, "operation_type": "settlement_refinancing", "prefixed_interest_rate": { "interest_base": "calendar_days_365", "annual_rate": 2.32, "monthly_rate": 0.1051676747, "daily_rate": 0.0032929847 }, "issue_date": "2026-04-07", "number_of_installments": 3, "requester_key": "78287247-947d-4730-9bd1-7efb068175b6", "final_disbursement_amount": 0.01, "refinanced_credit_operations": [ { "refinanced_credit_operation_key": "72760166-4ddf-41fb-8a8c-605f8f4fc35c", "refinanced_credit_operation_status": "pending_payment", "due_balance": 1007.62, "due_balance_reference_date": "2026-04-07", "original_deadline": 61 } ], "total_pre_fixed_amount": 220.27, "iof_amount": 9.09, "cet": 0.1103, "annual_cet": 2.5111, "disbursement_date": "2026-04-07", "installments": [ { "calendar_days": 30, "workdays": 20, "business_due_date": "2026-05-07", "due_date": "2026-05-07", "due_principal": 1016.72, "has_interest": true, "post_fixed_amount": 0, "pre_fixed_amount": 105.38950323, "tax_amount": 0.75507362, "total_amount": 412.33, "principal_amortization_amount": 306.94049677, "installment_number": 1 }, { "calendar_days": 31, "workdays": 20, "business_due_date": "2026-06-08", "due_date": "2026-06-07", "due_principal": 709.77950323, "has_interest": true, "post_fixed_amount": 0, "pre_fixed_amount": 76.15320432, "tax_amount": 1.68155633, "total_amount": 412.33, "principal_amortization_amount": 336.17679568, "installment_number": 2 }, { "calendar_days": 30, "workdays": 22, "business_due_date": "2026-07-07", "due_date": "2026-07-07", "due_principal": 373.60270755, "has_interest": true, "post_fixed_amount": 0, "pre_fixed_amount": 38.72729245, "tax_amount": 2.7878234, "total_amount": 412.33, "principal_amortization_amount": 373.60270755, "installment_number": 3 } ], "external_contract_fees": [ { "fee_type": "tac", "amount_type": "absolute", "amount": 0, "fee_amount": 0, "tax_amount": 0, "net_fee_amount": 0 } ], "contract_fee_amount": 3.05, "external_contract_fee_amount": 0, "net_external_contract_fee_amount": 0, "contract_fees": [ { "fee_type": "spread", "amount_type": "percentage", "amount": 0.3, "fee_amount": 3.05 } ], "issue_amount": 1016.72, "disbursed_issue_amount": 1007.63, "assignment_amount": 1019.77 } } ``` --- # Scenarios - BNPL Batch Renegotiation URL: /en/documentation/manual_bnpl_full/renegociacao/cenarios ## Overview This document presents the main batch renegotiation scenarios for BNPL operations. All scenarios use `amortization_type: "installment_payment"` and allow applying individual discounts per installment through the `discount_amount` field in each installment object. :::info Per-Installment Discount Logic You can apply different discounts to each installment individually. Simply add the `discount_amount` field (absolute value in BRL) inside the desired installment object. Installments without the `discount_amount` field will be charged at the full present value. ::: --- ## Scenario 1: 1 Installment Loan - Standard Payment The borrower has a 1-installment BNPL loan and wants to settle it at the present value. ### Payload Example ```json { "payment_type": "pix", "amortization_type": "installment_payment", "proposal_due_date": "2026-04-10", "discount_percentage": 0, "reference_date": "2026-04-10", "request_control_key": "3571e292-3a83-4011-904d-20ee963022ef", "operations": [ { "debt_key": "bf1175f4-750d-42b9-b264-5e7cd8c1c189", "installments": [ { "installment_key": "0298c572-7b6b-4db0-88d6-4bf1622d3e2d" } ] } ] } ``` --- ## Scenario 2: 1 Installment Loan - Interest Free Payment The borrower has a 1-installment BNPL loan and negotiates an interest-free payment. The discount applied corresponds to the interest amount of the installment. ### Payload Example ```json { "payment_type": "pix", "amortization_type": "installment_payment", "proposal_due_date": "2026-04-10", "discount_percentage": 0, "reference_date": "2026-04-10", "request_control_key": "b2c3d4e5-f6a7-8901-bcde-f12345678901", "operations": [ { "debt_key": "bf1175f4-750d-42b9-b264-5e7cd8c1c189", "installments": [ { "installment_key": "0298c572-7b6b-4db0-88d6-4bf1622d3e2d", "discount_amount": 54.19 } ] } ] } ``` :::info Note The `discount_amount` value (54.19) corresponds to the interest amount (`pre_fixed_amount`) of the installment. This way, the borrower only pays the principal amount. ::: --- ## Scenario 3: 1 Installment Loan - Interest + IOF Free Payment The borrower has a 1-installment BNPL loan and negotiates a payment without interest and without IOF. The discount applied corresponds to the sum of interest and IOF of the installment. ### Payload Example ```json { "payment_type": "pix", "amortization_type": "installment_payment", "proposal_due_date": "2026-04-10", "discount_percentage": 0, "reference_date": "2026-04-10", "request_control_key": "c3d4e5f6-a7b8-9012-cdef-123456789012", "operations": [ { "debt_key": "bf1175f4-750d-42b9-b264-5e7cd8c1c189", "installments": [ { "installment_key": "0298c572-7b6b-4db0-88d6-4bf1622d3e2d", "discount_amount": 55.44 } ] } ] } ``` :::info Note The `discount_amount` value (55.44) corresponds to the sum of interest (`pre_fixed_amount`: 54.19) + IOF (`tax_amount`: 1.25) of the installment. This way, the borrower only pays the principal amortization amount. ::: --- ## Scenario 4: Multiple Installments with Individual Discount The borrower has a BNPL loan with multiple installments and negotiates different discounts for specific installments. Installments without the `discount_amount` field are charged at the full present value. ### Payload Example ```json { "payment_type": "pix", "amortization_type": "installment_payment", "proposal_due_date": "2026-04-10", "discount_percentage": 0, "reference_date": "2026-04-10", "request_control_key": "d4e5f6a7-b8c9-0123-defa-234567890123", "operations": [ { "debt_key": "bf1175f4-750d-42b9-b264-5e7cd8c1c189", "installments": [ { "installment_key": "0298c572-7b6b-4db0-88d6-4bf1622d3e2d", "discount_amount": 20 }, { "installment_key": "5e267f58-0f55-4b12-9582-63e0e9e082a8" }, { "installment_key": "5be492bf-b637-4999-986d-ecf423cc5dd1" }, { "installment_key": "15abfbfd-8608-45e9-abbb-a04c021dcf7b", "discount_amount": 10 }, { "installment_key": "c8eb83b3-5b0d-4326-947c-79279cdce2d6" } ] } ] } ``` :::info Note In this example: - Installment 1: R$ 20.00 discount - Installment 2: no discount (full present value) - Installment 3: no discount (full present value) - Installment 4: R$ 10.00 discount - Installment 5: no discount (full present value) ::: --- ## Scenario 5: Overdue Installment Payment The borrower has overdue installments and wants to settle them. Overdue installments already include automatically calculated fines and penalty interest. Individual discounts can be applied to reduce the amount. ### Payload Example ```json { "payment_type": "bank_slip", "amortization_type": "installment_payment", "proposal_due_date": "2026-04-10", "discount_percentage": 0, "reference_date": "2026-04-10", "request_control_key": "e5f6a7b8-c9d0-1234-efab-345678901234", "operations": [ { "debt_key": "bf1175f4-750d-42b9-b264-5e7cd8c1c189", "installments": [ { "installment_key": "0298c572-7b6b-4db0-88d6-4bf1622d3e2d", "discount_amount": 15 }, { "installment_key": "5e267f58-0f55-4b12-9582-63e0e9e082a8", "discount_amount": 15 } ] } ] } ``` :::caution Attention For overdue installments, the present value already includes fines (`fine_amount`) and penalty interest calculated automatically based on the contract's `fine_configuration`. The `discount_amount` is applied on this total value. ::: --- ## Scenario 6: Multiple Operations with Individual Per-Installment Discount The borrower has BNPL loans across different operations and wants to settle installments from all of them in a single payment, with individual discounts. ### Payload Example ```json { "payment_type": "pix", "amortization_type": "installment_payment", "proposal_due_date": "2026-04-10", "discount_percentage": 0, "reference_date": "2026-04-10", "request_control_key": "f6a7b8c9-d0e1-2345-fabc-456789012345", "operations": [ { "debt_key": "bf1175f4-750d-42b9-b264-5e7cd8c1c189", "installments": [ { "installment_key": "0298c572-7b6b-4db0-88d6-4bf1622d3e2d", "discount_amount": 20 }, { "installment_key": "5e267f58-0f55-4b12-9582-63e0e9e082a8" } ] }, { "debt_key": "a2c3d4e5-860f-4b7a-9c1d-2e3f4a5b6c7d", "installments": [ { "installment_key": "7b8c9d0e-1f2a-3b4c-5d6e-7f8a9b0c1d2e", "discount_amount": 30 } ] } ] } ``` --- ## Installments Object - Discount Field | Field | Type | Description | Required | |---|---|---|---| | `installment_key`* | string | Key of the installment to be renegotiated | Yes | | `discount_amount` | float | Discount amount in BRL (R$) applied individually to the installment | No | :::info About the discount_amount field - The `discount_amount` field is **optional** and can be provided for any installment - The value is an **absolute discount in BRL** (not a percentage) - Installments without the `discount_amount` field are charged at the **full present value** - The discount is applied on the installment's present value at the `reference_date` ::: --- ## Scenarios Summary Table | Scenario | Description | Discount | |---|---|---| | 1 installment - standard | Payment at present value | No discount | | 1 installment - interest free | Discount = interest amount | `discount_amount` = `pre_fixed_amount` | | 1 installment - interest + IOF free | Discount = interest + IOF | `discount_amount` = `pre_fixed_amount` + `tax_amount` | | Multiple installments | Individual discounts per installment | `discount_amount` per installment | | Overdue installments | Overdue installments with fines/penalties | Optional `discount_amount` | | Multiple operations | Different operations in one batch | `discount_amount` per installment | --- ## Important Rules :::caution Batch Renegotiation Rules - All operations must belong to the **same issuer** and the same **integration key** - Limit of **50 operations** per batch - A single payment method (bank slip/Pix) is generated for the total batch amount - If an installment included in the batch is paid externally before confirmation, the batch is **rejected** - If payment is not made by the `proposal_due_date`, the batch is **rejected** - The `amortization_type` used is always `installment_payment` - The `discount_amount` field is applied **individually per installment** ::: --- # Inquiry - BNPL Batch Renegotiation URL: /en/documentation/manual_bnpl_full/renegociacao/consulta # Inquiry - BNPL Batch Renegotiation ## Overview You can query the status and details of a batch renegotiation proposal using the `batch_proposal_key` or the `request_control_key`. --- ## Query by Batch Proposal Key ENDPOINT /renegotiation/batch_proposal/ BATCH-PROPOSAL-KEY METHOD GET ### Path Params | Field | Type | Description | Max. Char. | |---|---|---|---| | `batch_proposal_key`* | string | Batch renegotiation proposal key | UUID | ### Response STATUS 200 Response Body ```json { "batch_proposal_key": "ff5ad6dd-2087-4850-a3e8-b37634448b4e", "discount_percentage": 0, "discount_amount": 0, "amortization_type": "installment_payment", "payment_amount": 517.88, "requester_name": "Dante Ltda", "requester_key": "78287247-947d-4730-9bd1-7efb068175b6", "issuer_name": "Dante Ferrarini", "reference_date": "2026-04-08", "issuer_document_number": "31057466093", "batch_proposal_status": "pending_payment", "proposal_due_date": "2026-04-15", "payment_type": "pix", "request_control_key": "94b31045-c8e7-45be-a88d-2ae25c5df5db", "origin_key": null, "operations": [ { "requester_key": "78287247-947d-4730-9bd1-7efb068175b6", "contract_number": "DWF1761222116", "payment_amount": 517.88, "discount_amount": 0, "origin_key": null, "affected_installments": [ { "installment_key": "1dea396f-beb1-4df3-9822-35800b4c095a", "due_date": "2026-05-07", "principal_amount": 491.49, "interest_amount": 52.4, "fine_amount": 0, "total_amount": 543.89, "present_amount": 517.88, "paid_amount": 517.88, "principal_amortization_payment_amount": 491.49, "prefixed_interest_payment_amount": 26.39, "fine_payment_amount": 0, "discount_amount": 0 } ], "remaining_installments": [ { "installment_key": "370e73d1-55d8-431e-9b22-d08fb8297999", "due_date": "2026-06-07", "principal_amount": 516.13, "interest_amount": 27.76, "fine_amount": 0, "total_amount": 543.89 } ], "debt_key": "72760166-4ddf-41fb-8a8c-605f8f4fc35c" } ], "payment": { "digitable_line": null, "qr_code_url": "00020126930014br.gov.bcb.pix2571qrcode-h.sandbox.qitech.app/bacen/cobv/acaeb341e1264cde99b93e247e12b3725204000053039865802BR5925QISOCIEDADEDECREDITODIRET6008SaoPaulo61080145200062070503***63043AD0", "qr_code_key": "acaeb341-e126-4cde-99b9-3e247e12b372", "bank_slip_key": null, "paid_method_type": "pix", "source_account_key": null, "payment_data": { "creditor_bank_account_key": "6108dd45-580d-48c4-b3bb-74c1e843be49", "batch_renegotiation_proposal_key": "ff5ad6dd-2087-4850-a3e8-b37634448b4e" } } } ``` --- ## Query by Request Control Key ENDPOINT /renegotiation/batch_proposal/request_control_key/ REQUEST-CONTROL-KEY METHOD GET ### Path Params | Field | Type | Description | Max. Char. | |---|---|---|---| | `request_control_key`* | string | Request control key | UUID | ### Response The response follows the same format as the query by `batch_proposal_key`. --- ## List Batch Renegotiations ENDPOINT /renegotiation/batch_proposal METHOD GET ### Query Params | Field | Type | Description | |---|---|---| | `batch_proposal_status` | string | Filter by batch proposal status | | `issuer_document_number` | string | Filter by issuer CPF/CNPJ | | `request_control_key` | string | Filter by control key | ### Response STATUS 200 Response Body ```json { "data": [ { "batch_proposal_key": "ff5ad6dd-2087-4850-a3e8-b37634448b4e", "discount_percentage": 0, "discount_amount": 0, "amortization_type": "installment_payment", "payment_amount": 517.88, "requester_name": "Dante Ltda", "requester_key": "78287247-947d-4730-9bd1-7efb068175b6", "issuer_name": "Dante Ferrarini", "reference_date": "2026-04-08", "issuer_document_number": "31057466093", "batch_proposal_status": "pending_payment", "proposal_due_date": "2026-04-15", "payment_type": "pix", "request_control_key": "94b31045-c8e7-45be-a88d-2ae25c5df5db", "origin_key": null } ], "pagination": { "current_page": 1, "next_page": 2, "rows_per_page": 10, "total_pages": 150, "total_rows": 1495 } } ``` --- ## Cancel a Batch Renegotiation ENDPOINT /renegotiation/batch_proposal/ BATCH-PROPOSAL-KEY METHOD DELETE ### Path Params | Field | Type | Description | Max. Char. | |---|---|---|---| | `batch_proposal_key`* | string | Key of the batch renegotiation proposal to be canceled | UUID | ### Response STATUS 204 Response Body ```json {} ``` :::caution Attention Only proposals with status `pending_payment` can be canceled. ::: --- # Renegotiation with IOF Spread and Interest-Only Discount - BNPL URL: /en/documentation/manual_bnpl_full/renegociacao/iof-spread-e-desconto-juros ## Overview This page documents the batch renegotiation flow for BNPL operations where the credit operation was created with `iof_charge_method: "spread"`. In this model, the IOF is **not** financed in the installments — it is calculated normally but added to the `assignment_amount` (assignment value), not to the borrower's installments. Additionally, the field `discount_validation: "only_interest_discount"` can be used in each operation within the `operations[]` array to restrict discounts to the interest portion only. If the discount exceeds the interest and reaches the principal or fine, the API will return the error `InvalidDiscountAmountOnlyInterestDiscount`. The flow uses the batch endpoints: simulation (`POST /renegotiation/batch_proposal_simulation`) followed by the proposal (`POST /renegotiation/batch_proposal`). The `discount_validation` field is set **per operation** in the `operations[]` array, not at the root level of the payload. :::info Note — iof_charge_method The `iof_charge_method` field is set at the time of **credit operation creation** (credit-operation-api), not during renegotiation. When `iof_charge_method: "spread"`: - The IOF is calculated normally (base IOF + additional IOF), but is **not** deducted from the borrower's installments - The IOF is added to the `assignment_amount` — meaning the IOF cost is reflected in the assignment value - The borrower's installments are "clean" of IOF The three possible values are: - `"financed"` **(default)** — IOF is financed in the installments (deducted from the amount credited to the borrower) - `"spread"` — IOF is added to the assignment value (`assignment_amount`), not to the installments - `"free"` — No IOF (`total_iof = 0`) ::: :::caution Attention — discount_validation When `discount_validation: "only_interest_discount"` is set on an operation, the system validates that the discount applied to each installment does **not** include principal amortization (`discount_principal_amortization_amount`) or fine (`discount_fine_amount`). Only interest (prefixed interest) can be discounted. If any installment has a discount that reaches the principal or fine, the API returns the error `InvalidDiscountAmountOnlyInterestDiscount` and the entire request fails. ::: ## Step 1: Batch Simulation ENDPOINT /renegotiation/batch_proposal_simulation METHOD POST :::warning Attention The fields `discount_amount` and `discount_percentage` **CANNOT** be sent together in the same payload (root level). ::: Request Body ```json { "amortization_type": "installment_payment", "reference_date": "2026-04-20", "discount_percentage": 0.0, "operations": [ { "debt_key": "3571e292-3a83-4011-904d-20ee963022ef", "discount_validation": "only_interest_discount", "installments": [ { "installment_key": "f9e8d7c6-b5a4-3210-fedc-ba9876543210" } ] } ] } ``` ### Body Params | Field | Type | Description | Max. Char. | |---|---|---|---| | `amortization_type`* | string | Amortization type | **[Amortization Type Enumerators](#amortization-type-enumerators)** | | `reference_date`* | string | Reference date for present value calculation (must be D+1) | 10 | | `discount_percentage` | float | Discount percentage on the present value ((1 - percentage) x Present Value) | 10 | | `discount_amount` | float | Discount amount applied on the present value | 10 | | `operations`* | array | List of operations to be renegotiated | **[Operations Object](#operations-object)** | ### Operations Object | Field | Type | Description | Max. Char. | |---|---|---|---| | `debt_key`* | string | Unique key of the credit operation (DEBT-KEY) | UUID | | `discount_validation` | string | Discount validation rule. When set to `"only_interest_discount"`, the applied discount cannot exceed the interest portion. | **[Discount Validation Enumerators](#discount-validation-enumerators)** | | `installments`* | array | Installments to be renegotiated | **[Installments Object](#installments-object)** | ### Installments Object | Field | Type | Description | Max. Char. | |---|---|---|---| | `installment_key`* | string | Key of the installment to be renegotiated | UUID | | `paid_amount` | float | Amount paid (or allocated) on the installment, in BRL (R$). Required when `amortization_type` is **`present_amount`**. | 15,2 | | `discount_amount` | float | Discount amount in BRL (R$) on the installment. Required when `amortization_type` is **`present_amount`** (use `0` if there is no discount). Optional for other types. | 15,2 | ### Discount Validation Enumerators | Field | Description | |---|---| | `only_interest_discount` | Validates that the discount applied to each installment does not exceed the interest amount. If the discount reaches the principal or fine, the API returns the error `InvalidDiscountAmountOnlyInterestDiscount`. | ### Amortization Type Enumerators | Field | Description | |---|---| | **installment_payment** | Renegotiation for payment of specific installments sent in the payload. Requires the `installment_key` of each installment. | | **overdue_installment_payment** | Renegotiation targeted at overdue installment payment. Requires the `installment_key` of each installment. | | **present_amount** | Simulation with per-installment present value. In each `installments[]`, `installment_key`, **`paid_amount`** and **`discount_amount`** are required. | ## Response STATUS 200 Response Body ```json { "batch_proposal_key": "7423c701-3578-4733-8f30-81ab60afdb6d", "discount_percentage": 0, "discount_amount": 0, "amortization_type": "installment_payment", "payment_amount": 517.88, "requester_name": "Empresa Exemplo Ltda", "requester_key": "78287247-947d-4730-9bd1-7efb068175b6", "issuer_name": "João da Silva", "reference_date": "2026-04-20", "issuer_document_number": "31057466093", "operations": [ { "requester_key": "78287247-947d-4730-9bd1-7efb068175b6", "contract_number": "DWF1761222116", "payment_amount": 517.88, "discount_amount": 0, "origin_key": null, "affected_installments": [ { "installment_key": "f9e8d7c6-b5a4-3210-fedc-ba9876543210", "due_date": "2026-05-07", "principal_amount": 491.49, "interest_amount": 52.40, "fine_amount": 0, "total_amount": 543.89, "present_amount": 517.88, "paid_amount": 517.88, "principal_amortization_payment_amount": 491.49, "prefixed_interest_payment_amount": 26.39, "fine_payment_amount": 0, "discount_amount": 0 } ], "remaining_installments": [ { "installment_key": "370e73d1-55d8-431e-9b22-d08fb8297999", "due_date": "2026-06-07", "principal_amount": 516.13, "interest_amount": 27.76, "fine_amount": 0, "total_amount": 543.89 } ], "debt_key": "3571e292-3a83-4011-904d-20ee963022ef" } ] } ``` ## Step 2: Batch Proposal ENDPOINT /renegotiation/batch_proposal METHOD POST :::warning Attention The fields `discount_amount` and `discount_percentage` **CANNOT** be sent together in the same payload (root level). ::: Request Body ```json { "amortization_type": "installment_payment", "reference_date": "2026-04-20", "proposal_due_date": "2026-04-27", "payment_type": "pix", "discount_percentage": 0.0, "request_control_key": "94b31045-c8e7-45be-a88d-2ae25c5df5db", "operations": [ { "debt_key": "3571e292-3a83-4011-904d-20ee963022ef", "discount_validation": "only_interest_discount", "installments": [ { "installment_key": "f9e8d7c6-b5a4-3210-fedc-ba9876543210" } ] } ] } ``` ### Body Params | Field | Type | Description | Max. Char. | |---|---|---|---| | `amortization_type`* | string | Amortization type | **[Amortization Type Enumerators](#amortization-type-enumerators-1)** | | `reference_date`* | string | Reference date for present value calculation (D+1) | 10 | | `proposal_due_date`* | string | Due date for the renegotiation proposal | 10 | | `payment_type`* | string | Payment type | **[Payment Type Enumerators](#payment-type-enumerators)** | | `request_control_key` | string | Control key for tracking and unique identification (optional) | UUID | | `discount_percentage` | float | Discount percentage on the present value | 10 | | `discount_amount` | float | Discount amount on the present value | 10 | | `operations`* | array | List of operations to be renegotiated | **[Operations Object](#operations-object-1)** | ### Operations Object | Field | Type | Description | Max. Char. | |---|---|---|---| | `debt_key`* | string | Unique key of the credit operation (DEBT-KEY) | UUID | | `discount_validation` | string | Discount validation rule. When set to `"only_interest_discount"`, the applied discount cannot exceed the interest portion. | **[Discount Validation Enumerators](#discount-validation-enumerators-1)** | | `installments`* | array | Installments to be renegotiated | **[Installments Object](#installments-object-1)** | ### Installments Object | Field | Type | Description | Max. Char. | |---|---|---|---| | `installment_key`* | string | Key of the installment to be renegotiated | UUID | | `paid_amount` | float | Amount paid (or allocated) on the installment, in BRL (R$). Required when `amortization_type` is **`present_amount`**. | 15,2 | | `discount_amount` | float | Discount amount in BRL (R$) applied to the installment. Required when `amortization_type` is **`present_amount`** (use `0` if there is no discount). For other amortization types, it remains optional per installment. | 15,2 | ### Discount Validation Enumerators | Field | Description | |---|---| | `only_interest_discount` | Validates that the discount applied to each installment does not exceed the interest amount. If the discount reaches the principal or fine, the API returns the error `InvalidDiscountAmountOnlyInterestDiscount`. | ### Payment Type Enumerators | Field | Description | |---|---| | `bank_slip` | Payment via bank slip (generates bank slip and Pix) | | `pix` | Payment via Pix (generates Pix only) | | `manual` | Manual payment (does not generate a payment method) | ### Amortization Type Enumerators | Field | Description | |---|---| | **installment_payment** | Renegotiation for payment of specific installments. Requires the `installment_key` of each installment. | | **overdue_installment_payment** | Renegotiation targeted at overdue installment payment. Requires the `installment_key` of each installment. | | **present_amount** | Renegotiation with per-installment present value composition. In each item of `installments[]`, `installment_key`, **`paid_amount`** and **`discount_amount`** are required. | ## Response STATUS 201 Response Body ```json { "batch_proposal_key": "ff5ad6dd-2087-4850-a3e8-b37634448b4e", "discount_percentage": 0, "discount_amount": 0, "amortization_type": "installment_payment", "payment_amount": 517.88, "requester_name": "Empresa Exemplo Ltda", "requester_key": "78287247-947d-4730-9bd1-7efb068175b6", "issuer_name": "João da Silva", "reference_date": "2026-04-20", "issuer_document_number": "31057466093", "batch_proposal_status": "pending_payment", "proposal_due_date": "2026-04-27", "payment_type": "pix", "request_control_key": "94b31045-c8e7-45be-a88d-2ae25c5df5db", "origin_key": null, "operations": [ { "requester_key": "78287247-947d-4730-9bd1-7efb068175b6", "contract_number": "DWF1761222116", "payment_amount": 517.88, "discount_amount": 0, "origin_key": null, "affected_installments": [ { "installment_key": "f9e8d7c6-b5a4-3210-fedc-ba9876543210", "due_date": "2026-05-07", "principal_amount": 491.49, "interest_amount": 52.40, "fine_amount": 0, "total_amount": 543.89, "present_amount": 517.88, "paid_amount": 517.88, "principal_amortization_payment_amount": 491.49, "prefixed_interest_payment_amount": 26.39, "fine_payment_amount": 0, "discount_amount": 0 } ], "remaining_installments": [ { "installment_key": "370e73d1-55d8-431e-9b22-d08fb8297999", "due_date": "2026-06-07", "principal_amount": 516.13, "interest_amount": 27.76, "fine_amount": 0, "total_amount": 543.89 } ], "debt_key": "3571e292-3a83-4011-904d-20ee963022ef" } ], "payment": { "digitable_line": null, "qr_code_url": "00020126930014br.gov.bcb.pix2571qrcode-h.sandbox.qitech.app/bacen/cobv/acaeb341e1264cde99b93e247e12b3725204000053039865802BR5925QISOCIEDADEDECREDITODIRET6008SaoPaulo61080145200062070503***63043AD0", "qr_code_key": "acaeb341-e126-4cde-99b9-3e247e12b372", "bank_slip_key": null, "paid_method_type": "pix", "source_account_key": null, "payment_data": { "creditor_bank_account_key": "6108dd45-580d-48c4-b3bb-74c1e843be49", "batch_renegotiation_proposal_key": "ff5ad6dd-2087-4850-a3e8-b37634448b4e" } } } ``` :::info Important Save the **batch_proposal_key** returned in the response. It will be needed to check the batch renegotiation status and to receive payment webhooks. ::: ## Error: Discount Exceeds Interest When `discount_validation: "only_interest_discount"` is set on an operation and the applied discount amount exceeds the interest portion, the API returns the following error: Error Response ```json { "code": "InvalidDiscountAmountOnlyInterestDiscount", "message": "Discount amount must be only interest discount" } ``` The validation is performed **per installment** during amortization processing. If any individual installment has a discount whose value includes principal amortization (`discount_principal_amortization_amount > 0`) or fine (`discount_fine_amount > 0`), the entire request is rejected. ## Assignment :::info Note After the proposal is paid, the assignment step (`POST /credit_operations/assign`) creates a formal transfer of the credit operation. This is a separate endpoint from the **credit-operation-api**. When the credit operation has `iof_charge_method: "spread"`, the calculated `assignment_amount` includes the IOF that was **not** financed in the installments. In other words, the assignment value reflects the total cost including the separate IOF. ::: --- # Batch Renegotiation Proposal - BNPL URL: /en/documentation/manual_bnpl_full/renegociacao/proposta # Batch Renegotiation Proposal - BNPL ## Overview After simulating the values, you can create a batch renegotiation proposal for multiple BNPL operations. The proposal generates a single payment method (bank slip and/or Pix) that covers all operations included in the batch. For the **`present_amount`** amortization type, each installment informed in `operations[].installments[]` must include **`paid_amount`** (amount paid/allocated to that installment) and **`discount_amount`** (discount in BRL applied to the installment), in addition to **`installment_key`**. :::caution Attention Batch renegotiation can only be created with operations from the same issuer and the same integration key. There is a limit of **50 operations** per batch renegotiation. ::: ## Request ENDPOINT /renegotiation/batch_proposal METHOD POST :::warning Attention The fields `discount_amount` and `discount_percentage` **CANNOT** be sent together in the same payload (root level). ::: :::info Note At the root of the body, `discount_amount` and `discount_percentage` are alternatives for a global discount on the present value. The **`paid_amount`** and **`discount_amount`** fields inside each object of `operations[].installments[]` define the per-installment composition when `amortization_type` is **`present_amount`** (they are required in this mode and do not conflict with the root-level rule). ::: Request Body ```json { "amortization_type": "present_amount", "reference_date": "2026-04-08", "proposal_due_date": "2026-04-15", "discount_percentage": 0.0, "payment_type": "pix", "request_control_key": "94b31045-c8e7-45be-a88d-2ae25c5df5db", "operations": [ { "debt_key": "1baea8a0-0fca-4f7c-8857-a227d4da72f8", "installments": [ { "installment_key": "ca5741c7-99a2-42e7-92a1-9328a36e4e88", "paid_amount": 500, "discount_amount": 50 } ] }, { "debt_key": "2cbfb9b1-1fdb-5f8d-9967-b338e5eb83f9", "installments": [ { "installment_key": "2ef25ed8-7124-44f5-9e3d-1d1a7196166e", "paid_amount": 150, "discount_amount": 10 } ] } ] } ``` ### Body Params | Field | Type | Description | Max. Char. | |---|---|---|---| | `amortization_type`* | string | Amortization type | **[Amortization Type Enumerators](#amortization-type-enumerators)** | | `reference_date`* | string | Reference date for present value calculation (D+1) | 10 | | `proposal_due_date`* | string | Due date for the renegotiation proposal | 10 | | `payment_type`* | string | Payment type | **[Payment Type Enumerators](#payment-type-enumerators)** | | `request_control_key` | string | Control key for tracking and unique identification (optional) | UUID | | `discount_percentage` | float | Discount percentage on the present value | 10 | | `discount_amount` | float | Discount amount on the present value | 10 | | `operations`* | array | List of operations to be renegotiated | **[Operations Object](#operations-object)** | ### Operations Object | Field | Type | Description | Max. Char. | |---|---|---|---| | `debt_key`* | string | Unique key of the credit operation (DEBT-KEY) | UUID | | `installments`* | array | Installments to be renegotiated | **[Installments Object](#installments-object)** | ### Installments Object | Field | Type | Description | Max. Char. | |---|---|---|---| | `installment_key`* | string | Key of the installment to be renegotiated | UUID | | `paid_amount` | float | Amount paid (or allocated) on the installment, in BRL (R$). Required when `amortization_type` is **`present_amount`**. | 15,2 | | `discount_amount` | float | Discount amount in BRL (R$) applied to the installment. Required when `amortization_type` is **`present_amount`** (use `0` if there is no discount). For other amortization types, it remains optional per installment. | 15,2 | ### Payment Type Enumerators | Field | Description | |---|---| | `bank_slip` | Payment via bank slip (generates bank slip and Pix) | | `pix` | Payment via Pix (generates Pix only) | | `manual` | Manual payment (does not generate a payment method) | ### Amortization Type Enumerators | Field | Description | |---|---| | **present_amount** | Renegotiation with per-installment present value composition. In each item of `installments[]`, `installment_key`, **`paid_amount`** and **`discount_amount`** are required. | | **installment_payment** | Renegotiation for payment of specific installments. Requires the `installment_key` of each installment. | | **overdue_installment_payment** | Renegotiation targeted at overdue installment payment. Requires the `installment_key` of each installment. | ## Response STATUS 201 Response Body ```json { "batch_proposal_key": "ff5ad6dd-2087-4850-a3e8-b37634448b4e", "discount_percentage": 0, "discount_amount": 0, "amortization_type": "present_amount", "payment_amount": 517.88, "requester_name": "Dante Ltda", "requester_key": "78287247-947d-4730-9bd1-7efb068175b6", "issuer_name": "Dante Ferrarini", "reference_date": "2026-04-08", "issuer_document_number": "31057466093", "batch_proposal_status": "pending_payment", "proposal_due_date": "2026-04-15", "payment_type": "pix", "request_control_key": "94b31045-c8e7-45be-a88d-2ae25c5df5db", "origin_key": null, "operations": [ { "requester_key": "78287247-947d-4730-9bd1-7efb068175b6", "contract_number": "DWF1761222116", "payment_amount": 517.88, "discount_amount": 0, "origin_key": null, "affected_installments": [ { "installment_key": "1dea396f-beb1-4df3-9822-35800b4c095a", "due_date": "2026-05-07", "principal_amount": 491.49, "interest_amount": 52.4, "fine_amount": 0, "total_amount": 543.89, "present_amount": 517.88, "paid_amount": 517.88, "principal_amortization_payment_amount": 491.49, "prefixed_interest_payment_amount": 26.39, "fine_payment_amount": 0, "discount_amount": 0 } ], "remaining_installments": [ { "installment_key": "370e73d1-55d8-431e-9b22-d08fb8297999", "due_date": "2026-06-07", "principal_amount": 516.13, "interest_amount": 27.76, "fine_amount": 0, "total_amount": 543.89 } ], "debt_key": "72760166-4ddf-41fb-8a8c-605f8f4fc35c" } ], "payment": { "digitable_line": null, "qr_code_url": "00020126930014br.gov.bcb.pix2571qrcode-h.sandbox.qitech.app/bacen/cobv/acaeb341e1264cde99b93e247e12b3725204000053039865802BR5925QISOCIEDADEDECREDITODIRET6008SaoPaulo61080145200062070503***63043AD0", "qr_code_key": "acaeb341-e126-4cde-99b9-3e247e12b372", "bank_slip_key": null, "paid_method_type": "pix", "source_account_key": null, "payment_data": { "creditor_bank_account_key": "6108dd45-580d-48c4-b3bb-74c1e843be49", "batch_renegotiation_proposal_key": "ff5ad6dd-2087-4850-a3e8-b37634448b4e" } } } ``` :::info Important Save the **batch_proposal_key** returned in the response. It will be needed to check the batch renegotiation status and to receive payment webhooks. ::: --- # Simulation - BNPL Batch Renegotiation URL: /en/documentation/manual_bnpl_full/renegociacao/simulacao # Simulation - BNPL Batch Renegotiation ## Overview Before creating a renegotiation proposal, you can simulate the batch renegotiation values for BNPL operations. The simulation allows you to view the affected installments, discount values, and the final amount to be paid for multiple operations simultaneously. With **`amortization_type`** set to **`present_amount`**, send in each installment of `operations[].installments[]` the fields **`paid_amount`**, **`discount_amount`** and **`installment_key`**, just like in the batch proposal. :::caution Attention Batch renegotiation can only be created with operations from the same issuer and the same integration key. There is a limit of **50 operations** per batch renegotiation. ::: ## Request ENDPOINT /renegotiation/batch_proposal_simulation METHOD POST :::warning Attention The fields `discount_amount` and `discount_percentage` **CANNOT** be sent together in the same payload (root level). ::: :::info Note At the root level, `discount_amount` and `discount_percentage` are alternatives for a global discount. The **`paid_amount`** and **`discount_amount`** fields in `operations[].installments[]` are used with **`present_amount`** per installment and do not replace the root-level rule. ::: Request Body ```json { "amortization_type": "present_amount", "reference_date": "2026-04-08", "discount_percentage": 0.0, "operations": [ { "debt_key": "1baea8a0-0fca-4f7c-8857-a227d4da72f8", "installments": [ { "installment_key": "ca5741c7-99a2-42e7-92a1-9328a36e4e88", "paid_amount": 500, "discount_amount": 50 } ] }, { "debt_key": "2cbfb9b1-1fdb-5f8d-9967-b338e5eb83f9", "installments": [ { "installment_key": "2ef25ed8-7124-44f5-9e3d-1d1a7196166e", "paid_amount": 150, "discount_amount": 10 } ] } ] } ``` ### Body Params | Field | Type | Description | Max. Char. | |---|---|---|---| | `amortization_type`* | string | Amortization type | **[Amortization Type Enumerators](#amortization-type-enumerators)** | | `reference_date`* | string | Reference date for present value calculation (must be D+1) | 10 | | `discount_percentage` | float | Discount percentage on the present value ((1 - percentage) * Present Value) | 10 | | `discount_amount` | float | Discount amount applied to the present value | 10 | | `operations`* | array | List of operations to be renegotiated | **[Operations Object](#operations-object)** | ### Operations Object | Field | Type | Description | Max. Char. | |---|---|---|---| | `debt_key`* | string | Unique key of the credit operation (DEBT-KEY) | UUID | | `installments`* | array | Installments to be renegotiated | **[Installments Object](#installments-object)** | ### Installments Object | Field | Type | Description | Max. Char. | |---|---|---|---| | `installment_key`* | string | Key of the installment to be renegotiated | UUID | | `paid_amount` | float | Amount paid (or allocated) on the installment, in BRL (R$). Required when `amortization_type` is **`present_amount`**. | 15,2 | | `discount_amount` | float | Discount amount in BRL (R$) on the installment. Required when `amortization_type` is **`present_amount`** (use `0` if there is no discount). Optional for other types. | 15,2 | ### Amortization Type Enumerators | Field | Description | |---|---| | **present_amount** | Simulation with present value per installment. In each `installments[]`, `installment_key`, **`paid_amount`** and **`discount_amount`** are required. | | **installment_payment** | Renegotiation for payment of specific installments sent in the payload. Requires the `installment_key` of each installment. | | **overdue_installment_payment** | Renegotiation targeted at overdue installment payment. Requires the `installment_key` of each installment. | ## Response STATUS 200 Response Body ```json { "batch_proposal_key": "7423c701-3578-4733-8f30-81ab60afdb6d", "discount_percentage": 0, "discount_amount": 0, "amortization_type": "present_amount", "payment_amount": 517.88, "requester_name": "Dante Ltda", "requester_key": "78287247-947d-4730-9bd1-7efb068175b6", "issuer_name": "Dante Ferrarini", "reference_date": "2026-04-08", "issuer_document_number": "31057466093", "operations": [ { "requester_key": "78287247-947d-4730-9bd1-7efb068175b6", "contract_number": "DWF1761222116", "payment_amount": 517.88, "discount_amount": 0, "origin_key": null, "affected_installments": [ { "installment_key": "1dea396f-beb1-4df3-9822-35800b4c095a", "due_date": "2026-05-07", "principal_amount": 491.4903841, "interest_amount": 52.3996159, "fine_amount": 0, "total_amount": 543.89, "present_amount": 517.88, "paid_amount": 517.88, "principal_amortization_payment_amount": 491.49, "prefixed_interest_payment_amount": 26.39, "fine_payment_amount": 0, "discount_amount": 0 } ], "remaining_installments": [ { "installment_key": "370e73d1-55d8-431e-9b22-d08fb8297999", "due_date": "2026-06-07", "principal_amount": 516.1296159, "interest_amount": 27.7603841, "fine_amount": 0, "total_amount": 543.89 } ], "debt_key": "72760166-4ddf-41fb-8a8c-605f8f4fc35c" } ] } ``` ### Discount Fields Percentage discount ```json { "discount_percentage": 0.5 } ``` Absolute discount ```json { "discount_amount": 200 } ``` --- # Webhooks - BNPL Batch Renegotiation URL: /en/documentation/manual_bnpl_full/renegociacao/webhooks ## Overview After creating a batch renegotiation proposal, the system will send webhooks to notify about the payment or rejection of the proposal. :::danger Attention! Webhooks should not be strictly mapped. New fields may be added to the payload without prior notice. ::: ## Payment Webhook This webhook is sent when payment for the batch renegotiation proposal is confirmed. WEBHOOK_TYPE renegotiation.batch_proposal STATUS paid Webhook Body ```json { "webhook_type": "renegotiation.batch_proposal", "key": "", "event_datetime": "", "status": "paid", "data": { "paid_method_type": "", "paid_in": { "code_number": "", "ispb": "", "name": "" } } } ``` ### Payment Webhook Fields | Field | Type | Description | |---|---|---| | **webhook_type** | string | Webhook type: `renegotiation.batch_proposal` | | **key** | string | Batch renegotiation proposal key (BATCH-PROPOSAL-KEY) | | **event_datetime** | string | Date and time when the webhook was sent | | **status** | string | Event status: `paid` | | **data.paid_method_type** | string | Payment method used | | **data.paid_in.code_number** | string | Settling bank code | | **data.paid_in.ispb** | string | Settling bank ISPB | | **data.paid_in.name** | string | Settling bank name | ### paid_method_type Enumerators | Enumerator | Description | |---|---| | **bank_slip** | Payment made via bank slip | | **pix** | Payment made via Pix | --- ## Rejection Webhook A batch renegotiation may be rejected due to payment deadline expiration or an installment payment made outside of the renegotiation. WEBHOOK_TYPE renegotiation.batch_proposal STATUS rejected Webhook Body ```json { "webhook_type": "renegotiation.batch_proposal", "key": "", "event_datetime": "", "status": "rejected", "data": {} } ``` :::caution Attention A batch renegotiation may be rejected due to: - **Deadline expiration**: payment was not made by the due date (`proposal_due_date`) - **External payment**: an installment included in the renegotiation was paid outside of the batch before payment confirmation ::: --- ## Installment Payment Data When an installment is paid through a batch renegotiation, the payment data is recorded in the installment: Payment Data ```json { "batch_renegotiation_proposal_key": "f9addba2-ec91-41bf-a150-c59eb1c3fbef", "paid_in": { "ispb": "18236120", "name": "NU PAGAMENTOS - IP", "code_number": 260 }, "resource_account_key": "ea44b9f2-ad00-4896-b8a3-b1a3da28a72f" } ``` ### Payment Data Fields | Field | Type | Description | |---|---|---| | **batch_renegotiation_proposal_key** | string | Batch renegotiation proposal key that originated the payment | | **paid_in.ispb** | string | ISPB of the bank used for payment | | **paid_in.name** | string | Name of the bank used for payment | | **paid_in.code_number** | integer | Code of the bank used for payment | | **resource_account_key** | string | Key of the resource account that received the payment | --- # Integration Scripts - BNPL Full URL: /en/documentation/manual_bnpl_full/scripts_integracao ## Summary We provide ready-to-use Python scripts that demonstrate the complete BNPL Full integration flow with the QI Tech Sandbox API. Each script corresponds to a tested and validated API call. **All payloads and responses shown in this documentation reflect the actual Sandbox API responses obtained through these scripts.** ## Download The scripts are available in the project repository: 📦 Download complete Python package ## Prerequisites - Python 3.8+ - Dependencies: `requests`, `python-jose`, `python-dotenv` - A `_local.env` file with your Sandbox credentials: - `API_KEY` - Your API client key - `QI_PUBLIC_KEY` - QI Tech public key - `CLIENT_PRIVATE_KEY` - Your EC private key (PEM) ## Available Scripts ### Issuance | # | Script | Endpoint | Method | Description | |---|--------|----------|--------|-------------| | 01 | `01_issuance_simulation.py` | `/v2/credit_operation/simulation` | POST | Simulate a credit operation before issuance | | 02 | `02_issuance_issuance.py` | `/signed_debt` | POST | Issue the debt with opt-in contract signature | | 03 | `03_issuance_query.py` | `/v2/credit_operation/requester_identifier_key/{key}` | GET | Query the issued operation | ### Reversal | # | Script | Endpoint | Method | Description | |---|--------|----------|--------|-------------| | 04 | `04_reversal_cancel_before_disbursement.py` | `/debt/{debt_key}/cancel` | PATCH | Cancel an operation before disbursement | | 05 | `05_reversal_cancel_after_disbursement.py` | `/debt/reversal` | POST | Reverse an operation after disbursement (generates Pix refund) | ### Renegotiation | # | Script | Endpoint | Method | Description | |---|--------|----------|--------|-------------| | 06 | `06_renegotiation_simulation.py` | `/renegotiation/batch_proposal_simulation` | POST | Simulate a batch renegotiation | | 07 | `07_renegotiation_proposal.py` | `/renegotiation/batch_proposal` | POST | Create a batch renegotiation proposal | | 08 | `08_renegotiation_query.py` | `/renegotiation/batch_proposal/{key}` | GET | Query a batch proposal by key | | 09 | `09_renegotiation_list.py` | `/renegotiation/batch_proposal` | GET | List all batch proposals | | 10 | `10_renegotiation_cancel.py` | `/renegotiation/batch_proposal/{key}` | DELETE | Cancel a pending batch proposal | ### Refinancing | # | Script | Endpoint | Method | Description | |---|--------|----------|--------|-------------| | 11 | `11_refinancing_present_value.py` | `/debt` | GET | Query present value for refinancing calculation | | 12 | `12_refinancing_simulation.py` | `/debt_simulation` | POST | Simulate a refinancing operation | | 13 | `13_refinancing_issuance.py` | `/signed_debt` | POST | Create a refinancing (issues new debt, settles the previous one) | ## How to Use 1. Download the scripts from the repository 2. Create a `_local.env` file with your Sandbox credentials 3. Run the scripts in numerical order 4. Update keys (`DEBT_KEY`, `BATCH_PROPOSAL_KEY`, etc.) between scripts as needed :::info About the documentation examples Each script includes the actual API response as a comment block at the end of the file. These examples are the source of truth for the payloads displayed on the pages of this documentation. ::: --- # Consulta - Emissão Crédito Clean URL: /en/documentation/manual_credito_clean/emissao/consulta ## Resumo Você pode consultar a dívida a qualquer momento para obter informações ou acompanhar o status atual da operação. ## Consultar Operação de Crédito Existem duas formas de consultar uma operação: - Por `credit_operation_key` (DEBT-KEY) - Por `requester_identifier_key` (chave identificadora enviada na emissão) ### Por Credit Operation Key ENDPOINT /v2/credit_operation/ CREDIT-OPERATION-KEY MÉTODO GET Testar no Playground | Campo | Tipo | Descrição | Caracteres | |---|---|---|---| | `credit_operation_key`* | string | Chave da operação de crédito (DEBT-KEY) | UUID | ### Por Requester Identifier Key ENDPOINT /v2/credit_operation/requester_identifier_key/ REQUESTER-IDENTIFIER-KEY MÉTODO GET | Campo | Tipo | Descrição | Caracteres | |---|---|---|---| | `requester_identifier_key`* | string | Chave identificadora enviada na emissão | UUID | ### Response STATUS 200 Response Body ```json { "credit_operation_key": "72760166-4ddf-41fb-8a8c-605f8f4fc35c", "issue_amount": 1007.62, "origin_key": "72760166-4ddf-41fb-8a8c-605f8f4fc35c", "total_iof": 7.62, "assigned_at": null, "disbursement_start_date": "2026-04-07", "disbursement_end_date": "2026-04-07", "issue_date": "2026-04-07", "requester_identifier_key": "d1905ef5-19df-4183-bf0e-802b8229933c", "installments": [ { "business_due_date": "2026-05-07", "due_date": "2026-05-07", "calendar_days": 30, "due_interest": 0, "due_principal": 1007.62, "fine_amount": 0, "has_interest": true, "post_fixed_amount": 0, "pre_fixed_amount": 52.4, "principal_amortization_amount": 491.49, "tax_amount": 1.21, "total_amount": 543.89, "workdays": 20, "accrual_reference_date": null, "advanced_paid_amount": 0, "bank_slip_key": null, "digitable_line": null, "installment_key": "1dea396f-beb1-4df3-9822-35800b4c095a", "installment_status": "opened", "installment_type": "principal", "original_due_principal": 1007.62, "original_pre_fixed_amount": 52.4, "original_principal_amortization_amount": 491.49, "paid_amount": 0, "original_total_amount": 543.89, "qr_code_key": null, "qr_code_url": null, "renegotiation_proposal_key": null, "total_accrual_amount": 0, "total_paid_amount": 0, "installment_number": 1, "paid_at": null, "updated_at": "2026-04-07T23:59:27", "principal_amortization_payment_amount": 0, "prefixed_interest_payment_amount": 0 }, { "business_due_date": "2026-06-08", "due_date": "2026-06-07", "calendar_days": 31, "due_interest": 0, "due_principal": 516.1296159, "fine_amount": 0, "has_interest": true, "post_fixed_amount": 0, "pre_fixed_amount": 27.76, "principal_amortization_amount": 516.13, "tax_amount": 2.58, "total_amount": 543.89, "workdays": 20, "accrual_reference_date": null, "advanced_paid_amount": 0, "bank_slip_key": null, "digitable_line": null, "installment_key": "370e73d1-55d8-431e-9b22-d08fb8297999", "installment_status": "opened", "installment_type": "principal", "original_due_principal": 516.13, "original_pre_fixed_amount": 27.76, "original_principal_amortization_amount": 516.13, "paid_amount": 0, "original_total_amount": 543.89, "qr_code_key": null, "qr_code_url": null, "renegotiation_proposal_key": null, "total_accrual_amount": 0, "total_paid_amount": 0, "installment_number": 2, "paid_at": null, "updated_at": "2026-04-07T23:59:27", "principal_amortization_payment_amount": 0, "prefixed_interest_payment_amount": 0 } ], "first_due_date": "2026-05-07", "requester_key": "78287247-947d-4730-9bd1-7efb068175b6", "contract_number": "DWF1761222116", "credit_operation_status_enumerator": "opened", "operation_type_enumerator": "structured_operation", "disbursement_date": "2026-04-07", "issuer_name": "Dante Ferrarini", "issuer_document_number": "31057466093", "external_contract_fees": [ { "amount_type": "absolute", "fee_amount": 0, "tax_amount": 0, "irrf_amount": 0, "amount": 0, "pis_amount": 0, "amount_released": 0, "fee_type": "tac", "cofins_amount": 0, "csll_amount": 0, "description": null, "net_fee_amount": 0, "rebate_account": null } ], "cet": 5.82, "annual_cet": 97.05, "final_disbursement_amount": 1000, "number_of_installments": 2, "disbursement_issue_amount": 1000, "prefixed_interest_rate": { "annual_rate": 0.8373372409, "daily_rate": 0.0016911989, "interest_base": { "enumerator": "calendar_days", "year_days": 360 }, "monthly_rate": 0.052 }, "fine_configuration": { "contract_fine_rate": 0.02, "fine_delay_rate": { "annual_rate": 0.12682503, "daily_rate": 0.00033173, "interest_base": { "enumerator": "calendar_days", "year_days": 360 }, "monthly_rate": 0.01 } }, "attached_documents": [ { "document_key": "d6705fc4-80e0-4c8e-9aff-f3875024e6a4", "document_url": "https://storage.googleapis.com/sandbox-doc-api/documents/...", "signature_url": "https://storage.googleapis.com/sandbox-doc-api/documents/..._signed.pdf", "document_type": "ccb_pre_price_days", "signature_required": true, "signed": true } ], "related_parties": [ { "related_party_key": "24fac77e-7782-4f72-b31a-daee288e34ed", "role_type": "issuer", "person_type": "natural", "name": "Dante Ferrarini", "email": "", "individual_document_number": "31057466093" } ], "base_iof": 3.79, "additional_iof": 3.83, "assignment_amount": 1010.64, "created_at": "2026-04-07T23:59:22Z", "total_prefixed_amount": 80.16 } ``` STATUS 400 Response Body ```json { "data": "{\"title\": \"Bad Request\", \"description\": \"Invalid request body.\", \"translation\": \"Corpo da requisição inválido.\", \"extra_fields\": {}, \"code\": \"LEG000069\"}" } ``` --- ## Consultar Eventos da Operação Você também pode consultar o histórico de eventos (log de status) da operação: ENDPOINT /v2/credit_operation/ CREDIT-OPERATION-KEY /events MÉTODO GET Testar no Playground ### Path Params | Campo | Tipo | Descrição | Caracteres | |---|---|---|---| | `credit_operation_key`* | string | Chave da operação de crédito | UUID | ### Response STATUS 200 Response Body ```json { "data": [ { "status": "waiting_signature", "reason": null, "cancel_reason": null, "event_date": "2026-03-13T17:19:59Z" }, { "status": "issued", "reason": null, "cancel_reason": null, "event_date": "2026-03-13T17:19:59Z" }, { "status": "waiting_disbursement", "reason": null, "cancel_reason": null, "event_date": "2026-03-13T17:19:59Z" }, { "status": "opened", "reason": null, "cancel_reason": null, "event_date": "2026-03-13T17:19:59Z" } ], "pagination": { "current_page": 1, "next_page": null, "rows_per_page": 10 } } ``` ### Enumeradores de Status da Operação | Status | Descrição | |---|---| | `waiting_signature` | Aguardando assinatura do contrato | | `issued` | Operação emitida | | `waiting_disbursement` | Aguardando desembolso | | `opened` | Operação aberta (desembolso realizado) | | `canceled` | Operação cancelada | | `settled` | Operação liquidada (todas as parcelas pagas) | --- # Consulta de Cessão URL: /en/documentation/manual_credito_clean/emissao/consulta_cessao ## Resumo A cessão é o processo pelo qual as operações de crédito (itens) são transferidas para um cessionário. Você pode acompanhar e consultar as cessões a qualquer momento para obter informações ou verificar o status atual do processo. ## Webhook de Confirmação de Cessão Este webhook é disparado para notificar o cliente de que o processo de cessão foi iniciado. Ele fornece os metadados essenciais necessários para acompanhar a cessão. Response Body ```json { "key": "19e34186-847b-4dd7-9fc2-d14e28bc2f10", "data": { "status": "settled", "total_amount": 1917.04, "assignment_key": "19e34186-847b-4dd7-9fc2-d14e28bc2f10", "reference_date": "2026-04-10", "number_of_items": 8, "term_of_assignment_url": null }, "webhook_type": "assignment.status_change", "event_datetime": "2026-04-10T22:37:52" } ``` | Campo | Tipo | Descrição | Caracteres | |---|---|---|---| | `assignment_key` | string | Identificador único da operação de cessão | 36 | | `term_of_assignment_url` | string | URL para download do Termo de Cessão (PDF) | 2048 | | `number_of_items` | integer | Número total de operações de crédito (itens) incluídas nesta cessão | 5 | | `total_amount` | float | Soma do valor presente de todos os itens da cessão | 15,2 | | `reference_date` | string | Data base utilizada para os cálculos da cessão (YYYY-MM-DD) | 10 | --- ## Consultar uma Cessão Específica Para consultar uma cessão específica, o cliente pode realizar uma requisição GET no endpoint utilizando a chave identificadora da cessão (`assignment_key`). ENDPOINT /v2/assignment/ ASSIGNMENT-KEY MÉTODO GET Testar no Playground ### Path Params | Campo | Tipo | Descrição | Caracteres | |---|---|---|---| | `assignment_key`* | string | Chave identificadora única da cessão | UUID | ### Response STATUS 200 Response Body ```json { "assignment_key": "77997168-5d61-430f-b5ae-08eb3d7b8c0e", "creation_datetime": "2023-10-01T12:00:00", "reference_date": "2023-10-01", "total_amount": 120000, "number_of_items": 5, "term_of_assignment_url": "https://example.com/assignment.pdf", "status": "settled", "signable_term_url": "https://example.com/signable_term.pdf" } ``` --- ## Consultar os Itens (Contratos) de uma Cessão Para consultar os contratos contidos em uma cessão, utilize uma requisição GET no endpoint com a mesma `assignment_key`. ENDPOINT /v2/assignment/ ASSIGNMENT-KEY /assignment_items?page=1&page_size=100 MÉTODO GET Testar no Playground ### Path Params | Campo | Tipo | Descrição | Caracteres | |---|---|---|---| | `assignment_key`* | string | Chave identificadora única da cessão | UUID | ### Query Params | Campo | Tipo | Descrição | Caracteres | |---|---|---|---| | `page` | string | Número da página | - | | `page_size` | string | Tamanho da página, limitado a 100 | - | ### Response A resposta é uma lista paginada contendo as informações de cada contrato da cessão (status 200): STATUS 200 Response Body ```json { "pagination": { "page": 1, "page_size": 10 }, "data": [ { "assignment_date": "2026-04-10", "assignment_item_key": "uuid", "contract_number": "TIK000012312", "control_number": "TIK000012312", "requester_identifier_key": "uuid", "credit_operation_key": "string", "disbursed_amount": 80.0, "disbursement_date": "2026-04-10", "endorsement_url": "url", "issue_amount": 180.00, "issuer_document_number": "string", "issuer_name": "string", "number_of_installments": 10, "present_amount": 180.0, "contract_present_amount": 180.0, "purchaser_document_number": "string", "status": "settled", "rejected_reasons": [], "assignment_items": [ { "installment_key": "uuid", "present_amount": 100, "due_date": "2026-05-10", "your_number": "TIK000012312001" }, { "installment_key": "uuid", "present_amount": 80, "due_date": "2026-06-10", "your_number": "TIK000012312002" } ] } ] } ``` --- ## Consultar Lotes de Cessão por Data Consulte os lotes de cessão pela data de referência (`reference_date`). ENDPOINT /v2/assignment/assignments?reference_date=2026-05-15 MÉTODO GET Testar no Playground ### Query Params | Campo | Tipo | Descrição | Caracteres | |---|---|---|---| | `reference_date` | string | Data da tentativa de cessão (YYYY-MM-DD) | 10 | ### Response STATUS 200 Response Body ```json { "data": [ { "assignment_key": "439b1257-82ac-4741-a416-a4428a9a7327", "number_of_items": 10000, "reference_date": "2025-01-01", "signable_term_url": "https://example.com/endorsement.pdf", "status": "settled", "term_of_assignment_url": "signed_url", "total_amount": 100.00 }, { "assignment_key": "439b1257-82ac-4741-a416-a4428a9a7327", "number_of_items": 10000, "reference_date": "2025-01-01", "signable_term_url": "https://example.com/endorsement.pdf", "status": "settled", "term_of_assignment_url": "signed_url", "total_amount": 100.00 }, { "assignment_key": "439b1257-82ac-4741-a416-a4428a9a7327", "number_of_items": 10000, "reference_date": "2025-01-01", "signable_term_url": "https://example.com/endorsement.pdf", "status": "canceled", "term_of_assignment_url": "signed_url", "total_amount": 100.00 } ] } ``` --- # Emissão com Assinatura Posterior URL: /en/documentation/manual_credito_clean/emissao/emissao_dois_passos Neste fluxo, a dívida é criada em uma primeira chamada e a assinatura do tomador é enviada em uma chamada separada. O sistema gera o contrato e aguarda a assinatura antes de processar o desembolso. --- ## Passo 1 — Criação da Dívida (`POST /debt`) ### Request ENDPOINT /debt MÉTODO POST Request Body **disbursed_amount** ```json { "borrower": { "name": "Dante Ferrarini", "email": "dante@email.com", "phone": { "number": "185633631", "area_code": "15", "country_code": "055" }, "is_pep": false, "address": { "city": "São Paulo", "state": "SP", "number": "1000", "street": "Rua Gilberto Sabino", "complement": "", "postal_code": "05425020", "neighborhood": "Pinheiros" }, "role_type": "issuer", "birth_date": "1993-09-10", "person_type": "natural", "individual_document_number": "31057466093" }, "financial": { "interest_type": "pre_price_days", "disbursement_date": "2026-04-07", "fine_configuration": { "monthly_rate": 0.01, "interest_base": "calendar_days", "contract_fine_rate": 0.02 }, "disbursed_amount": 1000, "monthly_interest_rate": 0.052, "credit_operation_type": "ccb", "interest_grace_period": 0, "number_of_installments": 2, "principal_grace_period": 0 }, "disbursement_bank_account": { "name": "Dante Ferrarini", "document_number": "31057466093", "bank_code": "329", "branch_number": "0001", "account_number": "7617846", "account_digit": "5", "account_type": "checking_account" }, "purchaser_document_number": "32402502000135" } ``` **installments** ```json { "borrower": { "name": "Dante Ferrarini", "email": "dante@email.com", "phone": { "number": "185633631", "area_code": "15", "country_code": "055" }, "is_pep": false, "address": { "city": "São Paulo", "state": "SP", "number": "1000", "street": "Rua Gilberto Sabino", "complement": "", "postal_code": "05425020", "neighborhood": "Pinheiros" }, "role_type": "issuer", "birth_date": "1993-09-10", "person_type": "natural", "individual_document_number": "31057466093" }, "financial": { "interest_type": "pre_price_days", "disbursement_date": "2026-04-07", "fine_configuration": { "monthly_rate": 0.01, "interest_base": "calendar_days", "contract_fine_rate": 0.02 }, "monthly_interest_rate": 0.052, "credit_operation_type": "ccb", "interest_grace_period": 0, "principal_grace_period": 0, "desired_installments": [ { "due_date": "2026-05-07", "total_amount": 543.89 }, { "due_date": "2026-06-07", "total_amount": 543.89 } ] }, "disbursement_bank_account": { "name": "Dante Ferrarini", "document_number": "31057466093", "bank_code": "329", "branch_number": "0001", "account_number": "7617846", "account_digit": "5", "account_type": "checking_account" }, "purchaser_document_number": "32402502000135" } ``` **due_dates** ```json { "borrower": { "name": "Dante Ferrarini", "email": "dante@email.com", "phone": { "number": "185633631", "area_code": "15", "country_code": "055" }, "is_pep": false, "address": { "city": "São Paulo", "state": "SP", "number": "1000", "street": "Rua Gilberto Sabino", "complement": "", "postal_code": "05425020", "neighborhood": "Pinheiros" }, "role_type": "issuer", "birth_date": "1993-09-10", "person_type": "natural", "individual_document_number": "31057466093" }, "financial": { "interest_type": "pre_price_days", "disbursement_date": "2026-04-07", "fine_configuration": { "monthly_rate": 0.01, "interest_base": "calendar_days", "contract_fine_rate": 0.02 }, "disbursed_amount": 1000, "monthly_interest_rate": 0.052, "credit_operation_type": "ccb", "interest_grace_period": 0, "principal_grace_period": 0, "due_dates": [ "2026-05-07", "2026-06-07" ] }, "disbursement_bank_account": { "name": "Dante Ferrarini", "document_number": "31057466093", "bank_code": "329", "branch_number": "0001", "account_number": "7617846", "account_digit": "5", "account_type": "checking_account" }, "purchaser_document_number": "32402502000135" } ``` ### Body Params | Campo | Tipo | Descrição | Caracteres | |---|---|---|---| | **borrower*** | object | Objeto do tomador | **[Objeto Borrower](#objeto-borrower)** | | **financial*** | object | Detalhes financeiros da operação | **[Objeto Financial](#objeto-financial)** | | **disbursement_bank_account*** | object | Dados da conta bancária do tomador para recebimento do desembolso | **[Objeto Disbursement Bank Account](#objeto-disbursement-bank-account)** | | **purchaser_document_number*** | string | CNPJ do cessionário | 14 | ### Objeto Borrower | Campo | Tipo | Descrição | Caracteres | |---|---|---|---| | name* | string | Nome completo do tomador | 100 | | email | string | Endereço de e-mail do tomador | 254 | | phone | object | Dados de telefone do tomador | **[Objeto Phone](#objeto-phone)** | | is_pep* | boolean | Indicador de Pessoa Politicamente Exposta | 5 | | address* | object | Endereço residencial do tomador | **[Objeto Address](#objeto-address)** | | role_type | string | Papel do tomador na operação (ex: "issuer") | 10 | | birth_date* | date | Data de nascimento do tomador (Formato: "YYYY-MM-DD") | 10 | | person_type* | string | Classificação da pessoa (natural ou legal) | 7 | | individual_document_number* | string | CPF do tomador - somente números | 11 | ### Objeto Address | Campo | Tipo | Descrição | Caracteres | |---|---|---|---| | city* | string | Nome da cidade | 100 | | state* | string | Sigla do estado (duas letras maiúsculas) | 2 | | number | string | Número do logradouro | 10 | | street* | string | Nome do logradouro | 100 | | complement | string | Complemento do endereço (texto livre) | 100 | | postal_code* | string | CEP - somente números | 8 | | neighborhood* | string | Nome do bairro | 100 | ### Objeto Phone | Campo | Tipo | Descrição | Caracteres | |---|---|---|---| | number* | string | Número do telefone | 9 | | area_code* | string | Código de área (DDD) | 2 | | country_code* | string | Código internacional (ex: "055") | 3 | ### Objeto Financial :::info Formas de definir o valor da operação É possível definir o valor da operação de três formas mutuamente exclusivas: - **`disbursed_amount` + `monthly_interest_rate` + `number_of_installments`**: informe o valor a ser desembolsado, a taxa de juros e o número de parcelas — o sistema calcula o valor de cada parcela. - **`desired_installments`**: informe um array com a data e o valor total de cada parcela individualmente — o sistema calcula o valor de desembolso. - **`disbursed_amount` + `due_dates`**: informe o valor de desembolso e um array com as datas de vencimento — o sistema calcula os valores das parcelas para a agenda irregular informada. ::: | Campo | Tipo | Descrição | Caracteres | |---|---|---|---| | interest_type* | string | Método de amortização | 20 | | disbursement_date* | string | Data de desembolso | 10 | | fine_configuration* | object | Configuração de multa e mora | **[Objeto Fine Configuration](#objeto-fine-configuration)** | | monthly_interest_rate* | float | Taxa de juros mensal | 10,6 | | disbursed_amount | float | Valor a ser desembolsado. Obrigatório se `desired_installments` não for informado | 15,2 | | number_of_installments | integer | Número de parcelas. Obrigatório se `disbursed_amount` for informado sem `due_dates` | 3 | | desired_installments | array | Array de parcelas com data e valor definidos individualmente. Obrigatório se `disbursed_amount` não for informado | **[Objeto Desired Installments](#objeto-desired-installments)** | | due_dates | array | Lista de datas de vencimento (YYYY-MM-DD). Utilizado com `disbursed_amount` para agenda de parcelas irregular | - | | credit_operation_type* | string | Tipo da operação de crédito (ex: "ccb") | 10 | | interest_grace_period | integer | Período de carência de juros (em meses) | 3 | | principal_grace_period | integer | Período de carência do principal (em meses) | 3 | ### Objeto Desired Installments | Campo | Tipo | Descrição | Caracteres | |---|---|---|---| | due_date* | string | Data de vencimento da parcela (YYYY-MM-DD) | 10 | | total_amount* | float | Valor total da parcela | 15,2 | ### Objeto Fine Configuration | Campo | Tipo | Descrição | Caracteres | |---|---|---|---| | monthly_rate* | float | Taxa de mora mensal | 10,6 | | interest_base* | string | Base de cálculo da mora (ex: "calendar_days") | 20 | | contract_fine_rate* | float | Taxa de multa contratual | 10,6 | ### Objeto Disbursement Bank Account | Campo | Tipo | Descrição | Caracteres | |---|---|---|---| | name | string | Nome do titular da conta | 50 | | document_number | string | CPF do titular da conta | 11 | | bank_code* | string | Código COMPE da instituição financeira | 3 | | branch_number* | string | Número da agência (sem dígito verificador) | 4 | | account_number* | string | Número da conta (sem dígito verificador) | 10 | | account_digit* | string | Dígito verificador da conta (usar zero no lugar de letras) | 1 | | account_type | enum | Tipo da conta (`checking_account`, `saving_account`, `payment_account`, etc.) | - | ### Response STATUS 200 A resposta retorna o plano de pagamento e a **DEBT-KEY**, com status `waiting_signature`. O desembolso não é realizado até que a assinatura seja enviada no Passo 2. Response Body ```json { "webhook_type": "debt", "key": "1baea8a0-0fca-4f7c-8857-a227d4da72f8", "status": "waiting_signature", "event_datetime": "2026-04-07 22:46:10", "data": { "borrower": { "name": "Dante Ferrarini", "document_number": "31057466093", "related_party_key": "d5cbcada-42e7-4d5b-84fc-3c2dc8038411" }, "contract": { "number": "0000192840/DWF", "urls": [ "https://storage.googleapis.com/sandbox-doc-api/documents/b2d974f9-c710-42e3-8ea4-69cc31561c38/CCB-0000192840-20260407.pdf" ], "signers": [ { "signer_name": "Dante Ferrarini", "signer_document_number": "31057466093", "signer_role": "issuer", "signer_email": "dante@email.com", "signer_external_key": null, "signature_url": null } ] }, "installments": [...], "total_pre_fixed_amount": 80.16 } } ``` :::caution Atenção Salve a **DEBT-KEY** retornada — ela é necessária para enviar a assinatura no Passo 2. ::: --- ## Passo 2 — Envio da Assinatura (`POST /debt/{DEBT-KEY}/signed`) ### Request ENDPOINT /debt/ DEBT-KEY /signed MÉTODO POST Request Body ```json { "type": "data_signature", "signatures": [ { "signed_object": { "raw_text": "Lorem ipsum dolor sit amet, consectetur a...." }, "authenticity": { "timestamp": "1970-01-01 00:00:01", "ip_address": "179.104.42.245", "session_id": "ddb1d063-4fdf-4330-af9c-3316e9142ff3" }, "signer": { "name": "Dante Ferrarini", "email": "dante@email.com", "phone": { "country_code": "055", "area_code": "15", "number": "185633631" }, "document_number": "31057466093" }, "authentication_type": "opt-in" } ] } ``` ### Path Params | Campo | Tipo | Descrição | Caracteres | |---|---|---|---| | `debt_key`* | string | Chave da dívida retornada no Passo 1 | UUID | ### Body Params | Campo | Tipo | Descrição | Caracteres | |---|---|---|---| | `type`* | string | Tipo de assinatura. Valor: `data_signature` | - | | `signatures`* | array | Lista de objetos de comprovação de assinatura | **[Objeto signatures](#objeto-signatures)** | ### Objeto signatures | Campo | Tipo | Descrição | Caracteres | |---|---|---|---| | `signed_object` | object | Documento que está sendo assinado | **[Objeto signed_object](#objeto-signed_object)** | | `authenticity` | object | Dados de autenticação da assinatura | **[Objeto authenticity](#objeto-authenticity)** | | `signer` | object | Dados do assinante | **[Objeto signer](#objeto-signer)** | | `authentication_type`* | string | Tipo de assinatura. Valor: `opt-in` | - | ### Objeto signed_object | Campo | Tipo | Descrição | Caracteres | |---|---|---|---| | `raw_text`* | string | Texto corrido com os dados do contrato que será assinado | - | ### Objeto authenticity | Campo | Tipo | Descrição | Caracteres | |---|---|---|---| | `timestamp`* | string | Data e hora da assinatura | - | | `ip_address`* | string | Endereço IP onde o aceite foi coletado | - | | `session_id`* | string | ID de sessão do cliente no momento da assinatura — deve ser armazenado por no mínimo 5 anos | - | | `geolocation` | object | Geolocalização opcional | - | ### Objeto signer | Campo | Tipo | Descrição | Caracteres | |---|---|---|---| | `name`* | string | Nome do assinante | - | | `email`* | string | E-mail do assinante | - | | `phone` | object | Telefone do assinante | **[Objeto Phone](#objeto-phone)** | | `document_number`* | string | CPF do assinante | - | ### Response STATUS 200 Response Body ```json { "data": {}, "event_datetime": "2026-04-07 15:24:47", "key": "", "status": "signature_received", "webhook_type": "debt" } ``` --- # Issuance with Immediate Signature (/signed_debt) URL: /en/documentation/manual_credito_clean/emissao/emissao_signed_debt This endpoint issues the debt and processes the contract signature via opt-in in a single call. Disbursement occurs on the date informed in the `disbursement_date` field, which may differ from the issuance date. No pre-registration is required; just provide the borrower's data within the issuance request. ## Request ENDPOINT /signed_debt METHOD POST Try it in the Playground Request Body **disbursed_amount** ```json { "borrower": { "name": "Dante Ferrarini", "email": "", "phone": { "number": "185633631", "area_code": "15", "country_code": "086" }, "is_pep": false, "address": { "city": "São Paulo", "state": "SP", "number": "", "street": "Rua Gilberto Sabino", "postal_code": "05425020", "neighborhood": "Pinheiros", "complement": "" }, "role_type": "issuer", "birth_date": "1993-09-10", "person_type": "natural", "attached_documents_list": [ { "selfie": "250e7e95-57c8-40bd-a0cd-0be8eb172916" } ], "individual_document_number": "31057466093" }, "financial": { "interest_type": "pre_price_days", "disbursement_date": "2026-04-07", "fine_configuration": { "monthly_rate": 0.01, "interest_base": "calendar_days", "contract_fine_rate": 0.02 }, "disbursed_amount": 1000, "monthly_interest_rate": 0.052, "credit_operation_type": "ccb", "interest_grace_period": 0, "number_of_installments": 2, "principal_grace_period": 0 }, "simplified": true, "additional_data": { "contract": { "contract_number": "DWF1761222116", "signatures": [ { "signer": { "name": "Dante Ferrarini", "email": "", "phone": { "number": "185633631", "area_code": "15", "country_code": "086" }, "document_number": "31057466093" }, "signature": { "timestamp": "28-01-2026 06:36:35", "ip_address": "192.168.1.1", "signature_file": { "file_url": "https://qitech.com.br/signature.pdf", "file_type": "pdf" } } } ] } }, "requester_identifier_key": "d1905ef5-19df-4183-bf0e-802b8229933c", "purchaser_document_number": "32402502000135", "disbursement_bank_accounts": [ { "name": "Dante Ferrarini", "ispb_number": "32402502", "account_digit": "5", "branch_number": "0001", "account_number": "7617846", "document_number": "31057466093", "percentage_receivable": 100 } ] } ``` **installments** ```json { "borrower": { "name": "Dante Ferrarini", "email": "", "phone": { "number": "185633631", "area_code": "15", "country_code": "086" }, "is_pep": false, "address": { "city": "São Paulo", "state": "SP", "number": "", "street": "Rua Gilberto Sabino", "postal_code": "05425020", "neighborhood": "Pinheiros", "complement": "" }, "role_type": "issuer", "birth_date": "1993-09-10", "person_type": "natural", "attached_documents_list": [ { "selfie": "250e7e95-57c8-40bd-a0cd-0be8eb172916" } ], "individual_document_number": "31057466093" }, "financial": { "interest_type": "pre_price_days", "disbursement_date": "2026-04-07", "fine_configuration": { "monthly_rate": 0.01, "interest_base": "calendar_days", "contract_fine_rate": 0.02 }, "monthly_interest_rate": 0.052, "credit_operation_type": "ccb", "interest_grace_period": 0, "principal_grace_period": 0, "desired_installments": [ { "due_date": "2026-05-07", "total_amount": 543.89 }, { "due_date": "2026-06-07", "total_amount": 543.89 } ] }, "simplified": true, "additional_data": { "contract": { "contract_number": "DWF1761222116", "signatures": [ { "signer": { "name": "Dante Ferrarini", "email": "", "phone": { "number": "185633631", "area_code": "15", "country_code": "086" }, "document_number": "31057466093" }, "signature": { "timestamp": "28-01-2026 06:36:35", "ip_address": "192.168.1.1", "signature_file": { "file_url": "https://qitech.com.br/signature.pdf", "file_type": "pdf" } } } ] } }, "requester_identifier_key": "d1905ef5-19df-4183-bf0e-802b8229933c", "purchaser_document_number": "32402502000135", "disbursement_bank_accounts": [ { "name": "Dante Ferrarini", "ispb_number": "32402502", "account_digit": "5", "branch_number": "0001", "account_number": "7617846", "document_number": "31057466093", "percentage_receivable": 100 } ] } ``` **due_dates** ```json { "borrower": { "name": "Dante Ferrarini", "email": "", "phone": { "number": "185633631", "area_code": "15", "country_code": "086" }, "is_pep": false, "address": { "city": "São Paulo", "state": "SP", "number": "", "street": "Rua Gilberto Sabino", "postal_code": "05425020", "neighborhood": "Pinheiros", "complement": "" }, "role_type": "issuer", "birth_date": "1993-09-10", "person_type": "natural", "attached_documents_list": [ { "selfie": "250e7e95-57c8-40bd-a0cd-0be8eb172916" } ], "individual_document_number": "31057466093" }, "financial": { "interest_type": "pre_price_days", "disbursement_date": "2026-04-07", "fine_configuration": { "monthly_rate": 0.01, "interest_base": "calendar_days", "contract_fine_rate": 0.02 }, "disbursed_amount": 1000, "monthly_interest_rate": 0.052, "credit_operation_type": "ccb", "interest_grace_period": 0, "principal_grace_period": 0, "due_dates": [ "2026-05-07", "2026-06-07" ] }, "simplified": true, "additional_data": { "contract": { "contract_number": "DWF1761222116", "signatures": [ { "signer": { "name": "Dante Ferrarini", "email": "", "phone": { "number": "185633631", "area_code": "15", "country_code": "086" }, "document_number": "31057466093" }, "signature": { "timestamp": "28-01-2026 06:36:35", "ip_address": "192.168.1.1", "signature_file": { "file_url": "https://qitech.com.br/signature.pdf", "file_type": "pdf" } } } ] } }, "requester_identifier_key": "d1905ef5-19df-4183-bf0e-802b8229933c", "purchaser_document_number": "32402502000135", "disbursement_bank_accounts": [ { "name": "Dante Ferrarini", "ispb_number": "32402502", "account_digit": "5", "branch_number": "0001", "account_number": "7617846", "document_number": "31057466093", "percentage_receivable": 100 } ] } ``` ### Request Body Details | Field | Type | Description | Length | |---|---|---|---| | **borrower*** | object | Borrower object - The debtor of the credit operation | **[Borrower Object](#borrower-object)** | | **financial*** | object | Contains all financial details and calculation parameters of the operation | **[Financial Object](#financial-object)** | | **simplified** | boolean | If true, uses the simplified issuance flow | - | | **additional_data*** | object | Additional contract data, including signatures | **[Additional Data Object](#additional-data-object)** | | **requester_identifier_key** | string | Requester identifier key | UUID | | **purchaser_document_number*** | string | CNPJ of the assignee – The purchaser of the credit operation (FIDC) | 14 | | **disbursement_bank_accounts*** | array | Borrower's bank account data for receiving the disbursement | **[Disbursement Bank Account Object](#disbursement-bank-account-object)** | ### Borrower Object | Field | Type | Description | Length | |---|---|---|---| | name* | string | Borrower's full name | 100 | | email | string | Borrower's email address | 254 | | phone | object | Borrower's phone data | **[Phone Object](#phone-object)** | | is_pep* | boolean | Politically Exposed Person indicator | 5 | | address* | object | Borrower's residential address | **[Address Object](#address-object)** | | role_type | string | Borrower's role in the operation (e.g., "issuer") | 10 | | birth_date* | date | Borrower's date of birth (Format: "YYYY-MM-DD") | 10 | | person_type* | string | Person classification (natural or legal) | 7 | | attached_documents_list | array | List of attached documents (e.g., selfie) | **[Attached Documents Object](#attached-documents-object)** | | individual_document_number* | string | Borrower's CPF - numbers only | 11 | ### Attached Documents Object | Field | Type | Description | Length | |---|---|---|---| | selfie | string | DOCUMENT_KEY of the selfie document submitted via upload | UUID | ### Address Object | Field | Type | Description | Length | |---|---|---|---| | city* | string | City name | 100 | | state* | string | State abbreviation (two uppercase letters) | 2 | | number | string | Street number | 10 | | street* | string | Street name | 100 | | complement | string | Address complement (free text) | 100 | | postal_code* | string | Postal code (CEP) - numbers only | 8 | | neighborhood* | string | Neighborhood name | 100 | ### Phone Object | Field | Type | Description | Length | |---|---|---|---| | number* | string | Phone number | 9 | | area_code* | string | Area code (DDD) | 2 | | country_code* | string | International code (e.g., "055") | 3 | ### Financial Object :::info Ways to define the operation amount The operation amount can be defined through the following mutually exclusive combinations (provide **one and only one** of the value keys, alongside the other required fields): - **`disbursed_amount` + `monthly_interest_rate` + `number_of_installments`**: provide the net amount to be disbursed, the interest rate and the number of installments — the system computes each installment value. - **`amount` + `monthly_interest_rate` + `number_of_installments`**: provide the gross amount (with IOF) of the operation — the system computes the net disbursement and each installment value. - **`final_disbursement_amount` + `monthly_interest_rate` + `number_of_installments`**: provide the final amount that must reach the recipient and the system inflates `issue_amount` to cover IOF. - **`installment_face_value` + `number_of_installments` + (`disbursed_amount` or `amount`)**: provide the desired value per installment; when this combination is used **without** `monthly_interest_rate`, the system assumes a zero rate. - **`desired_installments`**: provide an array with the due date and total value of each installment individually — the system computes the disbursement value. - **`disbursed_amount` + `due_dates`**: provide the disbursement amount and an array with the due dates — the system computes the installment values for the informed irregular schedule. ::: | Field | Type | Description | Length | |---|---|---|---| | interest_type* | string | Amortization method | 20 | | disbursement_date* | string | Disbursement date | 10 | | first_due_date | string | Due date of the first installment (YYYY-MM-DD) | 10 | | limit_days_to_disburse | integer | Number of days after `disbursement_date` during which disbursement may still occur | 3 | | fine_configuration* | object | Fine and arrears configuration | **[Fine Configuration Object](#fine-configuration-object)** | | monthly_interest_rate | float | Monthly interest rate. Optional when `installment_face_value` is used | 10,6 | | annual_interest_rate | float | Annual interest rate (alternative to `monthly_interest_rate`) | 10,6 | | daily_interest_rate | float | Daily interest rate (alternative to `monthly_interest_rate`) | 10,6 | | disbursed_amount | float | Net amount to be disbursed | 15,2 | | amount | float | Gross amount of the operation (`issue_amount`) — includes IOF | 15,2 | | final_disbursement_amount | float | Final amount to reach the recipient — system inflates `issue_amount` to cover IOF | 15,2 | | installment_face_value | float | Desired value of each installment | 15,2 | | number_of_installments | integer | Number of installments | 3 | | desired_installments | array | Array of installments with individually defined date and value | **[Desired Installments Object](#desired-installments-object)** | | due_dates | array | List of due dates (YYYY-MM-DD). Used with `disbursed_amount` for an irregular installment schedule | - | | total_iof | float | Total IOF amount — when omitted, the system calculates it automatically | 15,2 | | credit_operation_type* | string | Credit operation type (e.g., "ccb") | 10 | | interest_grace_period | integer | Interest grace period (in months) | 3 | | principal_grace_period | integer | Principal grace period (in months) | 3 | ### Desired Installments Object | Field | Type | Description | Length | |---|---|---|---| | due_date* | string | Installment due date (YYYY-MM-DD) | 10 | | total_amount* | float | Total installment amount | 15,2 | ### Fine Configuration Object | Field | Type | Description | Length | |---|---|---|---| | monthly_rate* | float | Monthly arrears rate | 10,6 | | interest_base* | string | Arrears calculation base (e.g., "calendar_days") | 20 | | contract_fine_rate* | float | Contract fine rate | 10,6 | ### Disbursement Bank Account Object | Field | Type | Description | Length | |---|---|---|---| | name | string | Full name of the destination account holder | 100 | | document_number | string | CPF or CNPJ of the destination account holder | 11 or 14 | | transfer_method | string | Transfer method. Values: `pix`, `ted` (default: `pix`) | 3 | | pix_transfer_type | string | Pix transfer subtype. Values: `manual`, `key`, `qrcode` | 6 | | ispb_number | string | ISPB code of the financial institution | 8 | | bank_code | string | COMPE code of the financial institution (alternative to `ispb_number`) | 3 | | branch_number | string | Branch number (without check digit) | 4 | | account_number | string | Account number (without check digit) | 19 | | account_digit | string | Account check digit (use zero in place of letters) | 1 | | account_type | string | Destination account type. Values: `checking_account`, `saving_account`, `salary_account`, `payment_account`, `deposit_account`, `guaranteed_account`, `investment_account` | 20 | | pix_key | string | Recipient's Pix key — required when `pix_transfer_type` = `key` | - | | qr_code_key | string | UUID key of a Pix QR Code already registered — required when `pix_transfer_type` = `qrcode` | 36 | | qr_code_url | string | EMV string (copy-and-paste) of the Pix QR Code — alternative to `qr_code_key` | 250 | | digitable_line | string | Bank slip digitable line — used for disbursement via boleto | 47-48 | | end_to_end_id | string | Pix end-to-end identifier (populated in the response) | 32 | | percentage_receivable | float | Percentage of the disbursement allocated to this account. Required when `amount_receivable` is not provided | 3 | | amount_receivable | float | Fixed amount allocated to this account. Required when `percentage_receivable` is not provided | 15,2 | :::info Supported disbursement modes The field combination depends on `transfer_method` and `pix_transfer_type`: - **QI Tech internal account or TED**: `bank_code`/`ispb_number` + `branch_number` + `account_number` + `account_digit` + `document_number` + `name` + `percentage_receivable`. - **Pix manual**: `pix_transfer_type` = `manual` + account data (same as TED). - **Pix by key**: `pix_transfer_type` = `key` + `pix_key`. - **Pix by QR Code (registered)**: `pix_transfer_type` = `qrcode` + `qr_code_key`. - **Pix by QR Code (copy-and-paste)**: `qr_code_url` + `transfer_method` = `pix`. - **Boleto payment**: `digitable_line` + `amount_receivable`. ::: ### Additional Data Object | Field | Type | Description | Length | |---|---|---|---| | contract* | object | Contract data | **[Contract Object](#contract-object)** | ### Contract Object | Field | Type | Description | Length | |---|---|---|---| | contract_number* | string | Unique contract identifier number | 20 | | signatures* | array | List of digital signature evidence objects (Opt-in) | **[Signature Object](#signature-object)** | ### Signature Object | Field | Type | Description | Length | |---|---|---|---| | signer* | object | Signer identification data | **[Signer Object](#signer-object)** | | signature* | object | Digital signature evidence data | **[Signature Details Object](#signature-details-object)** | ### Signer Object | Field | Type | Description | Length | |---|---|---|---| | name* | string | Signer's full name | 255 | | document_number* | string | Signer's CPF | 11 | | email | string | Signer's email | 100 | | phone | object | Signer's phone data | **[Phone Object](#phone-object)** | ### Signature Details Object | Field | Type | Description | Length | |---|---|---|---| | ip_address* | string | IP address used in the signature | 45 | | timestamp* | string | Signature date and time (ISO 8601: YYYY-MM-DDTHH:mm:ssZ) | 24 | | signature_file* | object | Digital signature file | **[Signature File Object](#signature-file-object)** | ### Signature File Object | Field | Type | Description | Length | |---|---|---|---| | file_url* | string | Direct link to the signed contract document (PDF) | 2048 | | file_type* | string | Signature file format (e.g., "pdf") | 4 | ## Response The response to the issuance request returns the payment schedule and a **DEBT-KEY**, which identifies the debt at QI SCD. STATUS 201 Response Body ```json { "webhook_type": "debt", "key": "72760166-4ddf-41fb-8a8c-605f8f4fc35c", "status": "issued", "event_datetime": "2026-04-07 23:59:28", "data": { "borrower": { "name": "Dante Ferrarini", "document_number": "31057466093", "related_party_key": "24fac77e-7782-4f72-b31a-daee288e34ed" }, "contract": { "document_key": null, "number": "DWF1761222116", "urls": [], "signature_information": [ { "signer_name": "Dante Ferrarini", "signer_document_number": "31057466093", "signer_role": "issuer", "signer_email": null, "signer_external_key": null, "signature_url": null } ] }, "requester_identifier_key": "d1905ef5-19df-4183-bf0e-802b8229933c", "iof_charge_method": "financed", "collaterals": [], "contract_fees": [ { "fee_type": "spread", "fee_amount": 3.02 } ], "external_contract_fees": [ { "fee_type": "tac", "fee_amount": 0, "tax_amount": 0, "net_fee_amount": 0 } ], "external_contract_fee_amount": 0, "net_external_contract_fee_amount": 0, "contract_fee_amount": 3.02, "issue_amount": 1007.62, "assignment_amount": 1010.64, "cet": "5,8200%", "annual_cet": "97,0501%", "number_of_installments": 2, "base_iof": 3.79, "additional_iof": 3.83, "total_iof": 7.62, "ipoc_code": "324025020203131057466093DWF1761222116", "prefixed_interest_rate": { "annual_rate": 0.8373372409, "created_at": "2026-04-07T23:59:22", "daily_rate": 0.0016911989, "interest_base": "calendar_days", "monthly_rate": 0.052 }, "installments": [ { "accrual_reference_date": null, "additional_costs": [], "advanced_paid_amount": 0, "bank_slip_key": null, "business_due_date": "2026-05-07", "calendar_days": 30, "digitable_line": null, "due_date": "2026-05-07", "due_interest": 0, "due_principal": 1007.62, "fine_amount": null, "has_interest": true, "installment_history": [], "installment_key": "1dea396f-beb1-4df3-9822-35800b4c095a", "installment_number": 1, "installment_payment": [], "installment_status": "created", "installment_type": "principal", "original_due_principal": 1007.62, "original_pre_fixed_amount": 52.3996159, "original_principal_amortization_amount": 491.4903841, "original_total_amount": 543.89, "paid_amount": 0, "paid_at": null, "post_fixed_amount": 0, "pre_fixed_amount": 52.3996159, "principal_amortization_amount": 491.4903841, "qr_code_key": null, "qr_code_url": null, "renegotiation_proposal_key": null, "tax_amount": 1.20906634, "total_accrual_amount": null, "total_amount": 543.89, "total_paid_amount": 0, "workdays": 20 }, { "accrual_reference_date": null, "additional_costs": [], "advanced_paid_amount": 0, "bank_slip_key": null, "business_due_date": "2026-06-08", "calendar_days": 31, "digitable_line": null, "due_date": "2026-06-07", "due_interest": 0, "due_principal": 516.1296159, "fine_amount": null, "has_interest": true, "installment_history": [], "installment_key": "370e73d1-55d8-431e-9b22-d08fb8297999", "installment_number": 2, "installment_payment": [], "installment_status": "created", "installment_type": "principal", "original_due_principal": 516.1296159, "original_pre_fixed_amount": 27.7603841, "original_principal_amortization_amount": 516.1296159, "original_total_amount": 543.89, "paid_amount": 0, "paid_at": null, "post_fixed_amount": 0, "pre_fixed_amount": 27.7603841, "principal_amortization_amount": 516.1296159, "qr_code_key": null, "qr_code_url": null, "renegotiation_proposal_key": null, "tax_amount": 2.58168034, "total_accrual_amount": null, "total_amount": 543.89, "total_paid_amount": 0, "workdays": 20 } ], "total_pre_fixed_amount": 80.16 } } ``` :::caution Attention Remember to save the returned **DEBT-KEY**, as it will be required for queries, renegotiations, and chargebacks of the operation. ::: ### Response Body Details | Field | Type | Description | |---|---|---| | **webhook_type** | string | Event type identifier | | **key** | string | DEBT-KEY — unique identifier of the debt at QI SCD (UUID) | | **status** | string | Current debt status | | **event_datetime** | string | Event date and time (ISO 8601) | | **data** | object | **[Data Object](#data-object)** — Operation data | ### Data Object | Field | Type | Description | |---|---|---| | **borrower** | object | **[Borrower Response Object](#borrower-response-object)** — Borrower data | | **contract** | object | **[Contract Response Object](#contract-response-object)** — Contract data | | **requester_identifier_key** | string | Requester identifier key (UUID) | | **iof_charge_method** | string | IOF charge method — always "financed" | | **collaterals** | array | List of operation collaterals | | **contract_fees** | array | **[Contract Fees Object](#contract-fees-object)** — QI Tech fees charged in the operation | | **external_contract_fees** | array | **[External Contract Fees Object](#external-contract-fees-object)** — External fees charged in the operation | | **external_contract_fee_amount** | float | Total amount of external fees | | **net_external_contract_fee_amount** | float | Net amount of external fees after taxes | | **contract_fee_amount** | float | Total amount of QI Tech fees | | **issue_amount** | float | Nominal amount of the credit operation | | **assignment_amount** | float | Assignment amount of the credit operation | | **cet** | string | Monthly Total Effective Cost | | **annual_cet** | string | Annual Total Effective Cost | | **number_of_installments** | integer | Number of installments | | **base_iof** | float | Base IOF amount | | **additional_iof** | float | Additional IOF amount | | **total_iof** | float | Total IOF amount | | **ipoc_code** | string | Brazilian credit registration code generated by QI Tech | | **prefixed_interest_rate** | object | **[Interest Rate Response Object](#interest-rate-response-object)** — Nominal interest rate | | **installments** | array | **[Installments Response Object](#installments-response-object)** — Operation installments | | **disbursement_account** | array | **[Disbursement Account Response Object](#disbursement-account-response-object)** — Disbursement account data (only for PIX-by-key or QR Code disbursements) | | **total_pre_fixed_amount** | float | Total pre-fixed interest amount across all installments | ### Disbursement Account Response Object Returned only when the disbursement is via **PIX key** (`pix_key`) or **QR Code** (`qr_code_key` / `qr_code_url`). For TED, manual PIX, or bank-slip disbursements, the `disbursement_account` field **is not present** in the response. | Field | Type | Description | |---|---|---| | **name** | string | Destination account holder's name (always in clear text). | | **document_number** | string | CPF or CNPJ of the destination account holder. **CPF (11 digits) is returned masked** as `***XXXXXX**` when the account was resolved via QR Code; **CNPJ (14 digits) is returned in full**. In the `pix_key` flow with DICT lookup, it is returned without masking. | | **pix_key** | string | Recipient's PIX key (client input or extracted from the decoded QR Code). | | **qr_code_key** | string | UUID of the PIX QR Code when disbursement was via registered QR. | | **qr_code_url** | string | EMV copy-and-paste of the QR Code when disbursement was via copy-and-paste QR. | | **account_branch** | string | Destination account branch (populated in `pix_key` flow with DICT lookup). | | **account_number** | string | Destination account number. | | **account_digit** | string | Destination account check digit. | | **account_type** | string | Destination account type. | | **ispb** | string | ISPB code of the destination financial institution. | | **percentage_receivable** | float | Percentage of the disbursement allocated to this account. | | **amount_receivable** | float | Fixed amount allocated to this account. | | **end_to_end_id** | string | PIX end-to-end identifier, assigned after decoding/lookup. | :::info Conditional behavior The `disbursement_account` field is **strictly populated** with `name` and `document_number` when the flow is PIX (key or QR Code). The remaining fields depend on the disbursement type: for example, in `qr_code_url` the `account_branch`/`account_number`/`account_digit` fields are `null` because the dynamic EMV does not carry them. ::: ### Borrower Response Object | Field | Type | Description | |---|---|---| | **name** | string | Borrower's full name | | **document_number** | string | Borrower's CPF | | **related_party_key** | string | Unique borrower identifier at QI Tech (UUID) | ### Contract Response Object | Field | Type | Description | |---|---|---| | **document_key** | string | Contract document key | | **number** | string | Contract number | | **urls** | array | List of contract document URLs | | **signature_information** | array | **[Signature Information Object](#signature-information-object)** — Signature information | ### Signature Information Object | Field | Type | Description | |---|---|---| | **signer_name** | string | Signer's full name | | **signer_document_number** | string | Signer's CPF | | **signer_role** | string | Signer's role in the operation | | **signer_email** | string | Signer's email | | **signer_external_key** | string | Signer's external key | | **signature_url** | string | URL of the signed document | ### Contract Fees Object | Field | Type | Description | |---|---|---| | **fee_type** | string | Fee type | | **fee_amount** | float | Fee amount | ### External Contract Fees Object | Field | Type | Description | |---|---|---| | **fee_type** | string | External fee type | | **fee_amount** | float | External fee amount | | **tax_amount** | float | Tax amount on the fee | | **net_fee_amount** | float | Net fee amount after taxes | ### Interest Rate Response Object | Field | Type | Description | |---|---|---| | **annual_rate** | float | Annual interest rate | | **created_at** | string | Rate creation timestamp (ISO 8601) | | **daily_rate** | float | Daily interest rate | | **interest_base** | string | Interest calculation base | | **monthly_rate** | float | Monthly interest rate | ### Installments Response Object | Field | Type | Description | |---|---|---| | **accrual_reference_date** | string | Installment calculation reference date | | **additional_costs** | array | List of additional installment costs | | **advanced_paid_amount** | float | Amount paid in advance | | **bank_slip_key** | string | Bank slip key | | **business_due_date** | string | Due date adjusted to the next business day | | **calendar_days** | integer | Calendar days between installments | | **digitable_line** | string | Bank slip digitable line | | **due_date** | string | Installment due date | | **due_interest** | float | Outstanding interest amount on the due date before payment | | **due_principal** | float | Outstanding balance at the installment moment | | **fine_amount** | float | Applied fine amount | | **has_interest** | boolean | Indicates whether interest applies to the installment | | **installment_history** | array | Installment event history | | **installment_key** | string | Unique installment identifier (UUID) | | **installment_number** | integer | Installment number | | **installment_payment** | array | List of payments made on the installment | | **installment_status** | string | Current installment status | | **installment_type** | string | Installment type — always "principal" | | **original_due_principal** | float | Original outstanding balance at issuance | | **original_pre_fixed_amount** | float | Original pre-fixed interest amount at issuance | | **original_principal_amortization_amount** | float | Original principal amortization amount at issuance | | **original_total_amount** | float | Original total installment amount at issuance | | **paid_amount** | float | Amount already paid on the installment | | **paid_at** | string | Payment date | | **post_fixed_amount** | float | Post-fixed interest amount — always 0 | | **pre_fixed_amount** | float | Current pre-fixed interest amount | | **principal_amortization_amount** | float | Principal amortization amount | | **qr_code_key** | string | Pix QR Code key | | **qr_code_url** | string | Pix QR Code URL | | **renegotiation_proposal_key** | string | Renegotiation proposal key, when applicable | | **tax_amount** | float | IOF amount on the installment | | **total_accrual_amount** | float | Total accrued interest amount | | **total_amount** | float | Total installment amount | | **total_paid_amount** | float | Total amount paid on the installment so far | | **workdays** | integer | Business days between installments | --- # Simulação - Emissão Crédito Clean URL: /en/documentation/manual_credito_clean/emissao/simulacao ## Resumo Na QI Tech, disponibilizamos aos nossos clientes a possibilidade de simular os valores de uma operação de crédito antes de sua emissão efetiva. A simulação segue o mesmo padrão da requisição de emissão de dívida, porém não é necessário fornecer os dados cadastrais do tomador e da conta de desembolso. ## Request ENDPOINT /v2/credit_operation/simulation MÉTODO POST Testar no Playground Request Body **disbursed_issue_amount** ```json { "credit_operation_type": "ccb", "disbursed_issue_amount": 2800, "disbursement_date": "2025-09-24", "first_due_date": "2025-10-24", "force_installments_on_workdays": true, "interest_type": "pre_price_days", "issuer_person_type": "natural", "monthly_interest_rate": 0.04488, "number_of_installments": 2, "principal_amortization_month_period": 1 } ``` **installments** ```json { "credit_operation_type": "ccb", "disbursement_date": "2026-01-26", "interest_type": "pre_price_days", "issuer_person_type": "natural", "monthly_interest_rate": 0.04488, "installments": [ { "due_date": "2026-02-26", "amount": 137.48 }, { "due_date": "2026-03-26", "amount": 180.56 } ] } ``` ### Detalhes do Request Body | Campo | Tipo | Descrição | Caracteres | |---|---|---|---| | **credit_operation_type*** | string | Tipo de operação de crédito | **[Enumerador Credit Operation Type](#enumerador-credit-operation-type)** | | **disbursed_issue_amount** | float | Valor efetivamente liberado ao tomador. Obrigatório no fluxo padrão | 15,2 | | **disbursement_date*** | string | Data em que os recursos do empréstimo serão disponibilizados | 10 | | **first_due_date** | string | Data de vencimento da primeira parcela. Obrigatório no fluxo padrão | 10 | | **force_installments_on_workdays** | boolean | Se verdadeiro, move datas de vencimento para o próximo dia útil | - | | **interest_type*** | string | Método de amortização | **[Enumerador Interest Type](#enumerador-interest-type)** | | **issuer_person_type*** | string | Define se o emissor é pessoa física ou jurídica | **[Enumerador Person Type](#enumerador-person-type)** | | **monthly_interest_rate*** | float | Taxa de juros mensal aplicada sobre o saldo principal | 10,6 | | **number_of_installments** | integer | Número de parcelas. Obrigatório no fluxo padrão | 3 | | **principal_amortization_month_period** | integer | Período, em meses, entre as parcelas. Obrigatório no fluxo padrão | 1 | | **installments** | array | Lista de parcelas para simulação. Cada item deve conter `due_date` e `amount`. Utilizar em substituição a `number_of_installments` + `first_due_date` | **[Objeto Installments Request](#objeto-installments-request)** | ### Objeto Installments Request | Campo | Tipo | Descrição | Caracteres | |---|---|---|---| | **due_date*** | string | Data de vencimento da parcela (YYYY-MM-DD) | 10 | | **amount*** | float | Valor total da parcela. O sistema calcula o `disbursed_issue_amount` correspondente | 15,2 | ### Enumerador Credit Operation Type | Valor | Descrição | |---|---| | `ccb` | Cédula de Crédito Bancário | ### Enumerador Interest Type | Valor | Descrição | |---|---| | `pre_price_days` | Juros pré-fixados com amortização Price por dias corridos | | `pre_price` | Juros pré-fixados com amortização Price por meses | | `pre_sac` | Juros pré-fixados com amortização SAC | ### Enumerador Person Type | Valor | Descrição | |---|---| | `natural` | Pessoa física | | `legal` | Pessoa jurídica | ## Response STATUS 200 Response Body ```json { "disbursement_date": "2025-09-24", "issue_amount": 2821.32, "interest_type": "pre_price_days", "assignment_amount": 2829.78, "base_iof": 10.6, "total_iof": 21.32, "additional_iof": 10.72, "cet": 5.09, "annual_cet": 81.39, "first_due_date": "2025-10-24", "disbursed_amount": 2800, "prefixed_interest_rate": { "annual_rate": 0.6935459998, "daily_rate": 0.0014644728, "interest_base": "calendar_days", "monthly_rate": 0.04488 }, "tax_configuration": { "base_rate": 8.2e-05, "additional_rate": 0.0038 }, "fees": [ { "amount": 0.3, "fee_amount": 8.46, "amount_type": "percentage", "fee_type": "spread", "type": "internal" } ], "installments": [ { "due_date": "2025-10-24", "amount": 1507.4, "due_principal": 2821.32, "due_interest": 0, "has_interest": true, "period": 1, "period_workdays": 1.1, "calendar_days": 30, "workdays": 22, "installment_number": 1, "period_to_disbursement": 1, "prefixed_amount": 126.62248868, "period_workdays_to_disbursement": 1.1, "calendar_days_to_disbursement": 30, "workdays_to_disbursement": 22, "tax_amount": 3.39671268, "principal_amortization_amount": 1380.77751132 }, { "due_date": "2025-11-24", "amount": 1507.4, "due_principal": 1440.54248868, "due_interest": 0, "has_interest": true, "period": 1, "period_workdays": 1, "calendar_days": 31, "workdays": 20, "installment_number": 2, "period_to_disbursement": 2, "prefixed_amount": 66.85751132, "period_workdays_to_disbursement": 2.1, "calendar_days_to_disbursement": 61, "workdays_to_disbursement": 42, "tax_amount": 7.20559353, "principal_amortization_amount": 1440.54248868 } ] } ``` ### Detalhes do Response Body | Campo | Tipo | Descrição | |---|---|---| | **annual_cet** | float | Custo Efetivo Total anualizado expresso em decimal | | **assignment_amount** | float | Valor de cessão da operação de crédito | | **cet** | float | Custo Efetivo Total mensal expresso em decimal | | **fees** | array | **[Objeto Fees](#objeto-fees)** - Lista de taxas da QI Tech cobradas na operação | | **disbursed_amount** | float | Valor desembolsado na operação de crédito | | **disbursement_date** | string | Data de desembolso da operação | | **installments** | array | **[Objeto Installments](#objeto-installments)** - Parcelas da operação | | **interest_type** | string | Método de amortização e cálculo de juros | | **additional_iof** | float | IOF adicional aplicado sobre o principal da transação | | **base_iof** | float | Base de cálculo do IOF | | **total_iof** | float | Valor total do IOF aplicado na transação | | **issue_amount** | float | Valor nominal da operação de crédito | | **tax_configuration** | object | **[Objeto Tax Configuration](#objeto-tax-configuration)** - Valores das taxas de IOF | | **first_due_date** | string | Data de vencimento da primeira parcela | | **prefixed_interest_rate** | object | **[Objeto Interest Rate](#objeto-interest-rate)** - Taxa de juros nominal | ### Objeto Fees | Campo | Tipo | Descrição | |---|---|---| | **amount** | float | Valor ou percentual da taxa | | **fee_amount** | float | Valor monetário da taxa | | **amount_type** | string | Tipo do valor (percentage ou fixed) | | **fee_type** | string | Tipo da taxa | | **type** | string | Classificação da taxa (internal ou external) | ### Objeto Installments | Campo | Tipo | Descrição | |---|---|---| | **due_date** | string | Data de vencimento da parcela | | **amount** | float | Valor total da parcela | | **due_principal** | float | Saldo devedor no momento da parcela | | **due_interest** | float | Valor de juros remanescente na data de vencimento antes do pagamento | | **has_interest** | boolean | Indicador de incidência de juros na parcela | | **installment_number** | integer | Número da parcela | | **prefixed_amount** | float | Valor dos juros pré-fixados pagos na parcela | | **tax_amount** | float | Valor do IOF na parcela | | **principal_amortization_amount** | float | Valor de amortização do principal | | **period** | float | Período da parcela | | **period_workdays** | float | Período da parcela em dias úteis | | **period_to_disbursement** | float | Número de períodos acumulados desde o desembolso até a parcela | | **period_workdays_to_disbursement** | float | Número de períodos em dias úteis acumulados desde o desembolso até a parcela | | **calendar_days** | integer | Dias corridos entre parcelas | | **calendar_days_to_disbursement** | integer | Dias corridos acumulados desde o desembolso até a parcela | | **workdays** | integer | Dias úteis entre parcelas | | **workdays_to_disbursement** | integer | Dias úteis acumulados desde o desembolso até a parcela | ### Objeto Tax Configuration | Campo | Tipo | Descrição | |---|---|---| | **base_rate** | float | Taxa base do IOF | | **additional_rate** | float | Taxa adicional do IOF | ### Objeto Interest Rate | Campo | Tipo | Descrição | |---|---|---| | **annual_rate** | float | Taxa de juros anual | | **daily_rate** | float | Taxa de juros diária | | **interest_base** | string | Base de cálculo dos juros | | **monthly_rate** | float | Taxa de juros mensal | --- # Webhooks - Emissão Crédito Clean URL: /en/documentation/manual_credito_clean/emissao/webhooks ## Resumo Após a resposta de sucesso da emissão, você receberá webhooks notificando sobre os eventos do ciclo de vida da operação: assinatura do contrato, desembolso e, eventualmente, cancelamento. :::danger Atenção! Os webhooks não devem ser mapeados de forma estrita. Novos campos podem ser adicionados ao payload sem aviso prévio. ::: ## Webhook de Assinatura Este webhook é enviado quando o contrato (CCB) é assinado com sucesso. WEBHOOK_TYPE debt STATUS signature_finished Webhook Body ```json { "key": "1ebd4a90-2721-4c39-a399-427fa16bca65", "status": "signature_finished", "webhook_type": "debt", "event_datetime": "2025-10-27T17:09:33Z", "signed_contract_url": "https://storage.googleapis.com/sandbox-doc-api/documents/c8b191cb-7b90-4e37-9280-397a597babc1/CCB-TIK11267101212-20251027170925_signed.pdf" } ``` ### Campos do Webhook de Assinatura | Campo | Tipo | Descrição | |---|---|---| | **key** | string | Chave única da dívida (DEBT-KEY) | | **status** | string | Status do evento: `signature_finished` | | **webhook_type** | string | Tipo do webhook: `debt` | | **event_datetime** | string | Data e hora do evento | | **signed_contract_url** | string | URL do contrato assinado (PDF) | ## Webhook de Desembolso Este webhook confirma que o desembolso foi realizado com sucesso. WEBHOOK_TYPE debt STATUS disbursed Webhook Body ```json { "key": "1ebd4a90-2721-4c39-a399-427fa16bca65", "data": { "installments": [ { "due_date": "2025-11-27", "total_amount": 87.43, "installment_key": "e25fb146-0a61-4319-a722-d01b2213d0f9", "pre_fixed_amount": 29.26477451, "installment_number": 1, "principal_amortization_amount": 58.16522549 }, { "due_date": "2025-12-27", "total_amount": 87.43, "installment_key": "2557de2b-6df1-4a8a-b46a-59206ece157f", "pre_fixed_amount": 20.11446867, "installment_number": 2, "principal_amortization_amount": 67.31553133 }, { "due_date": "2026-01-27", "total_amount": 87.43, "installment_key": "cc503d1d-6387-4a1f-bd78-62b248d02ec8", "pre_fixed_amount": 11.07075682, "installment_number": 3, "principal_amortization_amount": 76.35924318 } ], "ted_receipt_list": [], "requester_identifier_key": null }, "status": "disbursed", "webhook_type": "debt", "event_datetime": "2025-10-27T17:10:21Z" } ``` ### Campos do Webhook de Desembolso | Campo | Tipo | Descrição | |---|---|---| | **key** | string | Chave única da dívida (DEBT-KEY) | | **status** | string | Status do evento: `disbursed` | | **webhook_type** | string | Tipo do webhook: `debt` | | **event_datetime** | string | Data e hora do evento | | **data.installments** | array | Lista de parcelas com suas chaves e valores | | **data.ted_receipt_list** | array | Lista de comprovantes de TED (quando aplicável) | ## Webhook de Cancelamento Se a dívida falhar no desembolso ou for devolvida, você receberá um webhook de cancelamento. WEBHOOK_TYPE debt STATUS canceled Webhook Body ```json { "webhook_type": "debt", "key": "1ebd4a90-2721-4c39-a399-427fa16bca65", "event_datetime": "2025-10-27T16:38:59Z", "data": { "cancel_reason": "Operacao cancelada manualmente", "cancel_reason_enumerator": "manual" }, "status": "canceled" } ``` ### Campos do Webhook de Cancelamento | Campo | Tipo | Descrição | |---|---|---| | **key** | string | Chave única da dívida (DEBT-KEY) | | **status** | string | Status do evento: `canceled` | | **webhook_type** | string | Tipo do webhook: `debt` | | **event_datetime** | string | Data e hora do evento | | **data.cancel_reason** | string | Descrição textual do motivo do cancelamento | | **data.cancel_reason_enumerator** | string | Enumerador do motivo do cancelamento | ### Enumeradores de Cancelamento | Enumerador | Descrição | |---|---| | `disbursing_error` | Operação cancelada por erro durante o desembolso | | `waiting_signature` | Operação cancelada por falta de assinatura | | `pix_max_retry` | Operação cancelada porque o banco receptor não processou o desembolso | | `manual` | Operação cancelada manualmente | | `agencia_conta_invalida` | Agência ou número de conta do destinatário inválidos | | `invalid_account` | Número da conta de destino inexistente ou inválido | | `invalid_document_number` | CPF/CNPJ da conta de destino incorreto | | `unsupported_transaction` | A conta de destino não suporta este tipo de transação | | `invalid_ispb` | O número ISPB é inválido ou inexistente | | `rejected_payment` | Ordem de pagamento rejeitada pelo banco receptor | | `refund_after_payee_request` | Estorno solicitado pelo beneficiário | | `blocked_account` | A conta de destino está bloqueada | | `amount_too_great` | Valor excede o limite da conta de destino | | `receiver_error` | Transação interrompida por erro no PSP do receptor | | `closed_account` | A conta de destino está encerrada | | `disbursing_hour_closed` | Desembolso fora do horário permitido | | `unregistered_pix_key` | A chave Pix não está registrada | | `spi_timeout` | Timeout no controle SPI | --- ## Webhook de Quitação Quando todas as parcelas são pagas e a operação é quitada integralmente, o sistema envia este webhook. WEBHOOK_TYPE debt STATUS settled Webhook Body ```json { "key": "1ebd4a90-2721-4c39-a399-427fa16bca65", "data": { "settlement_amount": 3429.38 }, "status": "settled", "webhook_type": "debt", "event_datetime": "2025-10-27T07:03:49Z" } ``` ### Campos do Webhook de Quitação | Campo | Tipo | Descrição | |---|---|---| | **key** | string | Chave única da dívida (DEBT-KEY) | | **status** | string | Status do evento: `settled` | | **webhook_type** | string | Tipo do webhook: `debt` | | **event_datetime** | string | Data e hora do evento | | **data.settlement_amount** | float | Valor total liquidado | ## Webhook de Confirmação de Cessão Este webhook é enviado quando uma cessão de operações de crédito é processada. Ele notifica que o processo de cessão foi iniciado e fornece os metadados necessários para rastreamento. WEBHOOK_TYPE assignment.status_change Webhook Body ```json { "key": "b866dc02-73db-42a4-bc66-866d465cbb73", "webhook_type": "assignment.status_change", "event_datetime": "2026-04-10T22:37:52Z", "data": { "assignment_key": "550e8400-e29b-41d4-a716-446655440000", "term_of_assignment_url": "https://example.com/terms/cessao.pdf", "number_of_items": 1, "total_amount": 1000, "reference_date": "2026-04-10" } } ``` ### Campos do Webhook de Confirmação de Cessão | Campo | Tipo | Descrição | |---|---|---| | **key** | string | Chave única da cessão | | **webhook_type** | string | Tipo do webhook: `assignment.status_change` | | **event_datetime** | string | Data e hora do evento | | **data.assignment_key** | string | Identificador único da cessão (UUID) | | **data.term_of_assignment_url** | string | URL para download do Termo de Cessão (PDF) | | **data.number_of_items** | integer | Total de operações de crédito incluídas na cessão | | **data.total_amount** | float | Soma do valor presente de todos os itens da cessão | | **data.reference_date** | string | Data base utilizada nos cálculos da cessão (YYYY-MM-DD) | --- ## Webhook de Cancelamento Permanente Operações com status `canceled` são automaticamente canceladas de forma permanente após 7 dias. O cancelamento permanente também pode ser acionado manualmente via endpoint `/debt/{debt_key}/cancel_permanently`. WEBHOOK_TYPE debt STATUS canceled_permanently Webhook Body ```json { "key": "1ebd4a90-2721-4c39-a399-427fa16bca65", "data": {}, "status": "canceled_permanently", "webhook_type": "debt", "event_datetime": "2025-10-27T03:46:31Z" } ``` ### Campos do Webhook de Cancelamento Permanente | Campo | Tipo | Descrição | |---|---|---| | **key** | string | Chave única da dívida (DEBT-KEY) | | **status** | string | Status do evento: `canceled_permanently` | | **webhook_type** | string | Tipo do webhook: `debt` | | **event_datetime** | string | Data e hora do evento | --- ## Webhook de Atualização de Parcela Enviado quando o status de uma parcela é atualizado (pagamento, vencimento, antecipação, etc.). WEBHOOK_TYPE installment.status_change :::info Documentação completa Payload detalhado e todos os status possíveis estão em [Webhooks de Parcelas](/documentation/webhooks/parcelas). ::: ### Status de parcela | Status | Descrição | |---|---| | `opened` | Parcela em aberto | | `paid` | Parcela paga | | `waiting_payment` | Aguardando pagamento | | `paid_early` | Parcela paga antecipadamente | | `paid_partial` | Parcela paga parcialmente | | `overdue` | Parcela vencida | | `paid_partial_overdue` | Parcela paga parcialmente após vencimento | | `paid_overdue` | Parcela paga após vencimento | --- # Estorno Crédito Clean URL: /en/documentation/manual_credito_clean/estorno/ ## Resumo O estorno de uma operação Crédito Clean permite reverter o desembolso realizado. Existem três cenários de cancelamento/estorno: 1. **Cancelamento antes do desembolso**: Cancela a operação antes que os recursos sejam transferidos 2. **Estorno após o desembolso — via Pix de devolução (até 7 dias)**: Gera um Pix copia-e-cola para que o tomador devolva os recursos 3. **Estorno após o desembolso — via conta interna QI**: A devolução é feita diretamente pela conta interna da QI Tech, sem ação do tomador --- ## 1. Cancelamento Antes do Desembolso Cancela uma operação de crédito que ainda não foi desembolsada. ### Request ENDPOINT /debt/ DEBT-KEY /cancel MÉTODO PATCH Testar no Playground ### Path Params | Campo | Tipo | Descrição | Caracteres | |---|---|---|---| | `debt_key`* | string | Chave única da dívida retornada no momento da criação da operação de crédito | UUID | ### Response STATUS 200 Response Body ```json {} ``` :::caution Atenção Este endpoint só pode ser utilizado para operações que ainda **não foram desembolsadas**. Para operações já desembolsadas, utilize o endpoint de estorno abaixo. ::: --- ## 2. Estorno Após o Desembolso — Via Pix de Devolução (Até 7 Dias) Utilizado quando o parceiro deseja solicitar ao tomador que devolva os recursos via Pix. O sistema gera um Pix copia-e-cola para que o tomador realize a devolução. Assim que o pagamento é confirmado, a operação é cancelada automaticamente. :::info Quando usar Use este endpoint quando o estorno deve ser realizado pelo **próprio tomador**, que receberá um Pix de devolução para pagar. ::: ### Request ENDPOINT /debt/reversal MÉTODO POST Testar no Playground Request Body ```json { "credit_operation_key": "72760166-4ddf-41fb-8a8c-605f8f4fc35c" } ``` ### Body Params | Campo | Tipo | Descrição | Caracteres | |---|---|---|---| | `credit_operation_key`* | string | Chave da operação de crédito (DEBT-KEY) | UUID | ### Response STATUS 200 Response Body ```json { "payer_name": "Dante Ferrarini", "payer_document_number": "31057466093", "amount": 1000, "expiration_date": "2026-04-28", "copy_paste_pix": "00020126930014br.gov.bcb.pix2571qrcode-h.sandbox.qitech.app/bacen/cobv/fb1906ab2eff40109609855ac104f60e5204000053039865802BR5925QISOCIEDADEDECREDITODIRET6008SaoPaulo61080145200062070503***63046387", "reversal_key": "7a18fdb6-a3e7-4fc9-833e-0f6d8e98de3b", "status": "active", "debt_key": "72760166-4ddf-41fb-8a8c-605f8f4fc35c", "qr_code_key": "fb1906ab-2eff-4010-9609-855ac104f60e" } ``` ### Detalhes do Response | Campo | Tipo | Descrição | |---|---|---| | **payer_name** | string | Nome do tomador | | **payer_document_number** | string | CPF/CNPJ do tomador | | **amount** | float | Valor total a ser devolvido | | **expiration_date** | string | Data de expiração do Pix de devolução | | **copy_paste_pix** | string | Código Pix copia-e-cola para devolução dos recursos | | **reversal_key** | string | Chave única do estorno (UUID) | | **status** | string | Status do estorno: `active` | | **debt_key** | string | Chave da dívida (DEBT-KEY) | | **qr_code_key** | string | Chave do QR Code Pix (UUID) | :::warning Importante - O estorno só pode ser realizado dentro de **7 dias corridos** após o desembolso - O `copy_paste_pix` gerado possui uma **data de expiração**. Após essa data, o Pix não poderá mais ser utilizado - Após o pagamento do Pix pelo tomador, a operação será cancelada automaticamente e você receberá um webhook de cancelamento ::: --- ## 3. Estorno Após o Desembolso — Via Conta Interna QI Utilizado quando a devolução dos recursos é realizada diretamente pela **conta interna da QI Tech**, sem necessidade de ação do tomador. Indicado para o método `internal`, onde o valor é debitado internamente sem geração de Pix. :::info Quando usar Use este endpoint quando o estorno é operado pelo **parceiro via conta interna da QI Tech**, sem envolver o tomador no processo de devolução. ::: ### Request ENDPOINT /credit_operation/ CREDIT-OPERATION-KEY /reversal MÉTODO PUT :::info Header obrigatório Envie o header `SELECTED-AGENT` com o valor do seu `requester_key`. ::: ### Path Params | Campo | Tipo | Descrição | Caracteres | |---|---|---|---| | `credit_operation_key`* | string | Chave da operação de crédito (DEBT-KEY) | UUID | Request Body (opcional) ```json { "cancel_reason": "reversed_manually" } ``` ### Body Params | Campo | Tipo | Descrição | Caracteres | |---|---|---|---| | `cancel_reason` | string | Motivo do estorno. Se não informado, o sistema utilizará o padrão. | - | --- # Webhooks - Estorno Crédito Clean URL: /en/documentation/manual_credito_clean/estorno/webhooks ## Resumo Após a criação de um pedido de estorno, o sistema enviará webhooks para notificar sobre os eventos do processo de reversão. :::danger Atenção! Os webhooks não devem ser mapeados de forma estrita. Novos campos podem ser adicionados ao payload sem aviso prévio. ::: ## Webhook de Cancelamento por Estorno Quando o tomador realiza o pagamento do Pix de devolução gerado pelo estorno, a operação de crédito é cancelada automaticamente e o seguinte webhook é enviado: WEBHOOK_TYPE debt STATUS canceled Webhook Body ```json { "webhook_type": "debt", "key": "1ebd4a90-2721-4c39-a399-427fa16bca65", "event_datetime": "2025-10-27T16:38:59Z", "data": { "cancel_reason": "Operacao cancelada por estorno", "cancel_reason_enumerator": "refund_after_payee_request" }, "status": "canceled" } ``` ### Campos do Webhook | Campo | Tipo | Descrição | |---|---|---| | **webhook_type** | string | Tipo do webhook: `debt` | | **key** | string | Chave única da dívida (DEBT-KEY) | | **event_datetime** | string | Data e hora do evento | | **status** | string | Status do evento: `canceled` | | **data.cancel_reason** | string | Descrição textual do motivo do cancelamento | | **data.cancel_reason_enumerator** | string | Enumerador do motivo do cancelamento | ### Enumeradores de Cancelamento Relacionados a Estorno | Enumerador | Descrição | |---|---| | `refund_after_payee_request` | Estorno solicitado pelo beneficiário | | `manual` | Operação cancelada manualmente | | `disbursing_error` | Operação cancelada por erro durante o desembolso | --- ## Webhook de Liquidação de Estorno (Transaction Reversal) Para estornos processados via o endpoint de `transaction_reversal`, o webhook de confirmação segue o formato abaixo: WEBHOOK_TYPE transaction_reversal.transaction_reversal_status_change STATUS paid Webhook Body ```json { "data": { "transaction_reversal_key": "b6da1a84-5bb3-4d71-9912-cbbcfe7189c1", "amount": 123.45, "status": "paid", "description": "Valor de liquidação indevido", "reference_date": "2025-03-23", "fund_class_document_number": "12.345.678/0009-10", "fund_class_key": "0619574f-2815-419d-8208-630b0dc30487", "source_account": { "account_digit": "7", "account_branch": "0001", "account_number": "0099999", "owner": { "name": "FUNDO DE INVESTIMENTO", "document_number": "12.345.678/0009-10" }, "financial_institution": { "code": "329", "ispb": "32402502", "name": "QI Sociedade de Crédito Direto" } }, "target_account": { "owner": { "name": "Nome fictício", "document_number": "111.202.188-99" }, "account_digit": "0", "account_branch": "0001", "account_number": "1029490", "target_pix_key": "1232221", "financial_institution": { "code": "033", "ispb": "90400888", "name": "BCO SANTANDER (BRASIL) S.A." } }, "external_key": "40054daa-c3c5-49cd-add7-858b576c5887" }, "webhook_type": "transaction_reversal.transaction_reversal_status_change", "webhook_datetime": "2025-03-23T15:08:30Z" } ``` ### Campos do Webhook de Transaction Reversal | Campo | Tipo | Descrição | |---|---|---| | **webhook_type** | string | Tipo do webhook: `transaction_reversal.transaction_reversal_status_change` | | **webhook_datetime** | string | Data e hora do envio do webhook | | **data.transaction_reversal_key** | string | Chave única do estorno | | **data.amount** | float | Valor estornado | | **data.status** | string | Status do estorno: `paid` | | **data.description** | string | Descrição do estorno | | **data.reference_date** | string | Data de referência do processamento | | **data.fund_class_key** | string | Chave do fundo | | **data.source_account** | object | Dados da conta de origem do estorno | | **data.target_account** | object | Dados da conta de destino do estorno | | **data.external_key** | string | Chave externa da transação estornada | --- ## Webhook de Devolução de Indevido Quando um valor indevido é identificado e a devolução é processada com sucesso, o sistema envia este webhook. WEBHOOK_TYPE laas.devolution.refund_receipt STATUS refunded Webhook Body ```json { "event_datetime": "2024-01-15T14:30:00.000Z", "key": "fb34e0ac-2c98-47e7-9040-406b8c3d80e7", "status": "refunded", "webhook_type": "laas.devolution.refund_receipt", "data": { "origin_key": "b41c63e4-6912-4217-9111-a47dd4da9588", "devolution_key": "336f0e15-e7b8-45a4-8986-5411434be76a", "devolution_amount": 150.75, "devolution_status": "refunded", "devolution_reason_description": "The payment arrived earlier than expected. The difference between the paid amount and the present value should be refund", "receipt_url": "https://storage.googleapis.com/receipts/devolution_receipt_12345.pdf", "document_key": "cd27a0c3-630d-4682-81b2-71b5b325bcde", "transacted_at": "2024-01-15T14:25:30.000Z", "devolution_origin_type": "social_security" } } ``` ### Campos do Webhook de Devolução | Campo | Tipo | Descrição | |---|---|---| | **webhook_type** | string | Tipo do webhook: `laas.devolution.refund_receipt` | | **key** | string | Chave única da devolução | | **event_datetime** | string | Data e hora do evento | | **status** | string | Status: `refunded` | | **data.origin_key** | string | Chave de referência do recurso devolvido | | **data.devolution_key** | string | Chave única da devolução | | **data.devolution_amount** | float | Valor da devolução em reais | | **data.devolution_status** | string | Status da devolução | | **data.devolution_reason_description** | string | Descrição do motivo da devolução | | **data.receipt_url** | string | URL do comprovante da devolução | | **data.document_key** | string | Chave do documento relacionado | | **data.transacted_at** | string | Data e hora da transação (ISO 8601 UTC) | | **data.devolution_origin_type** | string | Origem da devolução | --- # Notificações - Crédito Clean URL: /en/documentation/manual_credito_clean/notificacoes ## Resumo O sistema de notificações permite consultar e reenviar webhooks de eventos do ciclo de vida da operação. Utilize estes endpoints para diagnosticar falhas de entrega e disparar retentativas. :::danger Atenção! Os webhooks não devem ser mapeados de forma estrita. Novos campos podem ser adicionados ao payload sem aviso prévio. ::: ## Webhooks do Crédito Clean Os webhooks gerados pelo Crédito Clean são distribuídos pelas páginas de cada fluxo: | Webhook Type | Status | Documentação | |---|---|---| | `debt` | `signature_finished` | [Emissão — Webhooks](./emissao/webhooks) | | `debt` | `disbursed` | [Emissão — Webhooks](./emissao/webhooks) | | `debt` | `canceled` | [Emissão — Webhooks](./emissao/webhooks) | | `debt` | `settled` | [Emissão — Webhooks](./emissao/webhooks) | | `debt` | `canceled_permanently` | [Emissão — Webhooks](./emissao/webhooks) | | `installment.status_change` | — | [Emissão — Webhooks](./emissao/webhooks) | | `debt` | `canceled` (estorno) | [Estorno — Webhooks](./estorno/webhooks) | | `transaction_reversal.transaction_reversal_status_change` | `paid` | [Estorno — Webhooks](./estorno/webhooks) | | `laas.devolution.refund_receipt` | `refunded` | [Estorno — Webhooks](./estorno/webhooks) | | `renegotiation.proposal` | `paid` | [Renegociação — Webhooks](./renegociacao/webhooks) | | `renegotiation.batch_proposal` | `paid` | [Renegociação — Webhooks](./renegociacao/webhooks) | | `renegotiation.batch_proposal` | `rejected` | [Renegociação — Webhooks](./renegociacao/webhooks) | --- ## Consultando Eventos para Reenvio ENDPOINT /notification/events MÉTODO GET ### Query Parameters | Parâmetro | Tipo | Descrição | |---|---|---| | **event_type** | string | Tipo do evento (ex: `debt_disbursed`) | | **callback_status** | string | Status do callback (ex: `failed`, `sent`) | | **origin_key** | uuid | Chave única do recurso de origem | | **start_datetime** | string | Data/hora inicial (formato `YYYY-MM-DDTHH:mm:ssZ`, UTC) | | **end_datetime** | string | Data/hora final (formato `YYYY-MM-DDTHH:mm:ssZ`, UTC) | :::caution Limite de janela A janela entre `start_datetime` e `end_datetime` deve ser de no máximo **14 dias**. ::: Response Body (200) ```json { "data": [ { "event_key": "", "event_type": "debt_disbursed", "status": "processed", "origin_enumerator": "account", "origin_key": "", "callbacks": [ { "callback_key": "", "callback_status": "failed" } ] } ], "pagination": { "current_page": 1, "rows_per_page": 25 } } ``` --- ## Reenviando um Callback ENDPOINT /notification/event/{`{event_key}`}/callback/{`{callback_key}`}/retry MÉTODO PATCH ### Path Parameters | Parâmetro | Tipo | Descrição | |---|---|---| | **event_key** | uuid | Chave do evento (obtida na listagem) | | **callback_key** | uuid | Chave do callback (obtida na listagem) | Retorna `204 No Content` em caso de sucesso. :::info Documentação completa Instruções detalhadas e exemplos de troubleshooting estão em [Reenvio de Notificações](/documentation/notificacoes/reenvio_de_notificacoes). ::: --- # Consulta de Valor Presente - Refinanciamento Crédito Clean URL: /en/documentation/manual_credito_clean/refinanciamento/consulta_valor_presente ## Resumo Para descobrir o valor presente que será utilizado no refinanciamento de uma operação, é possível utilizar o endpoint de consulta de dívidas indicando os query params listados abaixo. ## Request ENDPOINT /debt MÉTODO GET ### Query Params | Campo | Tipo | Descrição | |---|---|---| | `key`* | string | Chave da dívida (DEBT-KEY) retornada no momento da criação da operação de crédito | | `eval_present_value`* | string | Indica que o valor atual de cada parcela deve ser calculado e mostrado (`true`) | | `calculate_delay`* | string | Indica que, se a parcela estiver vencida, os juros de mora e multa devem ser calculados com o valor presente (`true`) | | `calculate_spread`* | string | Indica se o valor de spread da operação deve ser adicionado ao valor presente. Para operações de refinanciamento deve ser `false` | ### Exemplo de URL ``` /debt?key=72760166-4ddf-41fb-8a8c-605f8f4fc35c&eval_present_value=true&calculate_delay=true&calculate_spread=false ``` ### Response STATUS 200 Response Body ```json { "webhook_type": "debt", "operation_key": "72760166-4ddf-41fb-8a8c-605f8f4fc35c", "status": "opened", "data": { "credit_operation_key": "72760166-4ddf-41fb-8a8c-605f8f4fc35c", "contract_number": "DWF1761222116", "annual_cet": 97.05, "cet": 5.82, "disbursed_issue_amount": 1000, "disbursement_date": "2026-04-07", "issue_amount": 1007.62, "final_disbursement_amount": 1000, "number_of_installments": 2, "total_iof": 7.62, "base_iof": 3.79, "additional_iof": 3.83, "assignment_amount": 1007.63, "issuer_name": "Dante Ferrarini", "issuer_document_number": "31057466093", "prefixed_interest_rate": { "annual_rate": 0.8373372409, "daily_rate": 0.0016911989, "interest_base": { "enumerator": "calendar_days", "year_days": 360 }, "monthly_rate": 0.052 }, "installments": [ { "installment_key": "1dea396f-beb1-4df3-9822-35800b4c095a", "installment_number": 1, "due_date": "2026-05-07", "business_due_date": "2026-05-07", "calendar_days": 30, "total_amount": 543.89, "due_principal": 1007.62, "pre_fixed_amount": 52.3996159, "principal_amortization_amount": 491.4903841, "tax_amount": 1.20906634, "installment_status": { "enumerator": "opened" }, "paid_amount": 0, "present_amount": 517.01, "workdays": 20 }, { "installment_key": "370e73d1-55d8-431e-9b22-d08fb8297999", "installment_number": 2, "due_date": "2026-06-07", "business_due_date": "2026-06-08", "calendar_days": 31, "total_amount": 543.89, "due_principal": 516.1296159, "pre_fixed_amount": 27.7603841, "principal_amortization_amount": 516.1296159, "tax_amount": 2.58168034, "installment_status": { "enumerator": "opened" }, "paid_amount": 0, "present_amount": 490.62, "workdays": 20 } ] } } ``` :::tip Valor para Refinanciamento O valor total a ser utilizado como `disbursed_amount` na simulação/criação do refinanciamento é a soma dos `present_amount` de todas as parcelas. Neste exemplo: 517.01 + 490.62 = **1007.63**. ::: :::caution Atenção Para operações de refinanciamento, o campo `calculate_spread` deve ser sempre `false`, pois o valor de spread não deve ser considerado no cálculo do valor presente para quitação. ::: --- # Criação - Refinanciamento Crédito Clean URL: /en/documentation/manual_credito_clean/refinanciamento/criacao ## Resumo A criação de um refinanciamento utiliza o mesmo endpoint e payload da emissão (`/signed_debt`), com a adição do objeto `refinanced_credit_operations` contendo a lista de operações que serão quitadas. O somatório do valor presente dos contratos anteriores será retido e apenas o excedente será liberado na conta do tomador. ## Request ENDPOINT /signed_debt MÉTODO POST Testar no Playground Request Body ```json { "borrower": { "name": "Dante Ferrarini", "email": "", "phone": { "number": "185633631", "area_code": "15", "country_code": "086" }, "is_pep": false, "address": { "city": "São Paulo", "state": "SP", "number": "", "street": "Rua Gilberto Sabino", "postal_code": "05425020", "neighborhood": "Pinheiros", "complement": "" }, "role_type": "issuer", "birth_date": "1993-09-10", "person_type": "natural", "attached_documents_list": [ { "selfie": "250e7e95-57c8-40bd-a0cd-0be8eb172916" } ], "individual_document_number": "31057466093" }, "financial": { "disbursed_amount": 1007.63, "interest_type": "pre_price_days", "credit_operation_type": "ccb", "annual_interest_rate": 2.32, "disbursement_date": "2026-04-07", "interest_grace_period": 0, "principal_grace_period": 0, "number_of_installments": 3, "fine_configuration": { "contract_fine_rate": 0.02, "interest_base": "calendar_days", "monthly_rate": 0.01 } }, "simplified": true, "additional_data": { "contract": { "contract_number": "DWFR00000012", "signatures": [ { "signer": { "name": "Dante Ferrarini", "email": "", "phone": { "number": "185633631", "area_code": "15", "country_code": "086" }, "document_number": "31057466093" }, "signature": { "timestamp": "2026-04-08T00:40:30Z", "ip_address": "192.168.1.1", "signature_file": { "file_url": "https://qitech.com.br/signature.pdf", "file_type": "pdf" } } } ] } }, "refinanced_credit_operations": [ { "operation_key": "72760166-4ddf-41fb-8a8c-605f8f4fc35c" } ], "requester_identifier_key": "d2107ef5-19df-4183-bf0e-802b8229933c", "purchaser_document_number": "32402502000135", "disbursement_bank_accounts": [ { "name": "company name", "ispb_number": "32402502", "account_digit": "5", "branch_number": "0001", "account_number": "7617846", "document_number": "32246162000281", "percentage_receivable": 100 } ] } ``` :::caution Atenção O payload é **idêntico** ao da emissão (`/signed_debt`), com a adição do campo **`refinanced_credit_operations`** contendo a lista de operações a serem quitadas. ::: ### Detalhes do Request Body O payload contém todos os campos da [Emissão Crédito Clean](../emissao/emissao), com a adição de: | Campo | Tipo | Descrição | Caracteres | |---|---|---|---| | **refinanced_credit_operations*** | array | Lista de operações a serem refinanciadas | **[Objeto Refinanced Credit Operations](#objeto-refinanced-credit-operations)** | Todos os demais campos seguem a mesma especificação da emissão: - **[Objeto Borrower](../emissao/emissao#objeto-borrower)** - **[Objeto Additional Data](../emissao/emissao#objeto-additional-data)** - **[Objeto Disbursement Bank Account](../emissao/emissao#objeto-disbursement-bank-account)** :::info Diferença no Objeto Financial No refinanciamento, o campo `financial` utiliza `annual_interest_rate` ao invés de `monthly_interest_rate`, e o `disbursed_amount` deve ser o valor presente total da operação a ser refinanciada (obtido na consulta de valor presente). ::: ### Objeto Refinanced Credit Operations | Campo | Tipo | Descrição | Caracteres | |---|---|---|---| | `operation_key`* | string | Chave da operação a ser refinanciada (DEBT-KEY da operação original) | UUID | ## Response A resposta segue o mesmo formato da emissão de dívida, retornando a **DEBT-KEY** do novo contrato. STATUS 201 Response Body ```json { "webhook_type": "debt", "key": "290f042f-eedd-4d9d-b621-3a81df0181b6", "status": "opened", "event_datetime": "2026-04-08 00:40:37", "data": { "borrower": { "name": "Dante Ferrarini", "document_number": "31057466093", "related_party_key": "3d62f3c6-1ae5-49f9-aa5d-21a08d95aad6" }, "contract": { "document_key": null, "number": "DWFR00000012", "urls": [], "signature_information": [ { "signer_name": "Dante Ferrarini", "signer_document_number": "31057466093", "signer_role": "issuer", "signer_email": null, "signer_external_key": null, "signature_url": null } ] }, "requester_identifier_key": "d2107ef5-19df-4183-bf0e-802b8229933c", "iof_charge_method": "financed", "collaterals": [], "contract_fees": [ { "fee_type": "spread", "fee_amount": 3.05 }, { "fee_type": "spread_refinancing", "fee_amount": 3.02 } ], "external_contract_fees": [ { "fee_type": "tac", "fee_amount": 0, "tax_amount": 0, "net_fee_amount": 0 } ], "external_contract_fee_amount": 0, "net_external_contract_fee_amount": 0, "contract_fee_amount": 6.07, "issue_amount": 1016.72, "assignment_amount": 1022.79, "cet": "11,1900%", "annual_cet": "256,9982%", "number_of_installments": 3, "base_iof": 5.23, "additional_iof": 3.86, "total_iof": 9.09, "ipoc_code": "324025020203131057466093DWFR00000012", "prefixed_interest_rate": { "annual_rate": 2.32, "created_at": "2026-04-08T00:40:30", "daily_rate": 0.0033387969, "interest_base": "calendar_days", "monthly_rate": 0.1051676747 }, "installments": [ { "accrual_reference_date": null, "additional_costs": [], "advanced_paid_amount": 0, "bank_slip_key": null, "business_due_date": "2026-05-07", "calendar_days": 30, "digitable_line": null, "due_date": "2026-05-07", "due_interest": 0, "due_principal": 1016.72, "fine_amount": null, "has_interest": true, "installment_history": [], "installment_key": "52810e9d-0815-4fd1-ab20-d8b37dcd936e", "installment_number": 1, "installment_payment": [], "installment_status": "created", "installment_type": "principal", "original_due_principal": 1016.72, "original_pre_fixed_amount": 106.92260459, "original_principal_amortization_amount": 306.50739541, "original_total_amount": 413.43, "paid_amount": 0, "paid_at": null, "post_fixed_amount": 0, "pre_fixed_amount": 106.92260459, "principal_amortization_amount": 306.50739541, "qr_code_key": null, "qr_code_url": null, "renegotiation_proposal_key": null, "tax_amount": 0.75400819, "total_accrual_amount": null, "total_amount": 413.43, "total_paid_amount": 0, "workdays": 20 }, { "accrual_reference_date": null, "additional_costs": [], "advanced_paid_amount": 0, "bank_slip_key": null, "business_due_date": "2026-06-08", "calendar_days": 31, "digitable_line": null, "due_date": "2026-06-07", "due_interest": 0, "due_principal": 710.21260459, "fine_amount": null, "has_interest": true, "installment_history": [], "installment_key": "2bcfe19e-9847-4c8f-be80-17f646a897c4", "installment_number": 2, "installment_payment": [], "installment_status": "created", "installment_type": "principal", "original_due_principal": 710.21260459, "original_pre_fixed_amount": 77.30856978, "original_principal_amortization_amount": 336.12143022, "original_total_amount": 413.43, "paid_amount": 0, "paid_at": null, "post_fixed_amount": 0, "pre_fixed_amount": 77.30856978, "principal_amortization_amount": 336.12143022, "qr_code_key": null, "qr_code_url": null, "renegotiation_proposal_key": null, "tax_amount": 1.68127939, "total_accrual_amount": null, "total_amount": 413.43, "total_paid_amount": 0, "workdays": 20 }, { "accrual_reference_date": null, "additional_costs": [], "advanced_paid_amount": 0, "bank_slip_key": null, "business_due_date": "2026-07-07", "calendar_days": 30, "digitable_line": null, "due_date": "2026-07-07", "due_interest": 0, "due_principal": 374.09117437, "fine_amount": null, "has_interest": true, "installment_history": [], "installment_key": "7cf785c9-b6cf-4e9b-9c09-61d917bc72b8", "installment_number": 3, "installment_payment": [], "installment_status": "created", "installment_type": "principal", "original_due_principal": 374.09117437, "original_pre_fixed_amount": 39.33882563, "original_principal_amortization_amount": 374.09117437, "original_total_amount": 413.43, "paid_amount": 0, "paid_at": null, "post_fixed_amount": 0, "pre_fixed_amount": 39.33882563, "principal_amortization_amount": 374.09117437, "qr_code_key": null, "qr_code_url": null, "renegotiation_proposal_key": null, "tax_amount": 2.79146834, "total_accrual_amount": null, "total_amount": 413.43, "total_paid_amount": 0, "workdays": 22 } ], "total_pre_fixed_amount": 223.57 } } ``` :::info Observação - O valor presente das operações listadas em `refinanced_credit_operations` será automaticamente retido para quitação dos contratos anteriores - Apenas o excedente (diferença entre o valor desembolsado e o valor retido) será liberado na conta do tomador - Após a criação, os contratos refinanciados serão automaticamente liquidados - Os webhooks de emissão (assinatura, desembolso, cancelamento) seguem o mesmo padrão descrito na seção de [Webhooks da Emissão](../emissao/webhooks) ::: --- # Introdução - Refinanciamento Crédito Clean URL: /en/documentation/manual_credito_clean/refinanciamento/introducao ## Resumo Um refinanciamento consiste na geração de um novo contrato de crédito para a quitação de um anterior. O fluxo funciona da mesma forma que uma emissão de dívida simples, porém, quando informados os valores da operação, o somatório do valor presente dos contratos anteriores será retido e apenas o excedente, caso exista, será liberado na conta do tomador. ## Fluxo do Refinanciamento 1. **Consulta de valor presente**: Consultar o valor presente da operação original para saber o montante necessário para quitação 2. **Simulação**: Simular o refinanciamento com os dados da nova operação e a referência à operação original 3. **Criação**: Criar o refinanciamento informando a lista de operações a serem quitadas em `refinanced_credit_operations` :::info Importante O payload utilizado tanto na simulação quanto na criação de um refinanciamento é o mesmo de uma dívida simples, com a adição da lista de operações que serão quitadas em **`refinanced_credit_operations`**. ::: --- # Simulação - Refinanciamento Crédito Clean URL: /en/documentation/manual_credito_clean/refinanciamento/simulacao ## Resumo Antes de criar um refinanciamento, é possível simular os valores da nova operação. A simulação utiliza o mesmo payload de uma simulação de dívida simples, com a adição do campo `refinanced_credit_operations`. ## Request ENDPOINT /debt_simulation MÉTODO POST Request Body ```json { "borrower": { "person_type": "natural" }, "refinanced_credit_operations": [ { "operation_key": "72760166-4ddf-41fb-8a8c-605f8f4fc35c" } ], "financial": { "disbursed_amount": 1007.63, "interest_type": "pre_price_days", "credit_operation_type": "ccb", "annual_interest_rate": 2.32, "disbursement_date": "2026-04-07", "interest_grace_period": 0, "principal_grace_period": 0, "number_of_installments": 3, "fine_configuration": { "contract_fine_rate": 0.02, "interest_base": "calendar_days", "monthly_rate": 0.01 } } } ``` ### Body Params | Campo | Tipo | Descrição | |---|---|---| | **borrower*** | object | Dados do tomador (mínimo: `person_type`) | | **refinanced_credit_operations*** | array | Lista de operações a serem refinanciadas | | **financial*** | object | Dados financeiros da nova operação | ### Objeto refinanced_credit_operations | Campo | Tipo | Descrição | |---|---|---| | `operation_key`* | string | Chave da operação a ser refinanciada (DEBT-KEY) | ## Response STATUS 200 Response Body ```json { "type": "debt", "key": "daa5173d-ae44-44c5-87bc-f9115cfbcaa1", "status": "finished", "event_datetime": "2026-04-08 00:36:02", "data": { "interest_type": "pre_price_days", "credit_operation_type": "ccb", "interest_grace_period": 0, "interest_payment_month_period": 1, "principal_grace_period": 0, "principal_amortization_month_period": 1, "operation_type": "settlement_refinancing", "prefixed_interest_rate": { "interest_base": "calendar_days_365", "annual_rate": 2.32, "monthly_rate": 0.1051676747, "daily_rate": 0.0032929847 }, "issue_date": "2026-04-07", "number_of_installments": 3, "requester_key": "78287247-947d-4730-9bd1-7efb068175b6", "final_disbursement_amount": 0.01, "refinanced_credit_operations": [ { "refinanced_credit_operation_key": "72760166-4ddf-41fb-8a8c-605f8f4fc35c", "refinanced_credit_operation_status": "pending_payment", "due_balance": 1007.62, "due_balance_reference_date": "2026-04-07", "original_deadline": 61 } ], "total_pre_fixed_amount": 220.27, "iof_amount": 9.09, "cet": 0.1103, "annual_cet": 2.5111, "disbursement_date": "2026-04-07", "installments": [ { "calendar_days": 30, "workdays": 20, "business_due_date": "2026-05-07", "due_date": "2026-05-07", "due_principal": 1016.72, "has_interest": true, "post_fixed_amount": 0, "pre_fixed_amount": 105.38950323, "tax_amount": 0.75507362, "total_amount": 412.33, "principal_amortization_amount": 306.94049677, "installment_number": 1 }, { "calendar_days": 31, "workdays": 20, "business_due_date": "2026-06-08", "due_date": "2026-06-07", "due_principal": 709.77950323, "has_interest": true, "post_fixed_amount": 0, "pre_fixed_amount": 76.15320432, "tax_amount": 1.68155633, "total_amount": 412.33, "principal_amortization_amount": 336.17679568, "installment_number": 2 }, { "calendar_days": 30, "workdays": 22, "business_due_date": "2026-07-07", "due_date": "2026-07-07", "due_principal": 373.60270755, "has_interest": true, "post_fixed_amount": 0, "pre_fixed_amount": 38.72729245, "tax_amount": 2.7878234, "total_amount": 412.33, "principal_amortization_amount": 373.60270755, "installment_number": 3 } ], "external_contract_fees": [ { "fee_type": "tac", "amount_type": "absolute", "amount": 0, "fee_amount": 0, "tax_amount": 0, "net_fee_amount": 0 } ], "contract_fee_amount": 3.05, "external_contract_fee_amount": 0, "net_external_contract_fee_amount": 0, "contract_fees": [ { "fee_type": "spread", "amount_type": "percentage", "amount": 0.3, "fee_amount": 3.05 } ], "issue_amount": 1016.72, "disbursed_issue_amount": 1007.63, "assignment_amount": 1019.77 } } ``` --- # Cenários - Renegociação em Lote Crédito Clean URL: /en/documentation/manual_credito_clean/renegociacao/cenarios ## Resumo Este documento apresenta os principais cenários de renegociação em lote para operações Crédito Clean. Todos os cenários utilizam o `amortization_type: "present_amount"` e permitem aplicar descontos individuais por parcela através do campo `discount_amount` no objeto de cada installment. :::info Lógica de Desconto por Parcela É possível aplicar descontos diferentes em cada parcela individualmente. Basta adicionar o campo `discount_amount` (valor absoluto em reais) dentro do objeto da parcela desejada. Parcelas sem o campo `discount_amount` serão cobradas pelo valor presente integral. ::: --- ## Cenário 1: Empréstimo de 1 Parcela - Pagamento Padrão O tomador possui um empréstimo Crédito Clean de 1 parcela e deseja quitá-lo pelo valor presente. ### Exemplo de Payload ```json { "payment_type": "pix", "amortization_type": "present_amount", "proposal_due_date": "2026-04-10", "discount_percentage": 0, "reference_date": "2026-04-10", "request_control_key": "3571e292-3a83-4011-904d-20ee963022ef", "operations": [ { "debt_key": "bf1175f4-750d-42b9-b264-5e7cd8c1c189", "installments": [ { "installment_key": "0298c572-7b6b-4db0-88d6-4bf1622d3e2d" } ] } ] } ``` --- ## Cenário 2: Empréstimo de 1 Parcela - Pagamento Sem Juros (Interest Free) O tomador possui um empréstimo Crédito Clean de 1 parcela e negocia o pagamento sem juros. O desconto aplicado corresponde ao valor dos juros da parcela. ### Exemplo de Payload ```json { "payment_type": "pix", "amortization_type": "present_amount", "proposal_due_date": "2026-04-10", "discount_percentage": 0, "reference_date": "2026-04-10", "request_control_key": "b2c3d4e5-f6a7-8901-bcde-f12345678901", "operations": [ { "debt_key": "bf1175f4-750d-42b9-b264-5e7cd8c1c189", "installments": [ { "installment_key": "0298c572-7b6b-4db0-88d6-4bf1622d3e2d", "discount_amount": 54.19 } ] } ] } ``` :::info Observação O valor do `discount_amount` (54.19) corresponde ao valor dos juros (`pre_fixed_amount`) da parcela. Dessa forma, o tomador paga apenas o valor do principal. ::: --- ## Cenário 3: Empréstimo de 1 Parcela - Pagamento Sem Juros e Sem IOF (Interest + IOF Free) O tomador possui um empréstimo Crédito Clean de 1 parcela e negocia o pagamento sem juros e sem IOF. O desconto aplicado corresponde à soma dos juros e do IOF da parcela. ### Exemplo de Payload ```json { "payment_type": "pix", "amortization_type": "present_amount", "proposal_due_date": "2026-04-10", "discount_percentage": 0, "reference_date": "2026-04-10", "request_control_key": "c3d4e5f6-a7b8-9012-cdef-123456789012", "operations": [ { "debt_key": "bf1175f4-750d-42b9-b264-5e7cd8c1c189", "installments": [ { "installment_key": "0298c572-7b6b-4db0-88d6-4bf1622d3e2d", "discount_amount": 55.44 } ] } ] } ``` :::info Observação O valor do `discount_amount` (55.44) corresponde à soma dos juros (`pre_fixed_amount`: 54.19) + IOF (`tax_amount`: 1.25) da parcela. Dessa forma, o tomador paga apenas o valor de amortização do principal. ::: --- ## Cenário 4: Empréstimo de Múltiplas Parcelas com Desconto Individual O tomador possui um empréstimo Crédito Clean com várias parcelas e negocia descontos diferentes para parcelas específicas. Parcelas sem o campo `discount_amount` são cobradas pelo valor presente integral. ### Exemplo de Payload ```json { "payment_type": "pix", "amortization_type": "present_amount", "proposal_due_date": "2026-04-10", "discount_percentage": 0, "reference_date": "2026-04-10", "request_control_key": "d4e5f6a7-b8c9-0123-defa-234567890123", "operations": [ { "debt_key": "bf1175f4-750d-42b9-b264-5e7cd8c1c189", "installments": [ { "installment_key": "0298c572-7b6b-4db0-88d6-4bf1622d3e2d", "discount_amount": 20 }, { "installment_key": "5e267f58-0f55-4b12-9582-63e0e9e082a8" }, { "installment_key": "5be492bf-b637-4999-986d-ecf423cc5dd1" }, { "installment_key": "15abfbfd-8608-45e9-abbb-a04c021dcf7b", "discount_amount": 10 }, { "installment_key": "c8eb83b3-5b0d-4326-947c-79279cdce2d6" } ] } ] } ``` :::info Observação Neste exemplo: - Parcela 1: desconto de R$ 20,00 - Parcela 2: sem desconto (valor presente integral) - Parcela 3: sem desconto (valor presente integral) - Parcela 4: desconto de R$ 10,00 - Parcela 5: sem desconto (valor presente integral) ::: --- ## Cenário 5: Pagamento de Parcelas em Atraso (Overdue) O tomador possui parcelas vencidas e deseja quitá-las. As parcelas em atraso já incluem multa e juros de mora calculados automaticamente. É possível aplicar descontos individuais para reduzir o valor. ### Exemplo de Payload ```json { "payment_type": "pix", "amortization_type": "present_amount", "proposal_due_date": "2026-04-10", "discount_percentage": 0, "reference_date": "2026-04-10", "request_control_key": "e5f6a7b8-c9d0-1234-efab-345678901234", "operations": [ { "debt_key": "bf1175f4-750d-42b9-b264-5e7cd8c1c189", "installments": [ { "installment_key": "0298c572-7b6b-4db0-88d6-4bf1622d3e2d", "discount_amount": 15 }, { "installment_key": "5e267f58-0f55-4b12-9582-63e0e9e082a8", "discount_amount": 15 } ] } ] } ``` :::caution Atenção Para parcelas em atraso, o valor presente já inclui multa (`fine_amount`) e juros de mora calculados automaticamente com base na `fine_configuration` do contrato. O `discount_amount` é aplicado sobre esse valor total. ::: --- ## Cenário 6: Múltiplas Operações com Desconto Individual por Parcela O tomador possui empréstimos Crédito Clean em diferentes operações e deseja quitar parcelas de todas em um único pagamento, com descontos individuais. ### Exemplo de Payload ```json { "payment_type": "pix", "amortization_type": "present_amount", "proposal_due_date": "2026-04-10", "discount_percentage": 0, "reference_date": "2026-04-10", "request_control_key": "f6a7b8c9-d0e1-2345-fabc-456789012345", "operations": [ { "debt_key": "bf1175f4-750d-42b9-b264-5e7cd8c1c189", "installments": [ { "installment_key": "0298c572-7b6b-4db0-88d6-4bf1622d3e2d", "discount_amount": 20 }, { "installment_key": "5e267f58-0f55-4b12-9582-63e0e9e082a8" } ] }, { "debt_key": "a2c3d4e5-860f-4b7a-9c1d-2e3f4a5b6c7d", "installments": [ { "installment_key": "7b8c9d0e-1f2a-3b4c-5d6e-7f8a9b0c1d2e", "discount_amount": 30 } ] } ] } ``` --- ## Objeto Installments - Campo Discount | Campo | Tipo | Descrição | Obrigatório | |---|---|---|---| | `installment_key`* | string | Chave da parcela a ser renegociada | Sim | | `discount_amount` | float | Valor de desconto em reais (R$) aplicado individualmente na parcela | Não | :::info Sobre o campo discount_amount - O campo `discount_amount` é **opcional** e pode ser informado em qualquer parcela - O valor é um **desconto absoluto em reais** (não percentual) - Parcelas sem o campo `discount_amount` são cobradas pelo **valor presente integral** - O desconto é aplicado sobre o valor presente da parcela na `reference_date` ::: --- ## Tabela Resumo dos Cenários | Cenário | Descrição | Discount | |---|---|---| | 1 parcela - padrão | Pagamento pelo valor presente | Sem desconto | | 1 parcela - interest free | Desconto = valor dos juros | `discount_amount` = `pre_fixed_amount` | | 1 parcela - interest + IOF free | Desconto = juros + IOF | `discount_amount` = `pre_fixed_amount` + `tax_amount` | | Múltiplas parcelas | Descontos individuais por parcela | `discount_amount` por parcela | | Parcelas em atraso | Parcelas vencidas com multa/mora | `discount_amount` opcional | | Múltiplas operações | Operações diferentes em um lote | `discount_amount` por parcela | --- ## Regras Importantes :::caution Regras da Renegociação em Lote - Todas as operações devem ser do **mesmo emitente** e mesma **chave de integração** - Limite de **50 operações** por lote - Um único meio de pagamento (boleto/Pix) é gerado para o valor total do lote - Se uma parcela incluída no lote for paga por fora antes da confirmação, o lote é **rejeitado** - Se o pagamento não for realizado até a `proposal_due_date`, o lote é **rejeitado** - O `amortization_type` utilizado é sempre `present_amount` - O campo `discount_amount` é aplicado **individualmente por parcela** ::: --- # Consulta - Renegociação em Lote Crédito Clean URL: /en/documentation/manual_credito_clean/renegociacao/consulta ## Resumo É possível consultar o status e detalhes de uma proposta de renegociação em lote, utilizando a `batch_proposal_key` ou a `request_control_key`. --- ## Consultar por Batch Proposal Key ENDPOINT /renegotiation/batch_proposal/ BATCH-PROPOSAL-KEY MÉTODO GET ### Path Params | Campo | Tipo | Descrição | Caracteres | |---|---|---|---| | `batch_proposal_key`* | string | Chave da proposta de renegociação em lote | UUID | ### Response STATUS 200 Response Body ```json { "batch_proposal_key": "ff5ad6dd-2087-4850-a3e8-b37634448b4e", "discount_percentage": 0, "discount_amount": 0, "amortization_type": "installment_payment", "payment_amount": 517.88, "requester_name": "Dante Ltda", "requester_key": "78287247-947d-4730-9bd1-7efb068175b6", "issuer_name": "Dante Ferrarini", "reference_date": "2026-04-08", "issuer_document_number": "31057466093", "batch_proposal_status": "pending_payment", "proposal_due_date": "2026-04-15", "payment_type": "pix", "request_control_key": "94b31045-c8e7-45be-a88d-2ae25c5df5db", "origin_key": null, "operations": [ { "requester_key": "78287247-947d-4730-9bd1-7efb068175b6", "contract_number": "DWF1761222116", "payment_amount": 517.88, "discount_amount": 0, "origin_key": null, "affected_installments": [ { "installment_key": "1dea396f-beb1-4df3-9822-35800b4c095a", "due_date": "2026-05-07", "principal_amount": 491.49, "interest_amount": 52.4, "fine_amount": 0, "total_amount": 543.89, "present_amount": 517.88, "paid_amount": 517.88, "principal_amortization_payment_amount": 491.49, "prefixed_interest_payment_amount": 26.39, "fine_payment_amount": 0, "discount_amount": 0 } ], "remaining_installments": [ { "installment_key": "370e73d1-55d8-431e-9b22-d08fb8297999", "due_date": "2026-06-07", "principal_amount": 516.13, "interest_amount": 27.76, "fine_amount": 0, "total_amount": 543.89 } ], "debt_key": "72760166-4ddf-41fb-8a8c-605f8f4fc35c" } ], "payment": { "digitable_line": null, "qr_code_url": "00020126930014br.gov.bcb.pix2571qrcode-h.sandbox.qitech.app/bacen/cobv/acaeb341e1264cde99b93e247e12b3725204000053039865802BR5925QISOCIEDADEDECREDITODIRET6008SaoPaulo61080145200062070503***63043AD0", "qr_code_key": "acaeb341-e126-4cde-99b9-3e247e12b372", "bank_slip_key": null, "paid_method_type": "pix", "source_account_key": null, "payment_data": { "creditor_bank_account_key": "6108dd45-580d-48c4-b3bb-74c1e843be49", "batch_renegotiation_proposal_key": "ff5ad6dd-2087-4850-a3e8-b37634448b4e" } } } ``` --- ## Consultar por Request Control Key ENDPOINT /renegotiation/batch_proposal/request_control_key/ REQUEST-CONTROL-KEY MÉTODO GET ### Path Params | Campo | Tipo | Descrição | Caracteres | |---|---|---|---| | `request_control_key`* | string | Chave de controle da requisição | UUID | ### Response A resposta segue o mesmo formato da consulta por `batch_proposal_key`. --- ## Listar Renegociações em Lote ENDPOINT /renegotiation/batch_proposal MÉTODO GET ### Query Params | Campo | Tipo | Descrição | |---|---|---| | `batch_proposal_status` | string | Filtrar por status da proposta em lote | | `issuer_document_number` | string | Filtrar por CPF/CNPJ do emitente | | `request_control_key` | string | Filtrar por chave de controle | ### Response STATUS 200 Response Body ```json { "data": [ { "batch_proposal_key": "ff5ad6dd-2087-4850-a3e8-b37634448b4e", "discount_percentage": 0, "discount_amount": 0, "amortization_type": "installment_payment", "payment_amount": 517.88, "requester_name": "Dante Ltda", "requester_key": "78287247-947d-4730-9bd1-7efb068175b6", "issuer_name": "Dante Ferrarini", "reference_date": "2026-04-08", "issuer_document_number": "31057466093", "batch_proposal_status": "pending_payment", "proposal_due_date": "2026-04-15", "payment_type": "pix", "request_control_key": "94b31045-c8e7-45be-a88d-2ae25c5df5db", "origin_key": null } ], "pagination": { "current_page": 1, "next_page": 2, "rows_per_page": 10, "total_pages": 150, "total_rows": 1495 } } ``` --- ## Cancelar uma Renegociação em Lote ENDPOINT /renegotiation/batch_proposal/ BATCH-PROPOSAL-KEY MÉTODO DELETE ### Path Params | Campo | Tipo | Descrição | Caracteres | |---|---|---|---| | `batch_proposal_key`* | string | Chave da proposta de renegociação em lote a ser cancelada | UUID | ### Response STATUS 204 Response Body ```json {} ``` :::caution Atenção Somente propostas com status `pending_payment` podem ser canceladas. ::: --- # Proposta de Renegociação em Lote - Crédito Clean URL: /en/documentation/manual_credito_clean/renegociacao/proposta ## Resumo Após simular os valores, é possível criar uma proposta de renegociação em lote para múltiplas operações Crédito Clean. A proposta gera um único meio de pagamento (boleto e/ou Pix) que cobre todas as operações incluídas no lote. Para o tipo de amortização **`present_amount`**, cada parcela informada em `operations[].installments[]` deve incluir **`paid_amount`** (valor pago/alocado naquela parcela) e **`discount_amount`** (desconto em R$ aplicado na parcela), além de **`installment_key`**. :::caution Atenção A renegociação em lote só pode ser criada com operações de um mesmo emitente e mesma chave de integração. Há um limite de **50 operações** para cada renegociação em lote. ::: ## Request ENDPOINT /renegotiation/batch_proposal MÉTODO POST :::warning Atenção Os campos `discount_amount` e `discount_percentage` **NÃO** podem ser enviados juntos no mesmo payload (nível raiz). ::: :::info Nota Na raiz do body, `discount_amount` e `discount_percentage` são alternativas para desconto global sobre o valor presente. Já os campos **`paid_amount`** e **`discount_amount`** dentro de cada objeto em `operations[].installments[]` definem a composição por parcela quando `amortization_type` é **`present_amount`** (são obrigatórios nesse modo e não conflitam com a regra da raiz). ::: Request Body ```json { "amortization_type": "present_amount", "reference_date": "2026-04-08", "proposal_due_date": "2026-04-15", "discount_percentage": 0.0, "payment_type": "pix", "request_control_key": "94b31045-c8e7-45be-a88d-2ae25c5df5db", "operations": [ { "debt_key": "1baea8a0-0fca-4f7c-8857-a227d4da72f8", "installments": [ { "installment_key": "ca5741c7-99a2-42e7-92a1-9328a36e4e88", "paid_amount": 500, "discount_amount": 50 } ] }, { "debt_key": "2cbfb9b1-1fdb-5f8d-9967-b338e5eb83f9", "installments": [ { "installment_key": "2ef25ed8-7124-44f5-9e3d-1d1a7196166e", "paid_amount": 150, "discount_amount": 10 } ] } ] } ``` ### Body Params | Campo | Tipo | Descrição | Caracteres | |---|---|---|---| | `amortization_type`* | string | Tipo de amortização | **[Enumeradores Amortization Type](#enumeradores-amortization-type)** | | `reference_date`* | string | Data de referência para cálculo do valor presente (D+1) | 10 | | `proposal_due_date`* | string | Data de vencimento da proposta de renegociação | 10 | | `payment_type`* | string | Tipo de pagamento | **[Enumeradores Payment Type](#enumeradores-payment-type)** | | `request_control_key` | string | Chave de controle para rastreamento e identificação única (opcional) | UUID | | `discount_percentage` | float | Percentual de desconto sobre o valor presente | 10 | | `discount_amount` | float | Valor de desconto sobre o valor presente | 10 | | `operations`* | array | Lista de operações a serem renegociadas | **[Objeto Operations](#objeto-operations)** | ### Objeto Operations | Campo | Tipo | Descrição | Caracteres | |---|---|---|---| | `debt_key`* | string | Chave única da operação de crédito (DEBT-KEY) | UUID | | `installments`* | array | Parcelas a serem renegociadas | **[Objeto Installments](#objeto-installments)** | ### Objeto Installments | Campo | Tipo | Descrição | Caracteres | |---|---|---|---| | `installment_key`* | string | Chave da parcela a ser renegociada | UUID | | `paid_amount` | float | Valor pago (ou alocado) na parcela, em reais (R$). Obrigatório quando `amortization_type` é **`present_amount`**. | 15,2 | | `discount_amount` | float | Valor de desconto em reais (R$) aplicado na parcela. Obrigatório quando `amortization_type` é **`present_amount`** (use `0` se não houver desconto). Para outros tipos de amortização, permanece opcional por parcela. | 15,2 | ### Enumeradores Payment Type | Campo | Descrição | |---|---| | `bank_slip` | Pagamento via boleto bancário (gera boleto e Pix) | | `pix` | Pagamento via Pix (gera apenas Pix) | | `internal` | Pagamento via transferência interna (processamento automático) | | `manual` | Pagamento feito de forma manual (não gera forma de pagamento) | ### Enumeradores Amortization Type | Campo | Descrição | |---|---| | **present_amount** | Renegociação com composição por valor presente por parcela. Em cada item de `installments[]` é obrigatório informar `installment_key`, **`paid_amount`** e **`discount_amount`**. | | **installment_payment** | Renegociação para pagamento de parcelas específicas. Requer `installment_key` de cada parcela. | | **overdue_installment_payment** | Renegociação direcionada para pagamento de parcelas em atraso. Requer `installment_key` de cada parcela. | ## Response STATUS 201 Response Body ```json { "batch_proposal_key": "ff5ad6dd-2087-4850-a3e8-b37634448b4e", "discount_percentage": 0, "discount_amount": 0, "amortization_type": "present_amount", "payment_amount": 517.88, "requester_name": "Dante Ltda", "requester_key": "78287247-947d-4730-9bd1-7efb068175b6", "issuer_name": "Dante Ferrarini", "reference_date": "2026-04-08", "issuer_document_number": "31057466093", "batch_proposal_status": "pending_payment", "proposal_due_date": "2026-04-15", "payment_type": "pix", "request_control_key": "94b31045-c8e7-45be-a88d-2ae25c5df5db", "origin_key": null, "operations": [ { "requester_key": "78287247-947d-4730-9bd1-7efb068175b6", "contract_number": "DWF1761222116", "payment_amount": 517.88, "discount_amount": 0, "origin_key": null, "affected_installments": [ { "installment_key": "1dea396f-beb1-4df3-9822-35800b4c095a", "due_date": "2026-05-07", "principal_amount": 491.49, "interest_amount": 52.4, "fine_amount": 0, "total_amount": 543.89, "present_amount": 517.88, "paid_amount": 517.88, "principal_amortization_payment_amount": 491.49, "prefixed_interest_payment_amount": 26.39, "fine_payment_amount": 0, "discount_amount": 0 } ], "remaining_installments": [ { "installment_key": "370e73d1-55d8-431e-9b22-d08fb8297999", "due_date": "2026-06-07", "principal_amount": 516.13, "interest_amount": 27.76, "fine_amount": 0, "total_amount": 543.89 } ], "debt_key": "72760166-4ddf-41fb-8a8c-605f8f4fc35c" } ], "payment": { "digitable_line": null, "qr_code_url": "00020126930014br.gov.bcb.pix2571qrcode-h.sandbox.qitech.app/bacen/cobv/acaeb341e1264cde99b93e247e12b3725204000053039865802BR5925QISOCIEDADEDECREDITODIRET6008SaoPaulo61080145200062070503***63043AD0", "qr_code_key": "acaeb341-e126-4cde-99b9-3e247e12b372", "bank_slip_key": null, "paid_method_type": "pix", "source_account_key": null, "payment_data": { "creditor_bank_account_key": "6108dd45-580d-48c4-b3bb-74c1e843be49", "batch_renegotiation_proposal_key": "ff5ad6dd-2087-4850-a3e8-b37634448b4e" } } } ``` :::info Importante Salve a **batch_proposal_key** retornada na resposta. Ela será necessária para consultar o status da renegociação em lote e para receber os webhooks de pagamento. ::: --- # Simulação - Renegociação em Lote Crédito Clean URL: /en/documentation/manual_credito_clean/renegociacao/simulacao ## Resumo Antes de criar uma proposta de renegociação, é possível simular os valores da renegociação em lote para operações Crédito Clean. A simulação permite visualizar as parcelas afetadas, valores de desconto e o montante final a ser pago para múltiplas operações simultaneamente. Com **`amortization_type`** igual a **`present_amount`**, envie em cada parcela de `operations[].installments[]` os campos **`paid_amount`**, **`discount_amount`** e **`installment_key`**, como na proposta em lote. :::caution Atenção A renegociação em lote só pode ser criada com operações de um mesmo emitente e mesma chave de integração. Há um limite de **50 operações** para cada renegociação em lote. ::: ## Request ENDPOINT /renegotiation/batch_proposal_simulation MÉTODO POST :::warning Atenção Os campos `discount_amount` e `discount_percentage` **NÃO** podem ser enviados juntos no mesmo payload (nível raiz). ::: :::info Nota Na raiz, `discount_amount` e `discount_percentage` são alternativas para desconto global. Os campos **`paid_amount`** e **`discount_amount`** em `operations[].installments[]` são usados com **`present_amount`** por parcela e não substituem a regra da raiz. ::: Request Body ```json { "amortization_type": "present_amount", "reference_date": "2026-04-08", "discount_percentage": 0.0, "operations": [ { "debt_key": "1baea8a0-0fca-4f7c-8857-a227d4da72f8", "installments": [ { "installment_key": "ca5741c7-99a2-42e7-92a1-9328a36e4e88", "paid_amount": 500, "discount_amount": 50 } ] }, { "debt_key": "2cbfb9b1-1fdb-5f8d-9967-b338e5eb83f9", "installments": [ { "installment_key": "2ef25ed8-7124-44f5-9e3d-1d1a7196166e", "paid_amount": 150, "discount_amount": 10 } ] } ] } ``` ### Body Params | Campo | Tipo | Descrição | Caracteres | |---|---|---|---| | `amortization_type`* | string | Tipo de amortização | **[Enumeradores Amortization Type](#enumeradores-amortization-type)** | | `reference_date`* | string | Data de referência para cálculo do valor presente (precisa ser D+1) | 10 | | `discount_percentage` | float | Percentual de desconto sobre o valor presente ((1 - percentual) * Valor Presente) | 10 | | `discount_amount` | float | Valor de desconto aplicado sobre o valor presente | 10 | | `operations`* | array | Lista de operações a serem renegociadas | **[Objeto Operations](#objeto-operations)** | ### Objeto Operations | Campo | Tipo | Descrição | Caracteres | |---|---|---|---| | `debt_key`* | string | Chave única da operação de crédito (DEBT-KEY) | UUID | | `installments`* | array | Parcelas a serem renegociadas | **[Objeto Installments](#objeto-installments)** | ### Objeto Installments | Campo | Tipo | Descrição | Caracteres | |---|---|---|---| | `installment_key`* | string | Chave da parcela a ser renegociada | UUID | | `paid_amount` | float | Valor pago (ou alocado) na parcela, em reais (R$). Obrigatório quando `amortization_type` é **`present_amount`**. | 15,2 | | `discount_amount` | float | Valor de desconto em reais (R$) na parcela. Obrigatório quando `amortization_type` é **`present_amount`** (use `0` se não houver desconto). Opcional nos demais tipos. | 15,2 | ### Enumeradores Amortization Type | Campo | Descrição | |---|---| | **present_amount** | Simulação com valor presente por parcela. Em cada `installments[]` é obrigatório `installment_key`, **`paid_amount`** e **`discount_amount`**. | | **installment_payment** | Renegociação para pagamento de parcelas específicas enviadas no payload. Requer `installment_key` de cada parcela. | | **overdue_installment_payment** | Renegociação direcionada para pagamento de parcelas em atraso. Requer `installment_key` de cada parcela. | ## Response STATUS 200 Response Body ```json { "batch_proposal_key": "7423c701-3578-4733-8f30-81ab60afdb6d", "discount_percentage": 0, "discount_amount": 0, "amortization_type": "present_amount", "payment_amount": 517.88, "requester_name": "Dante Ltda", "requester_key": "78287247-947d-4730-9bd1-7efb068175b6", "issuer_name": "Dante Ferrarini", "reference_date": "2026-04-08", "issuer_document_number": "31057466093", "operations": [ { "requester_key": "78287247-947d-4730-9bd1-7efb068175b6", "contract_number": "DWF1761222116", "payment_amount": 517.88, "discount_amount": 0, "origin_key": null, "affected_installments": [ { "installment_key": "1dea396f-beb1-4df3-9822-35800b4c095a", "due_date": "2026-05-07", "principal_amount": 491.4903841, "interest_amount": 52.3996159, "fine_amount": 0, "total_amount": 543.89, "present_amount": 517.88, "paid_amount": 517.88, "principal_amortization_payment_amount": 491.49, "prefixed_interest_payment_amount": 26.39, "fine_payment_amount": 0, "discount_amount": 0 } ], "remaining_installments": [ { "installment_key": "370e73d1-55d8-431e-9b22-d08fb8297999", "due_date": "2026-06-07", "principal_amount": 516.1296159, "interest_amount": 27.7603841, "fine_amount": 0, "total_amount": 543.89 } ], "debt_key": "72760166-4ddf-41fb-8a8c-605f8f4fc35c" } ] } ``` ### Campos de Desconto Desconto percentual ```json { "discount_percentage": 0.5 } ``` Desconto absoluto ```json { "discount_amount": 200 } ``` --- # Webhooks - Renegociação em Lote Crédito Clean URL: /en/documentation/manual_credito_clean/renegociacao/webhooks ## Resumo Após a criação de uma proposta de renegociação, o sistema enviará webhooks para notificar sobre o pagamento ou rejeição da proposta. Esta página cobre tanto as propostas individuais (`renegotiation.proposal`) quanto as propostas em lote (`renegotiation.batch_proposal`). --- ## Webhook de Pagamento — Proposta Individual Enviado quando uma proposta de renegociação individual é paga. WEBHOOK_TYPE renegotiation.proposal STATUS paid Webhook Body ```json { "webhook_type": "renegotiation.proposal", "key": "", "event_datetime": "", "status": "paid", "data": { "paid_method_type": "", "paid_in": { "code_number": "", "ispb": "", "name": "" } } } ``` ### Campos do Webhook de Proposta Individual | Campo | Tipo | Descrição | |---|---|---| | **webhook_type** | string | Tipo do webhook: `renegotiation.proposal` | | **key** | string | Chave da proposta de renegociação (PROPOSAL-KEY) | | **event_datetime** | string | Data e hora do envio do webhook | | **status** | string | Status do evento: `paid` | | **data.paid_method_type** | string | Método de pagamento utilizado | | **data.paid_in.code_number** | string | Código do banco liquidante | | **data.paid_in.ispb** | string | ISPB do banco liquidante | | **data.paid_in.name** | string | Nome do banco liquidante | ### Enumeradores paid_method_type | Enumerador | Descrição | |---|---| | **bank_slip** | Pagamento realizado por boleto | | **pix** | Pagamento realizado por Pix | --- ## Webhooks — Proposta em Lote Após a criação de uma proposta de renegociação em lote, o sistema enviará webhooks para notificar sobre o pagamento ou rejeição da proposta. :::danger Atenção! Os webhooks não devem ser mapeados de forma estrita. Novos campos podem ser adicionados ao payload sem aviso prévio. ::: ## Webhook de Pagamento Este webhook é enviado quando o pagamento da proposta de renegociação em lote é confirmado. WEBHOOK_TYPE renegotiation.batch_proposal STATUS paid Webhook Body ```json { "webhook_type": "renegotiation.batch_proposal", "key": "", "event_datetime": "", "status": "paid", "data": { "paid_method_type": "", "paid_in": { "code_number": "", "ispb": "", "name": "" } } } ``` ### Campos do Webhook de Pagamento | Campo | Tipo | Descrição | |---|---|---| | **webhook_type** | string | Tipo do webhook: `renegotiation.batch_proposal` | | **key** | string | Chave da proposta de renegociação em lote (BATCH-PROPOSAL-KEY) | | **event_datetime** | string | Data e hora do envio do webhook | | **status** | string | Status do evento: `paid` | | **data.paid_method_type** | string | Método de pagamento utilizado | | **data.paid_in.code_number** | string | Código do banco liquidante | | **data.paid_in.ispb** | string | ISPB do banco liquidante | | **data.paid_in.name** | string | Nome do banco liquidante | ### Enumeradores paid_method_type | Enumerador | Descrição | |---|---| | **bank_slip** | Pagamento realizado por boleto | | **pix** | Pagamento realizado por Pix | --- ## Webhook de Rejeição Uma renegociação em lote pode ser rejeitada pelo decurso de prazo do pagamento ou por um pagamento de parcela por fora da renegociação. WEBHOOK_TYPE renegotiation.batch_proposal STATUS rejected Webhook Body ```json { "webhook_type": "renegotiation.batch_proposal", "key": "", "event_datetime": "", "status": "rejected", "data": {} } ``` :::caution Atenção Uma renegociação em lote pode ser rejeitada por: - **Decurso de prazo**: o pagamento não foi realizado dentro da data de vencimento (`proposal_due_date`) - **Pagamento externo**: uma parcela incluída na renegociação foi paga por fora antes da confirmação do pagamento do lote ::: --- ## Dados de Pagamento na Parcela Quando uma parcela é paga através de uma renegociação em lote, os dados de pagamento são registrados na parcela: Payment Data ```json { "batch_renegotiation_proposal_key": "f9addba2-ec91-41bf-a150-c59eb1c3fbef", "paid_in": { "ispb": "18236120", "name": "NU PAGAMENTOS - IP", "code_number": 260 }, "resource_account_key": "ea44b9f2-ad00-4896-b8a3-b1a3da28a72f" } ``` ### Campos dos Dados de Pagamento | Campo | Tipo | Descrição | |---|---|---| | **batch_renegotiation_proposal_key** | string | Chave da proposta de renegociação em lote que originou o pagamento | | **paid_in.ispb** | string | ISPB do banco utilizado para o pagamento | | **paid_in.name** | string | Nome do banco utilizado para o pagamento | | **paid_in.code_number** | integer | Código do banco utilizado para o pagamento | | **resource_account_key** | string | Chave da conta de recursos que recebeu o pagamento | --- # Scripts de Integração - Crédito Clean URL: /en/documentation/manual_credito_clean/scripts_integracao ## Resumo Disponibilizamos scripts Python prontos para uso que demonstram o fluxo completo de integração Crédito Clean com a API Sandbox da QI Tech. Cada script corresponde a uma chamada de API testada e validada. **Todos os payloads e respostas exibidos nesta documentação refletem as respostas reais da API Sandbox, obtidas através destes scripts.** ## Download Os scripts estão disponíveis no repositório do projeto: 📦 Baixar pacote Python completo ## Pre-requisitos - Python 3.8+ - Dependencias: `requests`, `python-jose`, `python-dotenv` - Arquivo `_local.env` com suas credenciais Sandbox: - `API_KEY` - Sua chave de API - `QI_PUBLIC_KEY` - Chave publica da QI Tech - `CLIENT_PRIVATE_KEY` - Sua chave privada EC (PEM) ## Scripts Disponiveis ### Emissao | # | Script | Endpoint | Metodo | Descricao | |---|--------|----------|--------|-----------| | 01 | `01_issuance_simulation.py` | `/v2/credit_operation/simulation` | POST | Simular uma operacao de credito antes da emissao | | 02 | `02_issuance_issuance.py` | `/signed_debt` | POST | Emitir a divida com assinatura de contrato via opt-in | | 03 | `03_issuance_query.py` | `/v2/credit_operation/requester_identifier_key/{key}` | GET | Consultar a operacao emitida | ### Estorno | # | Script | Endpoint | Metodo | Descricao | |---|--------|----------|--------|-----------| | 04 | `04_reversal_cancel_before_disbursement.py` | `/debt/{debt_key}/cancel` | PATCH | Cancelar operacao antes do desembolso | | 05 | `05_reversal_cancel_after_disbursement.py` | `/debt/reversal` | POST | Estornar operacao apos desembolso (gera Pix de devolucao) | ### Renegociacao | # | Script | Endpoint | Metodo | Descricao | |---|--------|----------|--------|-----------| | 06 | `06_renegotiation_simulation.py` | `/renegotiation/batch_proposal_simulation` | POST | Simular renegociacao em lote | | 07 | `07_renegotiation_proposal.py` | `/renegotiation/batch_proposal` | POST | Criar proposta de renegociacao em lote | | 08 | `08_renegotiation_query.py` | `/renegotiation/batch_proposal/{key}` | GET | Consultar proposta por chave | | 09 | `09_renegotiation_list.py` | `/renegotiation/batch_proposal` | GET | Listar todas as propostas | | 10 | `10_renegotiation_cancel.py` | `/renegotiation/batch_proposal/{key}` | DELETE | Cancelar proposta pendente | ### Refinanciamento | # | Script | Endpoint | Metodo | Descricao | |---|--------|----------|--------|-----------| | 11 | `11_refinancing_present_value.py` | `/debt` | GET | Consultar valor presente para calculo de refinanciamento | | 12 | `12_refinancing_simulation.py` | `/debt_simulation` | POST | Simular operacao de refinanciamento | | 13 | `13_refinancing_issuance.py` | `/signed_debt` | POST | Criar refinanciamento (emite nova divida, liquida a anterior) | ## Como Usar 1. Baixe os scripts do repositorio 2. Crie um arquivo `_local.env` com suas credenciais Sandbox 3. Execute os scripts em ordem numerica 4. Atualize as chaves (`DEBT_KEY`, `BATCH_PROPOSAL_KEY`, etc.) entre os scripts conforme necessario :::info Sobre os exemplos da documentacao Cada script inclui a resposta real da API como bloco de comentario no final do arquivo. Esses exemplos sao a fonte de verdade para os payloads exibidos nas paginas desta documentacao. ::: --- # Manual QI Sign URL: /en/documentation/manual_qi_sign/ :::danger Attention! QI Tech webhooks should not be mapped strictly. Additional fields may be included in the webhook payloads returned by our APIs. ::: ## Introduction Welcome to the QiTech Signatures API! This API provides access to the electronic document signature service. ### Problems? If you encounter any issues, please contact our support team (suporte@qitech.com.br), and we will respond as quickly as possible. ### Environments We provide two environments for our clients. The base API URLs are: - Production - `https://api.sign.qitech.com.br/` - Sandbox - `https://api.sandbox.sign.qitech.com.br/` ## HTTPS Only For security reasons, all communication with QI Tech APIs must be conducted via HTTPS. To prevent HTTP calls—whether due to oversight or other reasons—this server only provides port 443 with TLS 1.2 communication. Calls made using other protocols will be automatically denied. ## Authentication > To authenticate a request, use the following code: ```shell # In the shell, you only need to add the appropriate header to each request curl "api_endpoint_here" -H "Authorization: EXAMPLE_API_KEY" ``` > Replace the API key 'EXAMPLE_API_KEY' with your key acquired from our support. We use an API Key to allow access to our API. It has likely already been sent to you via email. If you haven't received your key yet, send an email to suporte@qitech.com.br . Our API expects to receive the API Key in all requests to our server in a header like the one below: `Authorization: EXAMPLE_API_KEY` You must replace EXAMPLE_API_KEY with the API Key received from support. Envelopes are the objects containing documents to be electronically signed. They are created from one or more files and can be sent for signature via email, SMS, or WhatsApp. To create an envelope, you must send a file or a set of files to the API. The envelope will be created, and you will receive a unique identifier for it. ## Creating an Envelope To create an Envelope, make a POST call to the /sign/envelope endpoint with the signer(s) data.. ```bash curl -X POST \ https://api.sign.qitech.com.br/sign/envelope \ -H 'Content-Type: application/json' \ -H "Authorization: EXAMPLE_API_KEY" \ -d '{ "id": "814e7ed3-4080-4cae-a853-8e12812817ea", "subject": "CCB QiTech", "expiration_date": "2023-09-20", "signers": [ { "id": "1", "name": "John Sample", "email": "johnsample@test.com", "birthdate": "1992-09-15", "document_number": "111.111.111-11", "phone": { "international_dial_code": "55", "area_code": "11", "number": "988878722" }, "document_submission_method": "email", "authentication_submission_method": "sms" } ] }' ``` ## Envelope Object Definition All information exchanges for an envelope use the following definition for this object. In some cases, to facilitate implementation and reduce data flow between parties, some information may be omitted. | Name | Type | Description | | --------------- | ------ | ---------------------------------------------------------------------------------- | | id | string | Unique identifier for the envelope.
**It is essential that this number is unique** | | subject | string | Envelope title. Appears in the email subject. | | expiration_date | string | Envelope expiration date in `YYYY-MM-DD` format. | | signers | list | List of Signer-type objects describing the envelope's signers. | ### Signer Object Definition | Name | Type | Description | | :------------------------------: | :----: | ------------------------------------------------------------------------------------------------------------------ | | id | string | Signer transaction identifier.
**It is essential that this number is unique per envelope** | | email | string | Signer's email address. | | name | string | Signer's full name. | | birthdate | string | Signer's birthdate in `YYYY-MM-DD` format. | | document_number | string | Signer's document number. | | phone | object | Object describing the signer's phone.. | | phone.international_dial_code | string | Country code for the signer's phone. | | phone.area_code | string | Area code for the signer's phone. | | phone.number | string | Signer's phone number. | | document_submission_method | enum | Method for sending documents for signature.
Available methods: **_email, sms e whatsapp _** | | authentication_submission_method | enum | Method for sending the authentication token for signature.
Available methods: **_email, sms e whatsapp _** | - The email and phone fields can be sent together or separately, but at least one must be provided. - All fields are mandatory. ### Envelope Creation Response After successful envelope creation, the response will be a JSON containing the envelope's id and status, as shown in the example: > Example response ```json { "id": "814e7ed3-4080-4cae-a853-8e12812817ea", "status": "created" } ``` ## Adding Identification Documents to the Signer To add identification documents to a signer, make a `POST` call to the `/sign/envelope/\{envelope_id\}/signer/\{signer_id\}/personal_document` endpoint for each document to be added. The file must be sent in the request body following this format: ```json { "document_b64": "Q5YACgAAAABDlgAbAAAAAEOWAC0AAAAAQ5YAPwAAAABDlgdN...", "template": "cnh_front", "file_type": "jpeg" } ``` ### Available Templates For each type of identification document, the corresponding template must be informed. The available templates are: | Template | Description | | --------- | ------------------------------------------------------------------------ | | cnh_front | Brazilian National Driver's License (CNH) front (photo side). | | cnh_back | Brazilian National Driver's License (CNH) back (signature side). | | rg_front | Brazilian ID Card (RG) front (photo side). | | rg_back | Brazilian ID Card (RG) back (data side). | ### Submission Attribute Description | Attribute | Description | | ------------ | -------------------------------------------------------------------------------------------------- | | document_b64 | Base64 encoded identification document. | | template | Declares the template to be applied for image analysis. | | file_type | Identifies the format of the sent file, `jpeg`. If not sent, `jpeg` is assumed. | - The maximum size for the identification document is 10 MB - All fields are mandatory except for `file_type`. ### Identification Document Addition Response After successfully adding identification documents, the response will be a JSON containing the `created_at` timestamp, as shown in the example: > Example response ```json { "created_at": "2023-01-01T00:00:00.000Z" } ``` ### Identification Document Collection If an identification document is not sent for the signer, it will be requested for collection at the time of signature. ## Adding Documents to the Envelope To add documents for signature to an envelope, make a `POST` call to the `/sign/envelope/\{envelope_id\}/document` endpoint for each document to be added. The file must be sent in the request body following this format: ```json { "id": "3dfc5526-ee47-4b63-ad97-ddaf5b1c9110", "document_b64": "Q5YACgAAAABDlgAbAAAAAEOWAC0AAAAAQ5YAPwAAAABDlgdN...", "name": "Laudo de vistoria de entrada", "document_type": "pdf" } ``` - The maximum document size is 10 MB ### Document Object Definition | Name | Type | Description | | :-----------: | :----: | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | id | string | Document identifier.
**It is essential that this number is unique within the envelope**
**Optional** CIf not provided, we will generate a 36-character UUID4 standard GUID. | | document_b64 | string | Documento codificado em base64. | | Name | string | Document name. | | document_type | enum | Document type.
Available type: **_pdf_** | ### Document Addition Response After successfully adding documents to the envelope, the response will be a JSON containing the document identifier and the creation date, as shown in the example below: > Example response ```json { "id": "3dfc5526-ee47-4b63-ad97-ddaf5b1c9110", "created_at": "2023-01-01T00:00:00.000Z" } ``` ## Sending the Envelope for Signature To send the envelope for signature, make a `PATCH` call to the `/sign/envelope/\{envelope_id\}` endpoint. ```bash curl -X PATCH \ https://api.sign.qitech.com.br/sign/envelope/\{envelope_id\} \ -H "Authorization: EXAMPLE_API_KEY" \ -d '{ "status": "submitted" }' ``` ### Envelope Submission Response After successfully sending the envelope for signature, the response will be a JSON containing the envelope status, as shown in the example below: > Example response ```json { "status": "submitted" } ``` After sending the envelope for signature, signers will receive an email or a message with the link to sign the documents. Upon accessing the link, the signer must fill in their CPF, sign the document, and undergo the facial and/or document validation flow depending on the partner's workflow. After signing, the signer will be redirected to the success page. ## Querying Envelope Data To check envelope data, such as status and signers, make a GET call to the `/sign/envelope/\{envelope_id\}` endpoint. ```bash curl -X GET \ https://api.sign.qitech.com.br/sign/envelope/\{envelope_id\} \ -H "Authorization: EXAMPLE_API_KEY" ``` If the request is successful, the response will be a JSON containing the envelope status and information about the signers, as shown in the example below: > Example response ```json { "id": "814e7ed3-4080-4cae-a853-8e12812817ea", "subject": "Laudo de vistoria de entrada", "expiration_date": "2023-09-20T02:59:59Z", "status": "completed", "signers": [ { "id": "1", "name": "John Sample", "email": "johnsample@test.com", "birthdate": "1992-09-15", "document_number": "111.111.111-11", "phone": { "international_dial_code": "55", "area_code": "11", "number": "988878722" }, "document_submission_method": "email", "authentication_submission_method": "email", "status": "signed", "signed_at": "2023-03-21T15:30:00.000Z", "signature_url": "https://sign.qitech.com.br/s/s2S33dD", "documents": [ { "id": "8d3c3f1a-1a1a-1a1a-1a1a-1a1a1a1a1a1a", "name": "Laudo de vistoria de entrada", "document_type": "pdf" } ] } ] } ``` - The envelope status can be `created`, `submitted`, `completed`, `canceled` ou `expired`. | Enumerators | Description | | :----------: | -------------------------------------------------------------------- | | created | Envelope created | | submitted | Envelope sent for signature | | completed | When all signatures for the envelope have been successfully completed | | canceled | Envelope canceled at the partner's request | | expired | Envelope expired due to signature time limit | | Name | Type | Description | | :-------------: | :------: | ------------------------------------------------------------------------- | | id | string | Unique identifier for the envelope. | | status | string | Envelope status. | | expiration_date | string | Envelope expiration date. | | signers | Signer | List of Signer-type objects describing the envelope's signers. | | documents | Document | List of Document-type objects describing the envelope's documents. | ## Webhook When all signers finish signing and the dossier is generated, a Webhook call will be triggered. To enable this, it is necessary to configure—via the support team (suporte@qitech.com.br)—an endpoint address where we will notify updates, as well as a signature_key that will be used to sign the request. Clients may also—though it is not recommended—use the [polling]( ) technique. In this case, simply do not configure the webhook endpoint and use the registration recovery endpoints to proceed with polling. ## Signature > Example of signature calculation in Python ```python hmac_obj = hmac.new(signature_key.encode('utf-8'), (endpoint + method + payload).encode('utf-8'), hashlib.sha1) return hmac_obj.hexdigest() ``` To ensure that the request received at the webhook endpoint originates from our servers, an HMAC signature is sent in the Signature Header, similar to the authentication process. After calculating the expected signature value on the server side, you must compare the calculated signature with the sent one. If the signatures match, it means the request originated from our servers and is trustworthy. Example webhook call: ```json { "id": "479f8e5a-75e1-4a33-9d75-e0083e3c8e9c", "status": "completed", "webhook_type": "envelope_completed", "signers": [ { "id": "c15392dd-7859-4eae-a2b6-bf0f760a6d9b", "biometry": { "face_validation_available": true, "fraud_base_flag": false, "face_validation_score": 90 }, "liveness": { "result": "live" }, "document": { "face_match_score": 85 } } ] } ``` | Name | Type | Description | | :---------------------------------------: | :-----: | -------------------------------------------------------------------------------- | | id | string | Unique identifier for the envelope. | | status | string | Envelope status. | | signer.id | string | Unique identifier for the signer. | | signer.biometry.face_validation_available | boolean | Indicates if the face was found and validated. | | signer.biometry.fraud_base_flag | boolean | Indicates if the signer's face was found in the fraud database. | | signer.biometry.face_validation_score | integer | Indicates the facial validation score. | | signer.liveness.result | string | Indicates the result of the liveness validation. Possible values: `live` or `spoof` | | signer.document.face_match_score | integer | Indicates the face match validation score. | ## Downloading Signed Dossiers If all signers have signed all documents in the envelope, the envelope status will be `completed`, and a dossier for each document, with signatures and signer data, will be available for download. To do this, make a `GET` call to the `/sign/envelope/\{envelope_id\}/report` endpoint. ```bash curl -X GET \ https://api.sign.qitech.com.br/sign/envelope/\{envelope_id\}/report \ -H "Authorization: EXAMPLE_API_KEY" ``` If the request is successful, the response will be a JSON containing the envelope id and status, plus a list with the document id and the generated dossier URL, as shown in the example below: > Example response ```json { "id": "479f8e5a-75e1-4a33-9d75-e0083e3c8e9c", "status": "available", "documents_reports": [ { "id": "a50ef632-842e-4622-8075-684b8c83a99e", "url": "https://qisign-dossiers.com/06abda52-5bd1-46a1-8fa2-f616ba44b395.pdf" } ] } ``` - The report link for each document will be valid for 24 hours. - The status of reports for the envelope can be `available` or `unavailable`. - The property `documents_reports` contains the list of envelope documents, identified by document id and their report link. ## Downloading Dossier by Signed Document If all signers have signed all documents in the envelope, the envelope status will be `completed` and a dossier for each signed document, with signatures and signer data, will be available for download. To do this, make a `GET` to the endpoint `/sign/envelope/\{envelope_id\}/document/{document_id}/report` ```bash curl -X GET \ https://api.sign.qitech.com.br/sign/envelope/\{envelope_id\}/document/{document_id}/report \ -H "Authorization: EXAMPLE_API_KEY" ``` If the request is successful, the response will be a JSON containing the id, status, url, and the base64 of the document dossier, as shown in the example below: > Example response ```json { "id": "5b930d3d-3713-4c42-85d5-f8e9e44e30ce", "status": "available", "document_report_url": "https://qisign-dossiers.com/7bcf5868-784a-4356-85fb-dd72fd53cd4a.pdf", "document_report": "vAsXDdsaGUsdIMIGxhIG1GU=..." } ``` - The link for the document report will be valid for 24 hours. - The status for the document report can be `available` or `unavailable`. - The property `document_report` is the document report in PDF format encoded in base64. ## Downloading Signer Face Photos It is possible to retrieve images of the signers' faces. To do this, simply make a `GET` call to the endpoint `/sign/envelope/\{envelope_id\}/signer/\{signer_id\}/face` ```bash curl -X GET \ https://api.sign.qitech.com.br/sign/envelope/\{envelope_id\}/signer/\{signer_id\}/face \ -H "Authorization: EXAMPLE_API_KEY" ``` If the request is successful, the response will be a JSON containing the base64 encoded image, as shown in the example below: > Example response ```json { "face_image_url": "https://qisign-face-image.com/4fd09dab-6f3e-4ff5-bfed-6f7debfcde71.jpeg" } ``` ## Canceling an Envelope To cancel an envelope, make a `PATCH` call to the endpoint `/sign/envelope/\{envelope_id\}` ```bash curl -X PATCH \ https://api.sign.qitech.com.br/sign/envelope/\{envelope_id\} \ -H "Authorization: EXAMPLE_API_KEY" \ -d '{ "status": "canceled" }' ``` If the request is successful, the response will be a JSON containing the envelope status, as shown in the example below: > Example response ```json { "status": "canceled" } ``` ## Downloading Signer Document Photos It is possible to retrieve images of the signers' documents. To do this, simply make a `GET` call to the endpoint `/sign/envelope/\{envelope_id\}/signer/\{signer_id\}/personal_document` ```bash curl -X GET \ https://api.sign.qitech.com.br/sign/envelope/\{envelope_id\}/signer/\{signer_id\}/personal_document \ -H "Authorization: EXAMPLE_API_KEY" ``` If the request is successful, the response will be a JSON containing the base64 encoded image, as shown in the example below: > Example response ```json { "document_front_url": "https://qisign-personal-documents.com/bee17d70-b029-41e2-b76b-86f64a8f9213.jpeg", "document_back_url": "https://qisign-personal-documents.com/faf38378-daa2-47b2-9d87-0bbc1f7c744c.jpeg" } ``` ## Checking Signer Status To check a signer's status, make a GET call to the endpoint `/sign/envelope/\{envelope_id\}/signer/\{signer_id\}` ```bash curl -X GET \ https://api.sign.qitech.com.br/sign/envelope/\{envelope_id\}/signer/\{signer_id\} \ -H "Authorization: EXAMPLE_API_KEY" ``` If the request is successful, the response will be a JSON containing the signer's status, as shown in the example below: > Example response ```json { "name": "John Sample", "email": "johnsample@test.com", "status": "signed", "signed_at": "2023-03-21T15:30:00.000Z" } ``` | Name | Type | Description | | :-------: | :----: | ----------------------------------------------------------------------- | | name | string | Signer's name. | | email | string | Signer's email. | | status | string | Signer's signature status. | | signed_at | string | Date and time of the last signature in `YYYY-MM-DDTHH:MM:SS.000Z` format. | ## HTTP Status Codes A API de assinatura utilizam a seguinte padronização nos status HTTP de retorno, de acordo com o RFC 7231 : | Status HTTP | Significado | Descrição | | ----------- | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 400 | Bad Request | The sent request has a formatting error. In most cases, we return an explanation of where the error is in the message body. | | 401 | Unauthorized | There was an issue with authentication; verify if the API Key is correct and in the proper header, as per the Authentication. | | 403 | Forbidden | The accessed endpoint is for internal use and is not available for this API Key. | | 404 | Not Found | The requested data was not found using the provided key. This status is also returned when an invalid endpoint is requested. | | 405 | Method Not Allowed | The HTTP method used does not apply to the used endpoint. | | 406 | Not Acceptable | The data sent in the request body is invalid. Generally, this means the data sent is not valid JSON. | | 409 | Conflict | The request ID corresponds to an ID already processed. This status is returned for duplicate requests sent to the server. | | 500 | Internal Server Error | We encountered an issue processing this request; when this error occurs, our specialists are automatically notified and immediately begin analysis and resolution. | | 503 | Service Unavailable | You have encountered an infrastructure unavailability—planned or unplanned—of our servers. |