# QI Tech — Outros Produtos Documentação da QI Tech em texto corrido, para colar em um LLM. Fonte: https://docs.qitech.com.br 40 página(s). Índice: - Manual de Cessão de Direitos Creditórios (/documentation/iaas/negociacao_recebiveis/manual_api) - Homologation Roadmap - BNPL (/documentation/manual_bnpl_ecommerce/) - Consulta - Emissão BNPL (/documentation/manual_bnpl_full/emissao/consulta) - Emissão BNPL (/documentation/manual_bnpl_full/emissao/) - Simulação - Emissão BNPL (/documentation/manual_bnpl_full/emissao/simulacao) - Webhooks - Emissão BNPL (/documentation/manual_bnpl_full/emissao/webhooks) - Estorno BNPL (/documentation/manual_bnpl_full/estorno/) - Estorno via Amortização — equal_amount e full_settle (/documentation/manual_bnpl_full/estorno/estorno_amortizacao) - Webhooks - Estorno BNPL (/documentation/manual_bnpl_full/estorno/webhooks) - Consulta de Valor Presente - Refinanciamento BNPL (/documentation/manual_bnpl_full/refinanciamento/consulta_valor_presente) - Criação - Refinanciamento BNPL (/documentation/manual_bnpl_full/refinanciamento/criacao) - Introdução - Refinanciamento BNPL (/documentation/manual_bnpl_full/refinanciamento/introducao) - Simulação - Refinanciamento BNPL (/documentation/manual_bnpl_full/refinanciamento/simulacao) - Cenários - Renegociação em Lote BNPL (/documentation/manual_bnpl_full/renegociacao/cenarios) - Consulta - Renegociação em Lote BNPL (/documentation/manual_bnpl_full/renegociacao/consulta) - Renegociação com IOF Spread e Desconto Somente Juros - BNPL (/documentation/manual_bnpl_full/renegociacao/iof-spread-e-desconto-juros) - Proposta de Renegociação em Lote - BNPL (/documentation/manual_bnpl_full/renegociacao/proposta) - Simulação - Renegociação em Lote BNPL (/documentation/manual_bnpl_full/renegociacao/simulacao) - Webhooks - Renegociação em Lote BNPL (/documentation/manual_bnpl_full/renegociacao/webhooks) - Scripts de Integração - BNPL Full (/documentation/manual_bnpl_full/scripts_integracao) - Consulta - Emissão Crédito Clean (/documentation/manual_credito_clean/emissao/consulta) - Consulta de Cessão (/documentation/manual_credito_clean/emissao/consulta_cessao) - Emissão com Assinatura Posterior (/documentation/manual_credito_clean/emissao/emissao_dois_passos) - Emissão com Assinatura Imediata (/signed_debt) (/documentation/manual_credito_clean/emissao/emissao_signed_debt) - Simulação - Emissão Crédito Clean (/documentation/manual_credito_clean/emissao/simulacao) - Webhooks - Emissão Crédito Clean (/documentation/manual_credito_clean/emissao/webhooks) - Estorno Crédito Clean (/documentation/manual_credito_clean/estorno/) - Webhooks - Estorno Crédito Clean (/documentation/manual_credito_clean/estorno/webhooks) - Notificações - Crédito Clean (/documentation/manual_credito_clean/notificacoes) - Consulta de Valor Presente - Refinanciamento Crédito Clean (/documentation/manual_credito_clean/refinanciamento/consulta_valor_presente) - Criação - Refinanciamento Crédito Clean (/documentation/manual_credito_clean/refinanciamento/criacao) - Introdução - Refinanciamento Crédito Clean (/documentation/manual_credito_clean/refinanciamento/introducao) - Simulação - Refinanciamento Crédito Clean (/documentation/manual_credito_clean/refinanciamento/simulacao) - Cenários - Renegociação em Lote Crédito Clean (/documentation/manual_credito_clean/renegociacao/cenarios) - Consulta - Renegociação em Lote Crédito Clean (/documentation/manual_credito_clean/renegociacao/consulta) - Proposta de Renegociação em Lote - Crédito Clean (/documentation/manual_credito_clean/renegociacao/proposta) - Simulação - Renegociação em Lote Crédito Clean (/documentation/manual_credito_clean/renegociacao/simulacao) - Webhooks - Renegociação em Lote Crédito Clean (/documentation/manual_credito_clean/renegociacao/webhooks) - Scripts de Integração - Crédito Clean (/documentation/manual_credito_clean/scripts_integracao) - Manual QI Sign (/documentation/manual_qi_sign/) --- # Manual de Cessão de Direitos Creditórios URL: /documentation/iaas/negociacao_recebiveis/manual_api Esse manual descreve o passo a passo envolvido na Cessão de Direitos Creditórios aos Fundos administrados pela QI CTVM. Além disso, é explicados as regras de negócio do produto e quais os principais pontos de atenção que o parceiro integrador deve ter para se ter uma integração mais rápida e eficiente. ## Pré Requisitos 1. Um Contrato de Cessão ter sido constituído e o Produto respectivo ter sido ativado (Vide APIs de **[Homologação de Cedente](/documentation/iaas/homologacao_cedente/contrato_de_cessao/pedido_de_contrato)**); 2. Somente o Gestor do Fundo, o Cedente parte do Contrato e Originadores vinculados que podem acessar esse serviço. 3. Ter armazenado a chave única de identificação do Fundo Cessionário ( fund_class_key ), e a chave única de identificação da Configuração de Cessão ( assignment_configuration_key ). ```python BASE_URL = "/fund_class/{fund_class_key}/assignment_configuration/{assignment_configuration_key}" ``` :::info A _**BASE_URL**_ será o caminho utilizado em todos os endpoints desta API. ::: ## Fluxo de Estados A esteira de Cessão possui duas entidades principais onde as suas máquinas de estados possuem relações. De um lado temos o Lote, denominado assignment e de outro temos os Ativos, que chamamos de asset . Para o primeiro temos o seguinte fluxo: ![Fluxo de estados do Lote (assignment)](/img/diagrams/iaas-negociacao-recebiveis-manual-api-1.svg) Para o Ativo, temos o seguinte: ![Fluxo de estados do Ativo (asset)](/img/diagrams/iaas-negociacao-recebiveis-manual-api-2.svg) ## Resumo da Integração Em suma, para chegarmos no Encarteiramento dos Ativos, temos o seguinte passo a passo: 1. Criação do Lote; 2. Inserção dos Ativos; 3. Encerrar inserção de Ativos; 4. Webhook de Elegibilidade dos Ativos; 6. Envio da Documentação ; 7. Webhook de Elegiblidade do Lote; 8. Aprovação do Gestor; 9. Assinatura do Termo de Cessão; 10. Pagamento da Cessão; 11. Encarteiramento dos Ativos; ## 1 - Criação do Lote; Para a **[criação do Lote](/documentation/iaas/negociacao_recebiveis/assignment/criacao)** é exigido apenas um identificador único, gerado no sistema do parceiro integrador. Esse será o identificador utilizado tanto nas devoluções de Webhooks quanto nas rotas para as outras funcionalidades, que serão explicadas abaixo. É de suma importância que esse identificador seja único, e o sistema da QI CTVM não permitirá que o parceiro mande duas vezes o mesmo Lote. ## 2 - Inserção dos Ativos; A inserção de Ativos é o processo mais delicado de toda a integração. Nessa seção iremos explicar quais as regras de negócio envolvidas na criação dos Ativos, sejam aquelas que independem do tipo, ou aquelas que são específicas para um determinado tipo. É muito importante para o entendimento dessa API, entender o conceito do Valor do Ativo e do Valor de Compra do Ativo. Para isso vamos utilizar a seguinte notação: **[A]** como Valor de Compra do Ativo, fornecido no raiz do objeto, e significa o quanto o Fundo deve pagar por esse Ativo. **[B]** como a soma total do Ágios da operação. Pode ser obtido através da soma de todos os total_values dos premiums fornecidos. **[C]** como a soma total do Deságios da operação. Pode ser obtido através da soma de todos os total_values das deductions fornecidas. **[D]** como o Valor do Ativo, que pode ser inferido através da seguinte fórmula. :::tip Relação [D] = [A] - [B] + [C] ::: ### 2.1 - Regras Independentes de Tipo de Ativo #### 2.1.1 - Compatibilidade de Tipo de Ativo com Configuração de Cessão; Toda Configuração de Cessão é única por tipo de ativo. Nunca será possível colocar num mesmo lote CCBs e e Duplicatas por exemplo. O produto ativado que gerou a assignment_configuration_key contém um tipo de ativo especifico, e esse será o único tipo aceito em uma dada Configuração. Caso isso seja violado retornaremos o seguinte erro: Response Body STATUS 400 ```json title='Response Body' { "code": "TRC000025" } ``` #### 2.1.2 - Inserção em Lotes Finalizados; Caso tente-se inserir um ativo em lotes que já foram fechados, o parceiro integrador receberá o seguinte erro: Response Body STATUS 400 ```json title='Response Body' { "code": "TRC000022" } ``` #### 2.1.3 - Validação de Código Postal; O código postal do objeto de endereço do tomador da operação deve ser válido. Portanto caso algum inexistente seja fornecido, a requisição não será aceita e devolverá o seguinte erro: Response Body STATUS 404 ```json title='Response Body' { "code": "TRC000070" } ``` #### 2.1.4 - Unicidade de External ID; Um mesmo ativo não pode ser cedido 2 vezes pelo parceiro. Portanto caso esse ativo já exista em nossa base e não tenha sido descartado, o seguinte erro será levantado: Response Body STATUS 409 ```json title='Response Body' { "code": "TRC000054" } ``` ### 2.2 - Regras para Operações de Crédito As Operações de Crédito são aquele ativos que derivam de um compromisso firmado por um Sacado, que toma dinheiro a uma determinada taxa, e honra um compromisso de pagamento de acordo com um determinado fluxo. Portanto esses ativos sempre possuem um principal em aberto, e uma taxa de juros que aumenta esse valor. A estrutura de dados exigida na Criação de uma Operação de Crédito encontra **[nesta página](/documentation/iaas/negociacao_recebiveis/asset/criacao_co)**. #### 2.2.1 - Divergência Valor do Ativo vs Principal em Aberto; Para uma Operação de Crédito é necessário que o Valor do Ativo seja sempre maior ou igual ao Principal em Aberto (Campo principal_value do Objeto de Operação de Crédito). O erro relacionado a essa regra de negócio é: Response Body STATUS 409 ```json title='Response Body' { "code": "TRC000054" } ``` #### 2.2.2 - Divergência Valor de Emissão vs Principal em Aberto; O valor de Emissão do Contrato deve ser sempre maior ou igual ao principal em Aberto. O erro relacionado a essa regra de negócio é: Response Body STATUS 409 ```json title='Response Body' { "code": "TRC000054" } ``` #### 2.2.3 - Parcelas Sequenciais; Todas as parcelas de uma operação de crédito devem ser ordenadas em ordem crescente de data de vencimento ( maturity_date ) e com os números ( installment_number ) sequenciais. Portanto se o fluxo começa com a parcela número 1, a próxima deve ser a 2, a seguinte a 3, e assim por diante. Os erros relacionados a essas regras são respectivamente: Response Body STATUS 409 ```json title='Response Body' { "code": "TRC000054" } ``` Response Body STATUS 409 ```json title='Response Body' { "code": "TRC000054" } ``` #### 2.2.4 - Objetos pré e pós fixados; De acordo com o tipo de juros ( interest_rate_type ) de uma operação, é preciso fornecer os objetos de pré e/ou pós fixados. Caso o tipo de juros seja pré fixado, é necessário fornecer **apenas** o objeto de pré fixado, enquanto na pós fixada, o objeto de pós fixado é **obrigatório** e o de pré fixado é **opcional**. Por exemplo, se a operação de ## 3 - Encerrar inserção de Ativos; Após todos os ativos do Lote terem sido criados, o parceiro pode comandar o **[encerramento da Inserção de Ativos](/documentation/iaas/negociacao_recebiveis/assignment/fechamento)**. Esse processo é importante para que o sistema da QI CTVM saiba que a partir desse momento, quando todos os ativos tiverem sido devidamente analisados pela Elegibilidade, e com toda a documentação fornecida, pode-se analisar a Elegibilidade do Lote como um todo. :::info Não é necessário esperar o Webhook de todos os Ativos para realizar essa ação. No momento em que não se desejar mais inserir ativos, pode-se executar esse comando. ::: ## 4 - Webhook de Elegibilidade dos Ativos; De acordo com o que os Ativos forem sendo analisados pelas regras de Elegibilidade do Fundo, o sistema devolve os **[Webhooks](/documentation/iaas/negociacao_recebiveis/asset/webhooks)**, 1 a 1. Esses Webhooks serão identificados com o identificador único do ativo, fornecido pelo parceiro no momento de criação. Apenas duas possibilidades podem incorrer dessa análise, a **aprovação** dos ativos, ou a **reprovação**. Caso aconteça o primeiro, o Ativo irá seguir a sua esteira, ficando sujeito a inserção de documentos, caso contrário, ele irá para o Estado de descartado, e não irá seguir para os próximos passos. ## 5 - Envio da Documentação; Com a aprovação de um determinado ativo na Elegibilidade, o parceiro pode seguir com a **[inserção dos documentos](/documentation/iaas/negociacao_recebiveis/asset/documents)** exigidos pelo produto. O envio deve ocorrer com uma requisição para cada documento necessário. O conteúdo será transmitido através de um Base64 do binário, portanto viabilizando que isso seja feito através de JSON, como todo o restante das APIs do nosso sistema. Note que para realizar essa requisição é exigido, além do binário do arquivo, o tipo de documento desse arquivo. O Ativo só seguirá a esteira quando todos os documento exigidos forem enviados. Quando isso acontecer, este irá seguir para o estado de Pré Aprovado ( pre_approved ). :::warning Aviso Os documentos exigidos dependem do tipo de Produto e do Regulamento do Fundo. Isso pode ser obtido recuperando o Produto do Contrato de Cessão, que foi ativado para obtenção da assignment_configuration_key desse respectivo lote. ::: :::info Não é necessário ter comandado o Encerramento da Inserção de Ativos. Caso queira vincular a lógica do Envio de Documentos ao Recebimento do Webhook, é totalmente possível e recomendado. ::: ## 6 - Webhook de Elegiblidade do Lote; Assim que um determinado Lote que ja teve a inserção de ativos encerrada, e todos os seus Ativos tiverem ou descartado ou pré-aprovados, ele irá seguir para uma análise de Elegibilidade do Lote todo. Mesmo que todos os Ativos ali tenha sido aprovados, pode ser que o Lote como um todo cause algum desenquadramento do Fundo. Por isso é necessário um segundo passo na execução da Elegibilidade. De forma similar ao Ativo, podemos ter duas opções de resultado decorrido da Elegibilidade, a aprovação ou a reprovação. O resultado será informado através de um **[Webhook](/documentation/iaas/negociacao_recebiveis/assignment/webhooks)**, mas dessa vez identificado com o external_id do Lote. Caso o Lote seja reprovado, ele será descartado, e o processo finaliza-se. Caso contrário, ele seguirá para uma etapa de análise e aprovação do Gestor. ## 7 - Aprovação do Gestor; A aprovação do Gestor deve ser feita através de uma **[requisição especifica](/documentation/iaas/negociacao_recebiveis/assignment/aprovacao)**, ou através do nosso **[Portal](https://manager-dash.qidtvm.com.br/)**. Caso o Lote seja negado, ele será descartado e o processo finaliza-se. Caso contrário, o sistema providencia a geração do Termo de Cessão e o envia para assinatura, levando o Lote para o Estado pending_assignment_term_signature , e assim ficará ate que todas as partes relacionadas assinem o Documento. ## 8 - Assinatura do Termo de Cessão; Uma vez assinado, enviamos um **[Webhook](/documentation/iaas/negociacao_recebiveis/assignment/webhooks)** avisando que o Termo foi assinado e deve prosseguir para o pagamento, ficando, portanto, em pending_payment ## 9 - Pagamento da Cessão; Nesse momento, o sistema paga o Cedente, o montante total da Cessão, que é a soma de todos os total_purchase_value dos ativos não descartados, na conta que foi informada no momento de ativação do Produto. Uma vez que esse pagamento for confirmado, enviamos um **[Webhook](/documentation/iaas/negociacao_recebiveis/assignment/webhooks)**, e os ativos começam a serem encarteirados. ## 10 - Encarteiramento dos Ativos; Por fim, assim que todos os ativos forem devidamente encarteirados, o Lote se tornará completed , e a partir desse momento o parceiro integrador tem a total certeza de que todos aqueles ativos já se encontram devidamente dentro do estoque do Fundo. --- # Homologation Roadmap - BNPL URL: /documentation/manual_bnpl_ecommerce/ ## Summary This document guides clients through integrating Buy Now Pay Later (BNPL) with the QI Tech platform. It outlines the essential steps and provides answers to common questions. ## 1. Document Inquiry The document inquiry can be performed using the following request: ### Request Body Upload ENDPOINT /document/[document_key]/url METHOD GET Testar no Playground ### Path Params | Field | Description | |--------------- |------------------------------------------| | `document_key` | Unique document key | :::caution Attention The document URL will be generated with an expiration period of 10 minutes. ::: Response Body ```json { "document_key": "8a1e62f3-7add-4240-a51d-e0f1a2f421fa", "document_url": "expirable_url", "signed_document_url": "expirable_url", "expiration_datetime": "2024-05-01T01:00:00.000Z" } ``` ## 2. 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 METHOD POST Testar no Playground Response Body ```json { "document_key": "cfbc8469-89ea-4a80-9f64-ba7b1566c68b", "document_md5": "cd451103fa512frc98ce684d3896698c" } ``` :::caution Atenção Remember to save the **document_key**, as this key is required to query the document. ::: ### API call example Example for uploading an image from a 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" # This key is an example; please use your own key. CLIENT_PRIVATE_KEY = '''' -----BEGIN EC PRIVATE KEY----- MIHbAgEBBEHh1hIeOPE5XNNhn6bxRAmVswsPZ0wZCmzVvP8Tl/LZK9ofVmRVGzll srU1uezJEyHKYdOHrE2p52xUj+pHzjJvb6AHBgUrgQQAI6GBiQOBhgAEAAofUz1J hBSOyGHLsnV9Sz0DSWmhl7U+ljqbfa8PKVFWSV3w16I1v2zME5/UzUhHn1gWsjnv 7/ekcLLAQbvqMPNXAfjIhFXLAPzqbB9iCuVua1v0Vgy52rBemOWrJka/Ws2bnKR8 h1N1OxOYeYr6C2jqMygBLktKMAs+282CEiEb4bIv -----END EC PRIVATE KEY----- ''' # This key is an example; please use your own key. 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): endpointeger= "/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 endpointeger= '/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-----`; // This key is an example; please use your own key. const api_key = '4c268c0a-53ff-429b-92b6-47ef98a6d89a' // This key is an example; please use your own key. 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. ::: ## 3. 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 Testar no 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": 12, "principal_amortization_month_period": 1 } ``` ### Request Body Details | Field | Type | Description | Max. Char. | |---|--- |---|---| | **credit_operation_type*** | string | Type of credit agreement | **[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 | 5 | | **interest_type*** | string | Amortization method | **[Interest Type Enumerator ](#interest-type-enumerator)** | | **issuer_person_type*** | string | Defines whether the issuer is an individual (natural person) or a legal entity (corporation/business) | **[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 | ### Response Debt Simulation 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.62083829, "period_workdays_to_disbursement": 1.1, "calendar_days_to_disbursement": 30, "workdays_to_disbursement": 22, "tax_amount": 3.39671674, "principal_amortization_amount": 1380.77916171 }, { "due_date": "2025-11-24", "amount": 1507.4, "due_principal": 1440.54083829, "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.85916171, "period_workdays_to_disbursement": 2.1, "calendar_days_to_disbursement": 61, "workdays_to_disbursement": 42, "tax_amount": 7.20558527, "principal_amortization_amount": 1440.54083829 } ] } ``` ### 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** | 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** | string | Disbursement date of the operation | - | | **installments** | array | **[Object Installments](#object-installments)** - Installments of the operation | - | | **interest_type** | string | **[Enumerator Interest Type](#enumerator-interest-type)** - Amortization method and interest calculation method | - | | **additional_iof** | float |A fixed-rate tax applied to the transaction principal, independent of the duration of the credit operation | - | | **base_iof** | float | The taxable amount or principal value 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 | **[Object Tax Configuration](#object-tax-configuration)** - Rate iof values | - | | **first_due_date** | string | Due date of the first installment | - | | **prefixed_interest_rate** | object | **[Object Interest Rate](#object-interest-rate)** - Nominal interest rate | - | ## 4. Debt issuance for natural persons 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 Testar no Playground Request Body ```json { "additional_data":{ "contract":{ "contract_number":"TIK11267101100", "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":"-46.63611", "lat":"-23.5475" }, "fingerprint_device":{ "device":"Web", "model":"iPhone 11", "os_version":"iOS 15.2", "browser":"Chrome", "browser_version":"120.0.0.0", "language":"pt-BR", "timezone":"America/Sao_Paulo", "gpu_renderer":"Apple GPU" } } } ] } }, "financial":{ "number_of_installments":2, "credit_operation_type":"ccb", "interest_type":"pre_price_days", "monthly_interest_rate":0.07, "disbursed_amount":200, "fine_configuration":{ "contract_fine_rate":0.02, "monthly_rate":0.15, "interest_base":"calendar_days" }, "interest_grace_period":0, "disbursement_date":"2026-02-06", "first_due_date":"2026-03-06", "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":"Accout Name" } ], "requester_identifier_key":"6b558426-6b6c-4c9e-bfb3-5734fe45a651", "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", "is_pep":false, "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", "document_identification_number":"96969879003", "name":"Alan Mathison Turing" } } ``` ### Request Body Details | Field | Type | Description | Max. Char. | |---|--- |---|---| | **borrower** * | object | Borrower Object - The debtor of the credit operation | **[Borrower Object](#borrower-object)** | | **disbursement_bank_account** * | object | Technical details of the bank account where the operation funds will be deposited. | **[Disbursement Bank Account Object](#disbursement-bank-account-object)** | | **financial** * | object | Contains all financial details and calculation parameters for the operation. | **[ Financial Object](#financial-object)** | | **purchaser_document_number** * | string | Assignee's Tax ID – The buyer of the credit operation (FIDC/Receivables Investment Fund). | 14 | | **additional_data** * | object | Assignee's Tax ID – The buyer of the credit operation (FIDC/Receivables Investment Fund). | **[ Additional Data Object](#additional-data-object)** | ### Borrower Object |Field|Type|Description|Max. Char.| |---|--- |---|---| |name *|string|Full name of the borrower|100| |email|string|Borrower's electronic mail 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 *|enum|The role of the person in the operation. Default: issuer|-| |birth_date *|date|Borrower's date of birth (Format: "YYYY-MM-DD")|10| |mother_name *|string|Borrower's mother's full name|100| |nationality|string|Borrower's nationality|50| |person_type *|string|Person classification|7| |individual_document_number *|string|Borrower's Tax ID (CPF) - numbers only|11| |document_identification *|string|DOCUMENT_KEY of the uploaded identification document (RG or CNH)|36| |document_identification_back|string|DOCUMENT_KEY of the uploaded back side of the identification document|36| ### 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| ### Disbursement Bank Account Object |Field|Type|Description|Max. Char.| |---|--- |---|---| |name|string|Account holder's full name|50| |document_number|string|Account holder's Tax ID (CPF)|11| |bank_code *|string|Financial institution's COMPE code|3| |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| |account_digit *|string|Account check digit (use zero instead of letters)|1| |account_type|enum|Account Type Enumerator - Type of the bank account| **[Account Type Object](#account-type-object)**| ### Additional Data Object |Field|Type|Description|Max. Char.| |---|--- |---|---| |contract_number *|string|The unique identifier or reference number of the contract|12| |signed *|boolean|Indicates if the contract has been successfully signed|5| |signatures *|array|List of digital signature evidence objects (Opt-in)|-| |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| |area_code *|string|Two-digit regional area code (e.g., "11")|2| |number *|string|Subscriber's phone number|9| |country_code *|string|International dialing code (e.g., "055")|3| |ip_address *|string|The IP address used during the signature process|45| |timestamp *|string|Date and time of the signature (DD-MM-YYYY HH:mm:ss)|19| |file_url *|string|Direct link to the signed contract document (PDF)|2048| |file_type *|string|Format of the signature file (e.g., "pdf")|4| |long *|string|Geographic longitude coordinate of the signature location|20| |lat *|string|Geographic latitude coordinate of the signature location|20| |fingerprint_device|string|Unique digital identifier of the device used|-| ### 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": "a6dbf441-31b0-44df-9bb8-593553de2c45", "status": "issued", "event_datetime": "2026-02-10 00:01:20", "data": { "borrower": { "name": "Alan Mathison Turing", "document_number": "96969879003", "related_party_key": "6995ff6e-27c2-47e9-b4bf-640934b56b23" }, "contract": { "document_key": null, "number": "TIK11267101100", "urls": [], "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": "6b558426-6b6c-4c9e-bfb3-5734fe45a651", "iof_charge_method": "financed", "collaterals": [], "contract_fees": [ { "fee_type": "spread", "fee_amount": 0.6 } ], "external_contract_fees": [], "external_contract_fee_amount": 0, "net_external_contract_fee_amount": 0, "contract_fee_amount": 0.6, "issue_amount": 201.49, "assignment_amount": 202.09, "cet": "7,6600%", "annual_cet": "142,5744%", "number_of_installments": 2, "base_iof": 0.73, "additional_iof": 0.76, "total_iof": 1.49, "ipoc_code": "324025020203196969879003TIK11267101100", "prefixed_interest_rate": { "annual_rate": 1.252191589, "created_at": "2026-02-10T00:01:18", "daily_rate": 0.0022578334, "interest_base": "calendar_days", "monthly_rate": 0.07 }, "installments": [ { "accrual_reference_date": null, "additional_costs": [], "advanced_paid_amount": 0, "bank_slip_key": null, "business_due_date": "2026-03-06", "calendar_days": 28, "digitable_line": null, "due_date": "2026-03-06", "due_interest": 0, "due_principal": 201.49, "fine_amount": null, "has_interest": true, "installment_history": [], "installment_key": "5c121fac-20f8-4481-b7b6-d0647a0ce524", "installment_number": 1, "installment_payment": [], "installment_status": "created", "installment_type": "principal", "original_due_principal": 201.49, "original_pre_fixed_amount": 13.13403553, "original_principal_amortization_amount": 97.92596447, "original_total_amount": 111.06, "paid_amount": 0, "paid_at": null, "post_fixed_amount": 0, "pre_fixed_amount": 13.13403553, "principal_amortization_amount": 97.92596447, "qr_code_key": null, "qr_code_url": null, "renegotiation_proposal_key": null, "tax_amount": 0.22483801, "total_accrual_amount": null, "total_amount": 111.06, "total_paid_amount": 0, "workdays": 18 }, { "accrual_reference_date": null, "additional_costs": [], "advanced_paid_amount": 0, "bank_slip_key": null, "business_due_date": "2026-04-06", "calendar_days": 31, "digitable_line": null, "due_date": "2026-04-06", "due_interest": 0, "due_principal": 103.56403553, "fine_amount": null, "has_interest": true, "installment_history": [], "installment_key": "a8a21d7a-481e-43ba-b115-fd89253bcde9", "installment_number": 2, "installment_payment": [], "installment_status": "created", "installment_type": "principal", "original_due_principal": 103.56403553, "original_pre_fixed_amount": 7.49596447, "original_principal_amortization_amount": 103.56403553, "original_total_amount": 111.06, "paid_amount": 0, "paid_at": null, "post_fixed_amount": 0, "pre_fixed_amount": 7.49596447, "principal_amortization_amount": 103.56403553, "qr_code_key": null, "qr_code_url": null, "renegotiation_proposal_key": null, "tax_amount": 0.5010428, "total_accrual_amount": null, "total_amount": 111.06, "total_paid_amount": 0, "workdays": 20 } ], "total_pre_fixed_amount": 20.63 } } ``` ## 5. Webhooks After the successful response, you will receive webhooks for the CCB and for disbursement success or failure. How the CCB and signature are notified depends on whether generation is **synchronous** or **asynchronous**: - **Synchronous CCB generation:** the Signature webhook (`signature_finished`) is sent during this flow, with the signed CCB URL. - **Asynchronous CCB generation:** two debt webhooks may be sent instead: one with status `issued` (full debt data after issuance) and one with status `generated_document` (CCB URL and signed document). **If these asynchronous webhooks are triggered, the Signature finished (`signature_finished`) webhook is not sent.** You will still receive a webhook indicating the disbursement’s success or failure (or cancellation), as described below. ### Signature webhook (synchronous) In synchronous CCB mode generation, the Signature webhook is delivered in this flow. Response Body ```json { "key": "1ebd4a90-2721-4c39-a399-427fa16bca65", "status": "signature_finished", "webhook_type": "debt", "event_datetime": "2025-10-27 17:09:33", "contract_document_key":"9f9ab7e4-3605-4f92-89ca-0d9c2a17fba4", "requester_identifier_key":"7349e218-0646-483b-b75b-3300f7212176", "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" } ``` ### Issued webhook (asynchronous) When CCB generation runs asynchronously, this webhook notifies issuance with the full debt payload (`status`: `issued`). It replaces the synchronous Signature webhook in that flow; see the introduction at the top of this section. Response Body ```json { "key": "1e90d231-e569-49cb-9bf0-3409bb45a43a", "data": { "cet": "33,6800%", "base_iof": 0.19, "borrower": { "name": "teste", "document_number": "68752867005", "related_party_key": "186e58d3-1e82-400c-88b5-fd9c087f80bb" }, "contract": { "urls": [], "number": "MSCT6YJ3MO51", "document_key": null, "signature_information": [ { "signer_name": "teste", "signer_role": "issuer", "signer_email": "teste@gmail.com", "signature_url": null, "signer_external_key": null, "signer_document_number": "06160405390" } ] }, "ipoc_code": "324025020203106160405390MSCT6YJ3MO51", "total_iof": 0.38, "annual_cet": "3.156,5450%", "collaterals": [], "installments": [ { "paid_at": null, "due_date": "2026-05-27", "workdays": 31, "tax_amount": 0.1859022, "fine_amount": null, "paid_amount": 0.0, "qr_code_key": null, "qr_code_url": null, "due_interest": 0.0, "has_interest": true, "total_amount": 76.82, "bank_slip_key": null, "calendar_days": 45, "due_principal": 50.38, "digitable_line": null, "installment_key": "4a940fc6-45d8-43a4-9f62-1b8cf36bf5d9", "additional_costs": [], "installment_type": "principal", "pre_fixed_amount": 26.44, "business_due_date": "2026-05-27", "post_fixed_amount": 0, "total_paid_amount": 0.0, "installment_number": 1, "installment_status": "created", "installment_history": [], "installment_payment": [], "advanced_paid_amount": 0.0, "total_accrual_amount": null, "original_total_amount": 76.82, "accrual_reference_date": null, "original_due_principal": 50.38, "original_pre_fixed_amount": 26.44, "renegotiation_proposal_key": null, "principal_amortization_amount": 50.38, "original_principal_amortization_amount": 50.38 } ], "issue_amount": 50.38, "contract_fees": [ { "fee_type": "spread", "fee_amount": 0.19 }, { "fee_type": "spread_ted_fee", "fee_amount": 1.0 } ], "additional_iof": 0.19, "assignment_amount": 51.57, "iof_charge_method": "financed", "contract_fee_amount": 1.19, "external_contract_fees": [], "number_of_installments": 1, "prefixed_interest_rate": { "created_at": "2026-04-12T21:37:53", "daily_rate": 0.009419836, "annual_rate": 29.6351274611, "monthly_rate": 0.33, "interest_base": "calendar_days_365" }, "total_pre_fixed_amount": 26.44, "requester_identifier_key": "ccdbb93a-89cf-47bc-bd69-87671019d2ae", "external_contract_fee_amount": 0, "net_external_contract_fee_amount": 0 }, "status": "issued", "webhook_type": "debt", "event_datetime": "2026-04-12 21:37:53" } ``` ### Generated document webhook (asynchronous) Sent asynchronously with the CCB document URL and the signed PDF. In the asynchronous flow, use this together with the Issued webhook; the Signature finished webhook is not sent. See the introduction at the top of this section. Response Body ```json { "key": "1e90d231-e569-49cb-9bf0-3409bb45a43a", "data": { "contract": { "urls": [ "https://storage.googleapis.com/live-doc-api/documents/ddc85f4c-7079-44c5-b8cc-1fa630406551-signed.pdf" ] }, "document_key": "ddc85f4c-7079-44c5-b8cc-1fa630406551", "signed_contract_url": "https://storage.googleapis.com/live-doc-api/documents/ddc85f4c-7079-44c5-b8cc-1fa630406551-signed.pdf" }, "status": "generated_document", "webhook_type": "debt", "event_datetime": "2026-04-12 21:38:02" } ``` ### Disbursement webhook Response 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": "24b5deae-304e-4773-9b25-e42dbd450241", }, "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. | ## 6. Cancellation ### Cancel debt before disbursement ### Request Body ENDPOINT /debt/ DEBT-KEY /cancel MÉTODO PATCH Testar no Playground ### Path params | Field | Type | Description | Max. Char. | |---|---| ---| ---| | `debt_key` * | string | Debt unique identifier key returned at the moment of the credit operation creation. | 32 | ### Response Body STATUS 200 Response Body ```json { "data": [ { "borrower": { "document_number": "68394265057", "name": "Xuxa Meneguel" }, "contract_fee_amount": 5.56, "installments": [ { "bank_slip_key": null, "calendar_days": 57, "due_date": "2020-09-30", "due_principal": -0.00217819, "fine_amount": null, "has_interest": true, "installment_key": "28eb5907-ed25-4a86-bb9d-b6dc944f13df", "installment_number": 1, "installment_status": "opened", "installment_type": "principal", "paid_amount": 0, "post_fixed_amount": 0, "pre_fixed_amount": 268.75782181, "principal_amortization_amount": 1111.9, "tax_amount": 0, "total_amount": 1380.66, "workdays": 40 } ], "operation_key": "7986dcc7-4331-478f-af47-adfbdf7f4a36", "status": "opened" } ], "pagination": { "current_page": 1, "next_page": null, "rows_per_page": 100, "total_pages": 1, "total_rows": 55 } } ``` ### Debt cancellation within seven days after disbursement — Via Pix refund Used when the partner requests the borrower to return the funds via Pix. The system generates a copy-paste Pix code for the borrower to complete the refund. Once payment is confirmed, the operation is automatically canceled. :::info When to use Use this endpoint when the reversal must be completed by the **borrower**, who will receive a Pix refund code to pay. ::: ### Request Body ENDPOINT /debt/CREDIT-OPERATION-KEY/reversal MÉTODO POST Testar no Playground Request Body ```json {} ``` --- ### Debt cancellation within seven days after disbursement — Via QI internal account Used when the refund is processed directly through **QI Tech's internal account**, without requiring any action from the borrower. Suitable for the `internal` method, where the amount is debited internally without generating a Pix. :::info When to use Use this endpoint when the reversal is operated by the **partner via QI Tech's internal account**, without involving the borrower in the refund process. ::: ### Request Body ENDPOINT /credit_operation/ CREDIT-OPERATION-KEY /reversal MÉTODO PUT :::info Required Header Send the `SELECTED-AGENT` header with your `requester_key` value. ::: ### Path Params | Field | Type | Description | Max. Char. | |---|---|---|---| | `credit_operation_key`* | string | Credit operation key (DEBT-KEY) | UUID | Request Body (optional) ```json { "cancel_reason": "reversed_manually" } ``` ### Body Params | Field | Type | Description | Max. Char. | |---|---|---|---| | `cancel_reason` | string | Reason for the reversal. If not provided, the system will use the default. | - | ### Response Body STATUS 200 Response Body ```json { "disbursed_issue_amount": 1500, "issue_amount": 2000, "assignment_amount": 1850, "assigned": true, "assigned_at": "2023-10-01T12:00:00", "purchaser_document_number": "12345678000199", "reversal_key": "a353c543-2ac7-437c-ac6a-eb4e8d6ce250" } ``` ## 7. Debt inquiry You can query the debt later to retrieve information or track its current status: ENDPOINT /v2/credit_operation/ CREDIT-OPERATION-KEY METHOD GET Testar no Playground ### Path params | Field | Type | Description | Max. Char. | |---|---|---|---| | `credit_operation_key` * | string | Key of the credit operation | UUID | ### Response STATUS 200 Response Body ```json { "credit_operation_key":"31381158-e138-4aaa-99b7-f78356e71004", "issue_amount":201, "origin_key":"31381158-e138-4aaa-99b7-f78356e71004", "total_iof":1, "assigned_at":null, "disbursement_start_date":"2026-02-23", "disbursement_end_date":"2026-02-23", "issue_date":"2026-02-23", "requester_identifier_key":"12313asdjasdx998", "installments":[ { "business_due_date":"2026-02-24", "due_date":"2026-02-24", "calendar_days":1, "due_interest":0, "due_principal":201, "fine_amount":0, "has_interest":true, "post_fixed_amount":0, "pre_fixed_amount":0.46, "principal_amortization_amount":103.45, "tax_amount":0.01, "total_amount":103.91, "workdays":1, "accrual_reference_date":null, "advanced_paid_amount":0, "bank_slip_key":null, "digitable_line":null, "installment_key":"cfd67eb8-cd1e-438b-8636-44cb94176515", "installment_status":"created", "installment_type":"principal", "original_due_principal":201, "original_pre_fixed_amount":0.46, "original_principal_amortization_amount":103.45, "paid_amount":0, "original_total_amount":103.91, "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":null, "principal_amortization_payment_amount":0, "prefixed_interest_payment_amount":0 }, { "business_due_date":"2026-03-24", "due_date":"2026-03-24", "calendar_days":28, "due_interest":0, "due_principal":97.54761348, "fine_amount":0, "has_interest":true, "post_fixed_amount":0, "pre_fixed_amount":6.36, "principal_amortization_amount":97.55, "tax_amount":0.23, "total_amount":103.91, "workdays":20, "accrual_reference_date":null, "advanced_paid_amount":0, "bank_slip_key":null, "digitable_line":null, "installment_key":"445f1c2d-3967-4b23-9290-e19a0a5fb956", "installment_status":"created", "installment_type":"principal", "original_due_principal":97.55, "original_pre_fixed_amount":6.36, "original_principal_amortization_amount":97.55, "paid_amount":0, "original_total_amount":103.91, "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":null, "principal_amortization_payment_amount":0, "prefixed_interest_payment_amount":0 } ], "first_due_date":"2026-02-24", "requester_key":"3e69b448-9afb-4aef-9c0d-0a3059350d80", "original_total_iof":null, "contract_number":"TIK122710117", "credit_operation_status_enumerator":"issued", "operation_type_enumerator":"structured_operation", "disbursement_date":"2026-02-23", "issuer_name":"Alan Mathison Turing", "issuer_document_number":"46843213049", "external_contract_fees":[ ], "cet":8.23, "annual_cet":158.43, "final_disbursement_amount":200, "number_of_installments":2, "disbursement_issue_amount":200, "prefixed_interest_rate":{ "annual_rate":1.252191589, "daily_rate":0.0022578334, "interest_base":{ "enumerator":"calendar_days", "year_days":360 }, "monthly_rate":0.07 }, "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/3d684e68e7df4e557d0480d98e2692.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/3d684e68e7df4e557d0480d98e2692.jpg", "signature_url":null, "document_type":"document_identification_back", "signature_required":false, "signed":false }, { "document_key":"73584aa0-91d4-483b-a95c-1b0263c14126", "document_url":"https://storage.googleapis.com/sandbox-doc-api/documents/73584aa0-91d4-483b-a95c-1b0263c14126/CASTELLOBNPL-ALAN_MATHISON_TURING-CCB-TIK122710117-202602241151.pdf", "signature_url":"https://storage.googleapis.com/sandbox-doc-api/documents/73584aa0-91d4-483b-a95c-1b0263c14126/CASTELLOBNPL-ALAN_MATHISON_TURING-CCB-TIK122710117-202602241151_signed.pdf", "document_type":"ccb_pre_price_days", "signature_required":true, "signed":true } ], "related_parties":[ { "related_party_key":"fe133e90-9ee6-401a-a5a4-7d415ecb04fd", "role_type":"issuer", "person_type":"natural", "name":"Alan Mathison Turing", "email":"weiwenqian.wayne@bytedance.com", "individual_document_number":"46843213049" } ], "base_iof":0.24, "additional_iof":0.76, "assignment_amount":201.6, "total_prefixed_amount":6.82 } ``` STATUS 400 Response Body ```json { "data": "{\"title\": \"Bad Request\", \"description\": \"Invalid request body.\", \"translation\": \"Corpo da requisição inválido.\", \"extra_fields\": {}, \"code\": \"LEG000069\"}" } ``` You can also query the debt later to retrieve the log of events status: ENDPOINT /v2/credit_operation/ CREDIT-OPERATION-KEY /events METHOD GET CREDIT-OPERATION-KEY /events">Testar no Playground ### Path params | Field | Type | Description | Max. Char. | |---|---|---|---| | `credit_operation_key` * | string | Key of the credit operation | 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 } } ``` STATUS 400 Response Body ```json { "data": "{\"title\": \"Bad Request\", \"description\": \"Invalid request body.\", \"translation\": \"Corpo da requisição inválido.\", \"extra_fields\": {}, \"code\": \"LEG000069\"}" } ``` ## 8. Assignment Inquiry ### Assignment Confirmation Webhook This webhook is triggered to notify the client that the assignment process has been initiated. It provides the essential metadata required to track the assignment. 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" } ``` |Field|Type|Description|Maximum lenght| |---|---|---|---| |assignment_key|string|Unique identifier for the assignment operation|36| |term_of_assignment_url|string| URL to download the Term of Assignment (PDF)|2048| |number_of_items|integer|Total number of credit operations (items) included in this assignment|5| |total_amount|float|The sum of the present value of all items in the assignment|15,2| |reference_date|string|The base date used for the assignment calculations (YYYY-MM-DD)|10| To query a specific assignment, the client can perform a GET request on the endpoint using the assignment identifier key (assignment_key). ### Request Body ENDPOINT /v2/assignment/[assignment_key] METHOD GET Testar no Playground ### Params | Field | Descrição | | ---------------- | ------------------------------ | | `assignment_key` | Assignment unique identifier key | ### 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" } ``` To query the contracts within an assignment, use a GET request on the endpoint with the same **assignment_key**. ### Request Body ENDPOINT /v2/assignment/[ASSIGNMENT_KEY]/assignment_items?page=1&page_size=100 METHOD GET Testar no Playground ### Path Params | Field | Type | Description | |-----------------|---------|----------------| | `assignment_key` | string |Assignment unique identifier key | ### Query Params | Field | Type | Description | |-----------------|---------|----------------| | `page` | string |Number of the page | | `page_size` | string | Length of the page, limited by 100 | The response is a paginated list containing information for each contract in the assignment (status 200): ### Response Body STATUS 200 Response Body ```json { "pagination": { "page": 1, "page_size": 10 } "data": [ { "assignment_date": date, "assignment_item_key": uuid, "contract_number": "TIK000012312", "control_number": "TIK000012312", "requester_identifier_key": uuid, -> including this field "credit_operation_key": string, "disbursed_amount": 80.0, "disbursement_date": date, "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/canceled", "rejected_reasons": [] "assignment_items": [ { "installment_key": uuid, "present_amount": 100, "due_date": date, "your_number": "TIK000012312001" }, { "installment_key": uuid, "present_amount": 80, "due_date": date, "your_number": "TIK000012312002" } ] } ] } ``` Query the assigment batchs by the **assignment_date**. ### Request Body ENDPOINT /v2/assignment/assignments?reference_date=2026-05-15 METHOD GET Testar no Playground ### Query Params | Field | Type | Description | |-----------------------------------|---------|--------------------------------------------------------------------------------| | `reference_date` |string| Date of assignment attempt | ### Response Body 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, } ]} ``` ## 9. Technical Specifications and Enums ### Fees Object | Field | Type | Description | |-----------------|-------|-----------------------------------------------------------------------------------------------------| | **amount** | float | Fee amount (in percentage or absolute value, depending on the value provided in the amount_type field)| - | | **amount_type** | enum | Fee value unit | **[Amount Type Enumerator](#amount-type-enumerator)** | | **fee_amount** | float | Absolute value of the fee charged in the operation | - | | **fee_type** | string | Type of fee charged in the operation | **[Fee Type Enumerator](#fee-type-enumerator)** | | **type** | string | Source of the fee charged in the operation | **[Origin Type Enumerator](#origin-type-enumerator)** | ### Installments Object | Field | Type | Description | |-----------------------------------|---------|--------------------------------------------------------------------------------| | **calendar_days** | integer | Number of calendar days between installments | - | | **due_date** | string | 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** | integer | 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** | integer | Calendar days to disbursement | - | | **workdays** | integer | Business days between installments | - | | **workdays_to_disbursement** | integer | Business days until disbursement | - | ### Interest Rate Object | Field | Description | |-------------------|---------------------------------------------------------------------------------------| | **annual_rate** | Annual fixed/floating interest rate expressed as a decimal | - | | **daily_rate** | Daily fixed/floating interest rate expressed as a decimal | - | | **interest_base** | **[Interest Base Enumerator](#interest-base-enumerator)** - Interest calculation basis | - | | **monthly_rate** | Monthly fixed/floating interest rate expressed as a decimal | - | ### Tax Configuration Object | Field | Description | |-----------------------|---------------------------------------------------------------------------------------| | **base_rate** | Base IOF rate value | - | | **additional_rate** | Additional IOF rate value | - | ### Enumeratores ### Person Type Enumerator | Enumerator | Description | |------------------------|-----------------------| | **legal** | Legal person | | **natural** | Natural person | ### Account Type Enumerator | Enumerator | Description | |------------------------|-----------------------| | **checking_account** | Checking account | ### Amount Type Enumerator | Enumerator | Description | |------------------------|-----------------------| | **absolute** | Absolute value | | **percentage** | Percentage value | ### Interest Type Enumerator | 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 | ### Credit Operation Type Enumerator | Enumerator | Description | |---------------|--------------------------------| | **ccb** | Bank Credit Note | ### Interest Base Enumerator | 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 | ### Fee Type Enumerator Each fee type must be previously enabled and configured by QI Tech | Enumerator | Description | |-----------------------|----------------------------------------------------------------------------| | **spread** | Premium included in the credit operation's acquisition value | | **spread_ted_fee** | Premium on the TED transfer fee | ### Origin Type Enumerator Each fee type must be previously enabled and configured by QI Tech | Enumerator | Description | |-----------------------|----------------------------------------------------------------------------| | **internal** | Internal fee | | **external** | External fee | --- # Consulta - Emissão BNPL URL: /documentation/manual_bnpl_full/emissao/consulta # Consulta - Emissão BNPL ## 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) | --- # Emissão BNPL URL: /documentation/manual_bnpl_full/emissao/ # Emissão BNPL ## Resumo Este endpoint realiza a emissão da dívida e processa a assinatura do contrato via opt-in. O desembolso ocorre automaticamente logo após a emissão. Não é necessário pré-cadastro; basta fornecer os dados do tomador durante a requisição de emissão. ## 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": { "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 } ] } ``` ### Detalhes do Request Body | Campo | Tipo | Descrição | Caracteres | |---|---|---|---| | **borrower*** | object | Objeto do tomador - O devedor da operação de crédito | **[Objeto Borrower](#objeto-borrower)** | | **financial*** | object | Contém todos os detalhes financeiros e parâmetros de cálculo da operação | **[Objeto Financial](#objeto-financial)** | | **simplified** | boolean | Se verdadeiro, utiliza o fluxo simplificado de emissão | - | | **additional_data*** | object | Dados adicionais do contrato, incluindo assinaturas | **[Objeto Additional Data](#objeto-additional-data)** | | **requester_identifier_key** | string | Chave identificadora do solicitante | UUID | | **purchaser_document_number*** | string | CNPJ do cessionário – O comprador da operação de crédito (FIDC) | 14 | | **disbursement_bank_accounts*** | array | Dados técnicos da conta bancária onde os recursos serão depositados | **[Objeto Disbursement Bank Account](#objeto-disbursement-bank-account)** | ### 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 | | attached_documents_list | array | Lista de documentos anexados (ex: selfie) | **[Objeto Attached Documents](#objeto-attached-documents)** | | individual_document_number* | string | CPF do tomador - somente números | 11 | ### Objeto Attached Documents | Campo | Tipo | Descrição | Caracteres | |---|---|---|---| | selfie | string | DOCUMENT_KEY do documento de selfie enviado via upload | UUID | ### 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 | 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)** | | disbursed_amount* | float | Valor a ser desembolsado | 15,2 | | 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 | | number_of_installments* | integer | Número de parcelas | 3 | | principal_grace_period | integer | Período de carência do principal (em meses) | 3 | | monthly_interest_rate* | float | Taxa de juros mensal | 10,6 | ### 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 completo do titular da conta | 50 | | ispb_number | string | Código ISPB da instituição financeira | 8 | | account_digit* | string | Dígito verificador da conta (usar zero no lugar de letras) | 1 | | 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 | | document_number | string | CPF/CNPJ do titular da conta | 14 | | percentage_receivable* | float | Percentual do desembolso para esta conta | 3 | ### Objeto Additional Data | Campo | Tipo | Descrição | Caracteres | |---|---|---|---| | contract* | object | Dados do contrato | **[Objeto Contract](#objeto-contract)** | ### Objeto Contract | Campo | Tipo | Descrição | Caracteres | |---|---|---|---| | contract_number* | string | Número identificador único do contrato | 20 | | signatures* | array | Lista de objetos de evidência de assinatura digital (Opt-in) | **[Objeto Signature](#objeto-signature)** | ### Objeto Signature | Campo | Tipo | Descrição | Caracteres | |---|---|---|---| | signer* | object | Dados de identificação do assinante | **[Objeto Signer](#objeto-signer)** | | signature* | object | Dados de evidência da assinatura digital | **[Objeto Signature Details](#objeto-signature-details)** | ### Objeto Signer | Campo | Tipo | Descrição | Caracteres | |---|---|---|---| | name* | string | Nome completo do assinante | 255 | | document_number* | string | CPF do assinante | 11 | | email | string | E-mail do assinante | 100 | | phone | object | Dados de telefone do assinante | **[Objeto Phone](#objeto-phone)** | ### Objeto Signature Details | Campo | Tipo | Descrição | Caracteres | |---|---|---|---| | ip_address* | string | Endereço IP utilizado na assinatura | 45 | | timestamp* | string | Data e hora da assinatura (ISO 8601: YYYY-MM-DDTHH:mm:ssZ) | 24 | | signature_file* | object | Arquivo da assinatura digital | **[Objeto Signature File](#objeto-signature-file)** | ### Objeto Signature File | Campo | Tipo | Descrição | Caracteres | |---|---|---|---| | file_url* | string | Link direto para o documento do contrato assinado (PDF) | 2048 | | file_type* | string | Formato do arquivo de assinatura (ex: "pdf") | 4 | ## Response A resposta à requisição de emissão retornará o plano de pagamento e uma **DEBT-KEY**, que é o identificador da dívida na 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 Atenção Lembre-se de salvar a **DEBT-KEY** retornada, pois ela será necessária para consultas, renegociações e estornos da operação. ::: ### Detalhes do Response Body | Campo | Tipo | Descrição | |---|---|---| | **webhook_type** | string | Identificador do tipo de evento | | **key** | string | DEBT-KEY — identificador único da dívida na QI SCD (UUID) | | **status** | string | Status atual da dívida | | **event_datetime** | string | Data e hora do evento (ISO 8601) | | **data** | object | **[Objeto Data](#objeto-data)** — Dados da operação | ### Objeto Data | Campo | Tipo | Descrição | |---|---|---| | **borrower** | object | **[Objeto Borrower Response](#objeto-borrower-response)** — Dados do tomador | | **contract** | object | **[Objeto Contract Response](#objeto-contract-response)** — Dados do contrato | | **requester_identifier_key** | string | Chave identificadora do solicitante (UUID) | | **iof_charge_method** | string | Método de cobrança do IOF — sempre "financed" | | **collaterals** | array | Lista de garantias da operação | | **contract_fees** | array | **[Objeto Contract Fees](#objeto-contract-fees)** — Taxas QI Tech cobradas na operação | | **external_contract_fees** | array | **[Objeto External Contract Fees](#objeto-external-contract-fees)** — Taxas externas cobradas na operação | | **external_contract_fee_amount** | float | Valor total das taxas externas | | **net_external_contract_fee_amount** | float | Valor líquido das taxas externas após impostos | | **contract_fee_amount** | float | Valor total das taxas QI Tech | | **issue_amount** | float | Valor nominal da operação de crédito | | **assignment_amount** | float | Valor de cessão da operação de crédito | | **cet** | string | Custo Efetivo Total mensal | | **annual_cet** | string | Custo Efetivo Total anual | | **number_of_installments** | integer | Número de parcelas | | **base_iof** | float | Valor base do IOF | | **additional_iof** | float | Valor adicional do IOF | | **total_iof** | float | Valor total do IOF | | **ipoc_code** | string | Código de registro de crédito brasileiro gerado pela QI Tech | | **prefixed_interest_rate** | object | **[Objeto Interest Rate Response](#objeto-interest-rate-response)** — Taxa de juros nominal | | **installments** | array | **[Objeto Installments Response](#objeto-installments-response)** — Parcelas da operação | | **total_pre_fixed_amount** | float | Valor total dos juros pré-fixados de todas as parcelas | ### Objeto Borrower Response | Campo | Tipo | Descrição | |---|---|---| | **name** | string | Nome completo do tomador | | **document_number** | string | CPF do tomador | | **related_party_key** | string | Identificador único do tomador na QI Tech (UUID) | ### Objeto Contract Response | Campo | Tipo | Descrição | |---|---|---| | **document_key** | string | Chave do documento do contrato | | **number** | string | Número do contrato | | **urls** | array | Lista de URLs do documento do contrato | | **signature_information** | array | **[Objeto Signature Information](#objeto-signature-information)** — Informações de assinatura | ### Objeto Signature Information | Campo | Tipo | Descrição | |---|---|---| | **signer_name** | string | Nome completo do assinante | | **signer_document_number** | string | CPF do assinante | | **signer_role** | string | Papel do assinante na operação | | **signer_email** | string | E-mail do assinante | | **signer_external_key** | string | Chave externa do assinante | | **signature_url** | string | URL do documento assinado | ### Objeto Contract Fees | Campo | Tipo | Descrição | |---|---|---| | **fee_type** | string | Tipo da taxa | | **fee_amount** | float | Valor da taxa | ### Objeto External Contract Fees | Campo | Tipo | Descrição | |---|---|---| | **fee_type** | string | Tipo da taxa externa | | **fee_amount** | float | Valor da taxa externa | | **tax_amount** | float | Valor do imposto sobre a taxa | | **net_fee_amount** | float | Valor líquido da taxa após impostos | ### Objeto Interest Rate Response | Campo | Tipo | Descrição | |---|---|---| | **annual_rate** | float | Taxa de juros anual | | **created_at** | string | Timestamp de criação da taxa (ISO 8601) | | **daily_rate** | float | Taxa de juros diária | | **interest_base** | string | Base de cálculo dos juros | | **monthly_rate** | float | Taxa de juros mensal | ### Objeto Installments Response | Campo | Tipo | Descrição | |---|---|---| | **accrual_reference_date** | string | Data de referência de cálculo da parcela | | **additional_costs** | array | Lista de custos adicionais da parcela | | **advanced_paid_amount** | float | Valor pago antecipadamente | | **bank_slip_key** | string | Chave do boleto bancário | | **business_due_date** | string | Data de vencimento ajustada para o próximo dia útil | | **calendar_days** | integer | Dias corridos entre parcelas | | **digitable_line** | string | Linha digitável do boleto | | **due_date** | string | Data de vencimento da parcela | | **due_interest** | float | Valor de juros remanescente na data de vencimento antes do pagamento | | **due_principal** | float | Saldo devedor no momento da parcela | | **fine_amount** | float | Valor de multa aplicado | | **has_interest** | boolean | Indicador de incidência de juros na parcela | | **installment_history** | array | Histórico de eventos da parcela | | **installment_key** | string | Identificador único da parcela (UUID) | | **installment_number** | integer | Número da parcela | | **installment_payment** | array | Lista de pagamentos realizados na parcela | | **installment_status** | string | Status atual da parcela | | **installment_type** | string | Tipo da parcela — sempre "principal" | | **original_due_principal** | float | Saldo devedor original no momento da emissão | | **original_pre_fixed_amount** | float | Valor original dos juros pré-fixados na emissão | | **original_principal_amortization_amount** | float | Valor original de amortização do principal na emissão | | **original_total_amount** | float | Valor total original da parcela na emissão | | **paid_amount** | float | Valor já pago na parcela | | **paid_at** | string | Data do pagamento | | **post_fixed_amount** | float | Valor dos juros pós-fixados — sempre 0 | | **pre_fixed_amount** | float | Valor atual dos juros pré-fixados | | **principal_amortization_amount** | float | Valor de amortização do principal | | **qr_code_key** | string | Chave do QR Code PIX | | **qr_code_url** | string | URL do QR Code PIX | | **renegotiation_proposal_key** | string | Chave da proposta de renegociação, se aplicável | | **tax_amount** | float | Valor do IOF na parcela | | **total_accrual_amount** | float | Valor total de juros acumulados | | **total_amount** | float | Valor total da parcela | | **total_paid_amount** | float | Valor total pago na parcela até o momento | | **workdays** | integer | Dias úteis entre parcelas | --- # Simulação - Emissão BNPL URL: /documentation/manual_bnpl_full/emissao/simulacao # Simulação - Emissão BNPL ## 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 ```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 } ``` ### 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 | 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 | 10 | | **force_installments_on_workdays*** | boolean | Se verdadeiro, garante que todas as datas de vencimento das parcelas sejam movidas 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 | 3 | | **principal_amortization_month_period*** | integer | Período, em meses, entre as parcelas | 1 | ### 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 BNPL URL: /documentation/manual_bnpl_full/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": "132372de-fead-488f-9fae-b6c2986182be", "data": { "installments": [ { "due_date": "2026-04-27", "total_amount": 89.48, "installment_key": "470c69cd-2a3e-4a17-9003-819e9d37a510", "pre_fixed_amount": 5.60437824, "installment_number": 1, "principal_amortization_amount": 83.87562176 }, { "due_date": "2026-05-26", "total_amount": 89.48, "installment_key": "c190c72d-2ea8-478c-b85b-041c0f402a0c", "pre_fixed_amount": 8.00493898, "installment_number": 2, "principal_amortization_amount": 81.47506102 }, { "due_date": "2026-06-26", "total_amount": 89.48, "installment_key": "07c40e11-400d-4675-8a57-b9bee9e4b21c", "pre_fixed_amount": 6.90959582, "installment_number": 3, "principal_amortization_amount": 82.57040418 }, { "due_date": "2026-07-27", "total_amount": 89.48, "installment_key": "43dfc3ec-99ed-4b86-9105-a126c69ca1ea", "pre_fixed_amount": 5.23461479, "installment_number": 4, "principal_amortization_amount": 84.24538521 }, { "due_date": "2026-08-26", "total_amount": 89.48, "installment_key": "104c9564-488c-44f4-ba50-5c1e87c145a7", "pre_fixed_amount": 3.4109145, "installment_number": 5, "principal_amortization_amount": 86.0690855 }, { "due_date": "2026-09-28", "total_amount": 89.48, "installment_key": "aa073681-d11c-4349-ad4a-64f68538447c", "pre_fixed_amount": 1.89555767, "installment_number": 6, "principal_amortization_amount": 87.58444233 } ], "ted_receipt_list": [ { "fee": 0, "url": "https://storage.googleapis.com/sandbox-doc-api/documents/491e-b208-ddf5addab58d/1043ce73-b366-491e-ddf5addab58d.pdf", "amount": 500.0, "origin": { "name": "QI SOCIEDADE DE CRÉDITO DIRETO S.A.", "type": "payment_account", "branch": "0001", "document": "32402502000135", "bank_code": "329", "account_key": "5d068423-6094-49e4-b15b-7740038295a8", "branch_digit": null, "account_digit": "5", "account_branch": "0001", "account_number": "00002", "financial_institution_name": "QI SOCIEDADE DE CRÉDITO DIRETO S.A." }, "timestamp": "2026-04-10T14:48:35", "description": "00360305 0001 12345-6 12345678000199 - NEXUS TECH SOLUTIONS", "destination": { "name": "NEXUS TECH SOLUTIONS", "type": "checking_account", "branch": "0001", "purpose": "Crédito PIX em Conta", "document": "12345678000199", "bank_ispb": "00360305", "branch_digit": null, "account_digit": "6", "account_number": "12345", "financial_institution_name": "BANCO HORIZONTE S.A." }, "end_to_end_id": "E00360305202604151954bB7qwX9pzKL0", "transaction_key": "2fb21861-b43c-4bbc-85d8-ece2aaf6328e", "origin_transaction_key": "dbd8af8d-c372-4d1b-8d9a-24527286d80a" } ], "requester_identifier_key": "65caad48-976c-44ea-8e34-c8519241981d" }, "status": "disbursed", "webhook_type": "debt", "event_datetime": "2026-04-10 14:48:35" } ``` ### 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 | --- # Estorno BNPL URL: /documentation/manual_bnpl_full/estorno/ # Estorno BNPL ## Resumo O estorno de uma operação BNPL 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. | - | --- # Estorno via Amortização — equal_amount e full_settle URL: /documentation/manual_bnpl_full/estorno/estorno_amortizacao ## Resumo Além dos fluxos de cancelamento antes do desembolso e estorno via Pix nos primeiros 7 dias (ver [Estorno BNPL](./estorno.md)), o BNPL Full oferece **duas modalidades de estorno por amortização**, que executam o retorno dos recursos debitando diretamente uma conta interna do parceiro: - **`equal_amount`** — estorno **parcial**. Distribui o valor informado proporcionalmente entre as parcelas da operação, reduzindo o saldo devedor. A operação continua ativa, com as parcelas restantes em aberto. - **`full_settle`** — estorno **total**. Quita integralmente a operação em uma única transação, calculando o valor presente de todas as parcelas na `reference_date`. Após a liquidação, a operação é marcada como `settled` e não há parcelas remanescentes. Ambas as modalidades utilizam o endpoint `POST /renegotiation/proposal` com `payment_type: "internal"`, o que significa que o valor é movimentado diretamente da conta informada em `account_key`, sem geração de boleto ou Pix. --- ## Quando usar cada modalidade ### `equal_amount` — Estorno Parcial Use quando o tomador deseja **reduzir** o saldo devedor sem encerrar a operação. O valor enviado em `payment_amount` é distribuído entre as parcelas, abatendo principal, juros e eventual multa. As parcelas que ainda não foram totalmente amortizadas continuam em `remaining_installments` para cobrança nos próximos vencimentos. Casos típicos: - Cliente pagou a mais e quer abater apenas parte da dívida. - Retorno parcial de recursos acordado entre parceiro e tomador. - Aplicação de créditos ou devoluções pontuais em operações ativas. ### `full_settle` — Estorno Total Use quando o objetivo é **quitar** a operação por completo. O sistema calcula o valor presente de todas as parcelas abertas na `reference_date` (principal + juros acumulados + eventual multa) e distribui o `payment_amount` até zerar o saldo. A operação passa ao status `settled`. Casos típicos: - Estorno após o prazo de 7 dias do `POST /debt/reversal`. - Quitação antecipada solicitada pelo tomador. - Encerramento administrativo da operação com retorno integral dos recursos. :::info Sequenciamento É possível combinar as duas modalidades. Por exemplo: várias chamadas `equal_amount` para amortizações parciais, seguidas de um `full_settle` final para quitar o saldo remanescente. ::: --- ## Request ENDPOINT /renegotiation/proposal MÉTODO POST Testar no Playground Request Body **equal_amount (parcial)** ```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 | Campo | Tipo | Descrição | Caracteres | |---|---|---|---| | `debt_key`* | string | Chave única da operação de crédito a ser estornada | UUID | | `payment_type`* | string | Deve ser `internal` para estorno via conta interna | 8 | | `amortization_type`* | string | Modalidade do estorno | **[Enumeradores Amortization Type](#enumeradores-amortization-type)** | | `reference_date`* | string | Data de referência para cálculo do valor presente (formato `YYYY-MM-DD`) | 10 | | `payment_amount`* | float | Valor do estorno em reais (R$). Em `equal_amount`, é o valor parcial a ser abatido. Em `full_settle`, deve cobrir o saldo total na `reference_date` | 15,2 | | `account_key`* | string | Chave da conta interna de onde o valor será debitado | UUID | | `request_control_key`* | string | Chave de controle da requisição (idempotência) | UUID | ### Enumeradores Amortization Type | Valor | Descrição | |---|---| | **`equal_amount`** | Estorno parcial. `payment_amount` é distribuído proporcionalmente entre as parcelas; a operação permanece ativa com as parcelas remanescentes em aberto. | | **`full_settle`** | Estorno total. Quita integralmente a operação na `reference_date`. A operação passa a `settled` e não há parcelas remanescentes. | --- ## 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" } ``` ### Detalhes do Response | Campo | Tipo | Descrição | |---|---|---| | `proposal_key` | string | Chave única da proposta de estorno (UUID). Guarde para consultas e webhooks. | | `amortization_type` | string | Modalidade utilizada (`equal_amount` ou `full_settle`). | | `payment_amount` | float | Valor efetivamente aplicado no estorno. | | `proposal_status` | string | Estado da proposta. Inicia em `pending_payment` e transiciona para `paid` após o débito interno. | | `affected_installments` | array | Parcelas que receberam o valor do estorno. Para cada parcela, mostra a composição do `paid_amount` entre principal, juros e multa. | | `remaining_installments` | array | Parcelas que permanecem em aberto após o estorno. Em `full_settle`, vem vazio. | | `payment.payment_data.target_account_key` | string | Conta de destino do débito interno. | | `payment.payment_data.transaction_amount` | float | Valor efetivamente movimentado da `account_key`. | | `devolution_amount` | float | Valor de sobrepagamento devolvido ao fundo. Só é diferente de zero quando já existe um pagamento prévio na operação e o estorno somado a esse pagamento excede o saldo devedor — o excedente é retornado via este campo. | | `request_control_key` | string | Eco da chave de idempotência enviada no request. | --- ## Regras e observações :::caution Atenção - **Estado da operação**: a operação deve estar ativa e desembolsada. Operações ainda não desembolsadas devem ser canceladas via `PATCH /debt/{debt_key}/cancel`. - **`reference_date`**: determina o cálculo de juros e multa. Em `full_settle`, todo o saldo é trazido a valor presente nesta data. **Não pode ser anterior à data de desembolso da operação** — esse é o limite mínimo permitido. - **Parcelas em atraso**: quando há parcelas vencidas, o `paid_amount` da parcela afetada é distribuído entre `principal_amortization_payment_amount`, `prefixed_interest_payment_amount` e `fine_payment_amount`. Verifique o detalhamento no array `affected_installments`. - **Idempotência**: `request_control_key` é obrigatório. Use um UUID único por tentativa para evitar duplicações. - **`full_settle` com valor insuficiente**: se `payment_amount` for menor que o saldo total calculado, o débito ainda é processado e distribuído proporcionalmente — verifique o status final da operação para confirmar a quitação. ::: :::info Combinando modalidades - Várias propostas `equal_amount` podem ser feitas em sequência, cada uma abatendo uma parte do saldo. - Um `full_settle` pode ser feito após uma ou mais propostas `equal_amount` para encerrar o saldo remanescente. - Cada proposta é independente e deve usar um `request_control_key` distinto. ::: --- ## Consultar status da proposta Após criar a proposta, consulte seu status pelo `request_control_key` informado no request. ENDPOINT /renegotiation/proposal/request_control_key/ REQUEST-CONTROL-KEY MÉTODO GET ### Path Params | Campo | Tipo | Descrição | Caracteres | |---|---|---|---| | `request_control_key`* | string | Chave de controle enviada na criação da proposta | UUID | O response segue o mesmo formato do retorno do `POST`. O campo `proposal_status` indica o andamento: | Status | Descrição | |---|---| | `pending_payment` | Proposta criada, aguardando o processamento do débito interno. | | `paid` | Débito processado. Em `full_settle`, a operação já está em `settled`. | --- ## Webhook de Quitação Quando um estorno resulta na quitação integral da operação — tipicamente em `full_settle`, mas também em casos de `equal_amount` cujo somatório zera o saldo devedor — o sistema envia um webhook do tipo `debt` com status `settled`. WEBHOOK_TYPE debt STATUS settled Use este webhook para confirmar, de forma assíncrona, que a operação foi encerrada após o processamento do débito interno. O payload completo e os campos seguem o padrão descrito em [Webhooks - Estorno BNPL](./webhooks.md). --- # Webhooks - Estorno BNPL URL: /documentation/manual_bnpl_full/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 | --- # Consulta de Valor Presente - Refinanciamento BNPL URL: /documentation/manual_bnpl_full/refinanciamento/consulta_valor_presente # Consulta de Valor Presente - Refinanciamento BNPL ## 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 BNPL URL: /documentation/manual_bnpl_full/refinanciamento/criacao # Criação - Refinanciamento BNPL ## 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": { "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 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 BNPL](../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 BNPL URL: /documentation/manual_bnpl_full/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 BNPL URL: /documentation/manual_bnpl_full/refinanciamento/simulacao # Simulação - Refinanciamento BNPL ## 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 BNPL URL: /documentation/manual_bnpl_full/renegociacao/cenarios ## Resumo Este documento apresenta os principais cenários de renegociação em lote para operações BNPL. 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 BNPL 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 BNPL 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 BNPL 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 BNPL 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 BNPL 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 BNPL URL: /documentation/manual_bnpl_full/renegociacao/consulta # Consulta - Renegociação em Lote BNPL ## 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. ::: --- # Renegociação com IOF Spread e Desconto Somente Juros - BNPL URL: /documentation/manual_bnpl_full/renegociacao/iof-spread-e-desconto-juros ## Resumo Esta página documenta o fluxo de renegociação em lote para operações BNPL em que a operação de crédito foi criada com `iof_charge_method: "spread"`. Nesse modelo, o IOF **não** é financiado nas parcelas — ele é calculado normalmente, mas adicionado ao `assignment_amount` (valor de cessão), e não às prestações do tomador. Além disso, é possível utilizar o campo `discount_validation: "only_interest_discount"` em cada operação do array `operations[]` para restringir os descontos aplicados somente à parcela de juros. Se o desconto exceder os juros e atingir o principal ou a multa, a API retornará o erro `InvalidDiscountAmountOnlyInterestDiscount`. O fluxo utiliza os endpoints de lote: simulação (`POST /renegotiation/batch_proposal_simulation`) seguida da proposta (`POST /renegotiation/batch_proposal`). O campo `discount_validation` é definido **por operação** no array `operations[]`, e não no nível raiz do payload. :::info Nota — iof_charge_method O campo `iof_charge_method` é definido no momento da **criação da operação de crédito** (credit-operation-api), e não durante a renegociação. Quando `iof_charge_method: "spread"`: - O IOF é calculado normalmente (IOF base + IOF adicional), mas **não** é deduzido das parcelas do tomador - O IOF é adicionado ao `assignment_amount` — ou seja, o custo do IOF é refletido no valor de cessão - As parcelas do tomador são "limpas" de IOF Os três valores possíveis são: - `"financed"` **(padrão)** — IOF é financiado nas parcelas (deduzido do valor creditado ao tomador) - `"spread"` — IOF é adicionado ao valor de cessão (`assignment_amount`), não às parcelas - `"free"` — Sem IOF (`total_iof = 0`) ::: :::caution Atenção — discount_validation Quando `discount_validation: "only_interest_discount"` é definido em uma operação, o sistema valida que o desconto aplicado em cada parcela **não** inclui amortização de principal (`discount_principal_amortization_amount`) nem multa (`discount_fine_amount`). Somente os juros (juros prefixados) podem ser descontados. Se qualquer parcela tiver um desconto que atinja o principal ou a multa, a API retorna o erro `InvalidDiscountAmountOnlyInterestDiscount` e a requisição inteira falha. ::: ## Passo 1: Simulação em Lote 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). ::: 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 | 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 | | `discount_validation` | string | Regra de validação de desconto. Quando definido como `"only_interest_discount"`, o desconto aplicado não pode ultrapassar a parcela de juros. | **[Enumeradores Discount Validation](#enumeradores-discount-validation)** | | `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 Discount Validation | Campo | Descrição | |---|---| | `only_interest_discount` | Valida que o desconto aplicado em cada parcela não ultrapassa o valor de juros. Caso o desconto atinja o principal ou multa, a API retorna o erro `InvalidDiscountAmountOnlyInterestDiscount`. | ### Enumeradores Amortization Type | Campo | Descrição | |---|---| | **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. | | **present_amount** | Simulação com valor presente por parcela. Em cada `installments[]` é obrigatório `installment_key`, **`paid_amount`** e **`discount_amount`**. | ## 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" } ] } ``` ## Passo 2: Proposta em Lote 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). ::: 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 | Campo | Tipo | Descrição | Caracteres | |---|---|---|---| | `amortization_type`* | string | Tipo de amortização | **[Enumeradores Amortization Type](#enumeradores-amortization-type-1)** | | `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-1)** | ### Objeto Operations | Campo | Tipo | Descrição | Caracteres | |---|---|---|---| | `debt_key`* | string | Chave única da operação de crédito (DEBT-KEY) | UUID | | `discount_validation` | string | Regra de validação de desconto. Quando definido como `"only_interest_discount"`, o desconto aplicado não pode ultrapassar a parcela de juros. | **[Enumeradores Discount Validation](#enumeradores-discount-validation-1)** | | `installments`* | array | Parcelas a serem renegociadas | **[Objeto Installments](#objeto-installments-1)** | ### 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 Discount Validation | Campo | Descrição | |---|---| | `only_interest_discount` | Valida que o desconto aplicado em cada parcela não ultrapassa o valor de juros. Caso o desconto atinja o principal ou multa, a API retorna o erro `InvalidDiscountAmountOnlyInterestDiscount`. | ### Enumeradores Payment Type | Campo | Descrição | |---|---| | `bank_slip` | Pagamento via boleto bancário (gera boleto e Pix) | | `pix` | Pagamento via Pix (gera apenas Pix) | | `manual` | Pagamento feito de forma manual (não gera forma de pagamento) | ### Enumeradores Amortization Type | Campo | Descrição | |---|---| | **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. | | **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`**. | ## 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 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. ::: ## Erro: Desconto Excede Juros Quando `discount_validation: "only_interest_discount"` é definido em uma operação e o valor de desconto aplicado excede a parcela de juros, a API retorna o seguinte erro: Resposta de Erro ```json { "code": "InvalidDiscountAmountOnlyInterestDiscount", "message": "Discount amount must be only interest discount" } ``` A validação é feita **por parcela** durante o processamento da amortização. Se qualquer parcela individual tiver um desconto cujo valor inclua amortização de principal (`discount_principal_amortization_amount > 0`) ou multa (`discount_fine_amount > 0`), a requisição inteira é rejeitada. ## Cessão (Assignment) :::info Nota Após a proposta ser paga, o passo de cessão (`POST /credit_operations/assign`) cria uma transferência formal da operação de crédito. Este é um endpoint separado da **credit-operation-api**. Quando a operação de crédito possui `iof_charge_method: "spread"`, o `assignment_amount` calculado inclui o IOF que **não** foi financiado nas parcelas. Ou seja, o valor de cessão reflete o custo total incluindo o IOF separado. ::: --- # Proposta de Renegociação em Lote - BNPL URL: /documentation/manual_bnpl_full/renegociacao/proposta # Proposta de Renegociação em Lote - BNPL ## Resumo Após simular os valores, é possível criar uma proposta de renegociação em lote para múltiplas operações BNPL. 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 BNPL URL: /documentation/manual_bnpl_full/renegociacao/simulacao # Simulação - Renegociação em Lote BNPL ## Resumo Antes de criar uma proposta de renegociação, é possível simular os valores da renegociação em lote para operações BNPL. 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 BNPL URL: /documentation/manual_bnpl_full/renegociacao/webhooks ## Resumo 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 - BNPL Full URL: /documentation/manual_bnpl_full/scripts_integracao ## Resumo Disponibilizamos scripts Python prontos para uso que demonstram o fluxo completo de integração BNPL Full 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. ::: --- # Consulta - Emissão Crédito Clean URL: /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: /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: /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" } ``` --- # Emissão com Assinatura Imediata (/signed_debt) URL: /documentation/manual_credito_clean/emissao/emissao_signed_debt Este endpoint realiza a emissão da dívida e processa a assinatura do contrato via opt-in em uma única chamada. O desembolso ocorre na data informada no campo `disbursement_date`, que pode ser diferente da data de emissão. Não é necessário pré-cadastro; basta fornecer os dados do tomador durante a requisição de emissão. ## Request ENDPOINT /signed_debt MÉTODO POST Testar no 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 } ] } ``` ### Detalhes do Request Body | Campo | Tipo | Descrição | Caracteres | |---|---|---|---| | **borrower*** | object | Objeto do tomador - O devedor da operação de crédito | **[Objeto Borrower](#objeto-borrower)** | | **financial*** | object | Contém todos os detalhes financeiros e parâmetros de cálculo da operação | **[Objeto Financial](#objeto-financial)** | | **simplified** | boolean | Se verdadeiro, utiliza o fluxo simplificado de emissão | - | | **additional_data*** | object | Dados adicionais do contrato, incluindo assinaturas | **[Objeto Additional Data](#objeto-additional-data)** | | **requester_identifier_key** | string | Chave identificadora do solicitante | UUID | | **purchaser_document_number*** | string | CNPJ do cessionário – O comprador da operação de crédito (FIDC) | 14 | | **disbursement_bank_accounts*** | array | Dados da conta bancária do tomador para recebimento do desembolso | **[Objeto Disbursement Bank Account](#objeto-disbursement-bank-account)** | ### 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 | | attached_documents_list | array | Lista de documentos anexados (ex: selfie) | **[Objeto Attached Documents](#objeto-attached-documents)** | | individual_document_number* | string | CPF do tomador - somente números | 11 | ### Objeto Attached Documents | Campo | Tipo | Descrição | Caracteres | |---|---|---|---| | selfie | string | DOCUMENT_KEY do documento de selfie enviado via upload | UUID | ### 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 por meio das seguintes combinações mutuamente exclusivas (informe **uma e somente uma** das chaves de valor, junto com os demais campos obrigatórios): - **`disbursed_amount` + `monthly_interest_rate` + `number_of_installments`**: informe o valor líquido a ser desembolsado, a taxa de juros e o número de parcelas — o sistema calcula o valor de cada parcela. - **`amount` + `monthly_interest_rate` + `number_of_installments`**: informe o valor bruto (com IOF) da operação — o sistema calcula o desembolso líquido e o valor de cada parcela. - **`final_disbursement_amount` + `monthly_interest_rate` + `number_of_installments`**: informe o valor final que deve chegar ao destinatário e o sistema infla o `issue_amount` para cobrir o IOF. - **`installment_face_value` + `number_of_installments` + (`disbursed_amount` ou `amount`)**: informe o valor desejado por parcela; quando essa combinação é usada **sem** `monthly_interest_rate`, o sistema assume taxa zero. - **`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 | | first_due_date | string | Data de vencimento da primeira parcela (YYYY-MM-DD) | 10 | | limit_days_to_disburse | integer | Quantidade de dias após `disbursement_date` em que o desembolso ainda pode ocorrer | 3 | | fine_configuration* | object | Configuração de multa e mora | **[Objeto Fine Configuration](#objeto-fine-configuration)** | | monthly_interest_rate | float | Taxa de juros mensal. Opcional quando `installment_face_value` é utilizado | 10,6 | | annual_interest_rate | float | Taxa de juros anual (alternativa a `monthly_interest_rate`) | 10,6 | | daily_interest_rate | float | Taxa de juros diária (alternativa a `monthly_interest_rate`) | 10,6 | | disbursed_amount | float | Valor líquido a ser desembolsado | 15,2 | | amount | float | Valor bruto da operação (`issue_amount`) — inclui IOF | 15,2 | | final_disbursement_amount | float | Valor final a chegar no destinatário — sistema infla o `issue_amount` para cobrir IOF | 15,2 | | installment_face_value | float | Valor desejado de cada parcela | 15,2 | | number_of_installments | integer | Número de parcelas | 3 | | desired_installments | array | Array de parcelas com data e valor definidos individualmente | **[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 | - | | total_iof | float | Valor total do IOF — quando omitido, o sistema calcula automaticamente | 15,2 | | 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 completo do titular da conta destino | 100 | | document_number | string | CPF ou CNPJ do titular da conta destino | 11 ou 14 | | transfer_method | string | Método de transferência. Valores: `pix`, `ted` (default: `pix`) | 3 | | pix_transfer_type | string | Subtipo da transferência Pix. Valores: `manual`, `key`, `qrcode` | 6 | | ispb_number | string | Código ISPB da instituição financeira | 8 | | bank_code | string | Código COMPE da instituição financeira (alternativa a `ispb_number`) | 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) | 19 | | account_digit | string | Dígito verificador da conta (usar zero no lugar de letras) | 1 | | account_type | string | Tipo da conta destino. Valores: `checking_account`, `saving_account`, `salary_account`, `payment_account`, `deposit_account`, `guaranteed_account`, `investment_account` | 20 | | pix_key | string | Chave Pix do destinatário — obrigatório quando `pix_transfer_type` = `key` | - | | qr_code_key | string | Chave UUID de um QR Code Pix já registrado — obrigatório quando `pix_transfer_type` = `qrcode` | 36 | | qr_code_url | string | String EMV (copia-e-cola) do QR Code Pix — alternativa a `qr_code_key` | 250 | | digitable_line | string | Linha digitável de boleto bancário — usado para desembolso por boleto | 47-48 | | end_to_end_id | string | Identificador end-to-end do Pix (preenchido na resposta) | 32 | | percentage_receivable | float | Percentual do desembolso destinado a esta conta. Obrigatório quando `amount_receivable` não é informado | 3 | | amount_receivable | float | Valor fixo destinado a esta conta. Obrigatório quando `percentage_receivable` não é informado | 15,2 | :::info Modos de desembolso suportados A combinação de campos depende do `transfer_method` e do `pix_transfer_type`: - **Conta interna QI Tech ou TED**: `bank_code`/`ispb_number` + `branch_number` + `account_number` + `account_digit` + `document_number` + `name` + `percentage_receivable`. - **Pix manual**: `pix_transfer_type` = `manual` + dados de conta (igual ao TED). - **Pix por chave**: `pix_transfer_type` = `key` + `pix_key`. - **Pix por QR Code (registrado)**: `pix_transfer_type` = `qrcode` + `qr_code_key`. - **Pix por QR Code (copia-e-cola)**: `qr_code_url` + `transfer_method` = `pix`. - **Pagamento de boleto**: `digitable_line` + `amount_receivable`. ::: ### Objeto Additional Data | Campo | Tipo | Descrição | Caracteres | |---|---|---|---| | contract* | object | Dados do contrato | **[Objeto Contract](#objeto-contract)** | ### Objeto Contract | Campo | Tipo | Descrição | Caracteres | |---|---|---|---| | contract_number* | string | Número identificador único do contrato | 20 | | signatures* | array | Lista de objetos de evidência de assinatura digital (Opt-in) | **[Objeto Signature](#objeto-signature)** | ### Objeto Signature | Campo | Tipo | Descrição | Caracteres | |---|---|---|---| | signer* | object | Dados de identificação do assinante | **[Objeto Signer](#objeto-signer)** | | signature* | object | Dados de evidência da assinatura digital | **[Objeto Signature Details](#objeto-signature-details)** | ### Objeto Signer | Campo | Tipo | Descrição | Caracteres | |---|---|---|---| | name* | string | Nome completo do assinante | 255 | | document_number* | string | CPF do assinante | 11 | | email | string | E-mail do assinante | 100 | | phone | object | Dados de telefone do assinante | **[Objeto Phone](#objeto-phone)** | ### Objeto Signature Details | Campo | Tipo | Descrição | Caracteres | |---|---|---|---| | ip_address* | string | Endereço IP utilizado na assinatura | 45 | | timestamp* | string | Data e hora da assinatura (ISO 8601: YYYY-MM-DDTHH:mm:ssZ) | 24 | | signature_file* | object | Arquivo da assinatura digital | **[Objeto Signature File](#objeto-signature-file)** | ### Objeto Signature File | Campo | Tipo | Descrição | Caracteres | |---|---|---|---| | file_url* | string | Link direto para o documento do contrato assinado (PDF) | 2048 | | file_type* | string | Formato do arquivo de assinatura (ex: "pdf") | 4 | ## Response A resposta à requisição de emissão retornará o plano de pagamento e uma **DEBT-KEY**, que é o identificador da dívida na 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 Atenção Lembre-se de salvar a **DEBT-KEY** retornada, pois ela será necessária para consultas, renegociações e estornos da operação. ::: ### Detalhes do Response Body | Campo | Tipo | Descrição | |---|---|---| | **webhook_type** | string | Identificador do tipo de evento | | **key** | string | DEBT-KEY — identificador único da dívida na QI SCD (UUID) | | **status** | string | Status atual da dívida | | **event_datetime** | string | Data e hora do evento (ISO 8601) | | **data** | object | **[Objeto Data](#objeto-data)** — Dados da operação | ### Objeto Data | Campo | Tipo | Descrição | |---|---|---| | **borrower** | object | **[Objeto Borrower Response](#objeto-borrower-response)** — Dados do tomador | | **contract** | object | **[Objeto Contract Response](#objeto-contract-response)** — Dados do contrato | | **requester_identifier_key** | string | Chave identificadora do solicitante (UUID) | | **iof_charge_method** | string | Método de cobrança do IOF — sempre "financed" | | **collaterals** | array | Lista de garantias da operação | | **contract_fees** | array | **[Objeto Contract Fees](#objeto-contract-fees)** — Taxas QI Tech cobradas na operação | | **external_contract_fees** | array | **[Objeto External Contract Fees](#objeto-external-contract-fees)** — Taxas externas cobradas na operação | | **external_contract_fee_amount** | float | Valor total das taxas externas | | **net_external_contract_fee_amount** | float | Valor líquido das taxas externas após impostos | | **contract_fee_amount** | float | Valor total das taxas QI Tech | | **issue_amount** | float | Valor nominal da operação de crédito | | **assignment_amount** | float | Valor de cessão da operação de crédito | | **cet** | string | Custo Efetivo Total mensal | | **annual_cet** | string | Custo Efetivo Total anual | | **number_of_installments** | integer | Número de parcelas | | **base_iof** | float | Valor base do IOF | | **additional_iof** | float | Valor adicional do IOF | | **total_iof** | float | Valor total do IOF | | **ipoc_code** | string | Código de registro de crédito brasileiro gerado pela QI Tech | | **prefixed_interest_rate** | object | **[Objeto Interest Rate Response](#objeto-interest-rate-response)** — Taxa de juros nominal | | **installments** | array | **[Objeto Installments Response](#objeto-installments-response)** — Parcelas da operação | | **disbursement_account** | array | **[Objeto Disbursement Account Response](#objeto-disbursement-account-response)** — Dados das contas de desembolso (PIX por chave ou QR Code) | | **total_pre_fixed_amount** | float | Valor total dos juros pré-fixados de todas as parcelas | ### Objeto Disbursement Account Response Retornado apenas quando o desembolso é via **chave PIX** (`pix_key`) ou **QR Code** (`qr_code_key` / `qr_code_url`). Em desembolsos por TED, manual, PIX manual ou boleto, o campo `disbursement_account` **não aparece** na resposta. | Campo | Tipo | Descrição | |---|---|---| | **name** | string | Nome do titular da conta destino (sempre por extenso). | | **document_number** | string | CPF ou CNPJ do titular da conta destino. **CPF (11 dígitos) vem mascarado** como `***XXXXXX**` quando a conta foi resolvida via QR Code; **CNPJ (14 dígitos) vem íntegro**. Em fluxo `pix_key` consultado no DICT, retorna sem máscara. | | **pix_key** | string | Chave PIX do destinatário (input do cliente ou extraída do QR Code decodificado). | | **qr_code_key** | string | UUID do QR Code PIX, quando o desembolso foi por QR registrado. | | **qr_code_url** | string | EMV "copia-e-cola" do QR Code, quando o desembolso foi por QR copia-e-cola. | | **account_branch** | string | Agência da conta destino (preenchida em fluxos `pix_key` consultado no DICT). | | **account_number** | string | Número da conta destino. | | **account_digit** | string | Dígito verificador da conta destino. | | **account_type** | string | Tipo da conta destino. | | **ispb** | string | Código ISPB da instituição financeira destino. | | **percentage_receivable** | float | Percentual do desembolso destinado a esta conta. | | **amount_receivable** | float | Valor fixo destinado a esta conta. | | **end_to_end_id** | string | Identificador end-to-end do PIX, atribuído após o decode/consulta. | :::info Comportamento condicional O campo `disbursement_account` é **estritamente populado** com `name` e `document_number` quando o fluxo é por PIX (chave ou QR Code). Os demais campos seguem o tipo do desembolso: por exemplo, em `qr_code_url` os campos `account_branch`/`account_number`/`account_digit` vêm `null` porque o EMV dinâmico não os carrega. ::: ### Objeto Borrower Response | Campo | Tipo | Descrição | |---|---|---| | **name** | string | Nome completo do tomador | | **document_number** | string | CPF do tomador | | **related_party_key** | string | Identificador único do tomador na QI Tech (UUID) | ### Objeto Contract Response | Campo | Tipo | Descrição | |---|---|---| | **document_key** | string | Chave do documento do contrato | | **number** | string | Número do contrato | | **urls** | array | Lista de URLs do documento do contrato | | **signature_information** | array | **[Objeto Signature Information](#objeto-signature-information)** — Informações de assinatura | ### Objeto Signature Information | Campo | Tipo | Descrição | |---|---|---| | **signer_name** | string | Nome completo do assinante | | **signer_document_number** | string | CPF do assinante | | **signer_role** | string | Papel do assinante na operação | | **signer_email** | string | E-mail do assinante | | **signer_external_key** | string | Chave externa do assinante | | **signature_url** | string | URL do documento assinado | ### Objeto Contract Fees | Campo | Tipo | Descrição | |---|---|---| | **fee_type** | string | Tipo da taxa | | **fee_amount** | float | Valor da taxa | ### Objeto External Contract Fees | Campo | Tipo | Descrição | |---|---|---| | **fee_type** | string | Tipo da taxa externa | | **fee_amount** | float | Valor da taxa externa | | **tax_amount** | float | Valor do imposto sobre a taxa | | **net_fee_amount** | float | Valor líquido da taxa após impostos | ### Objeto Interest Rate Response | Campo | Tipo | Descrição | |---|---|---| | **annual_rate** | float | Taxa de juros anual | | **created_at** | string | Timestamp de criação da taxa (ISO 8601) | | **daily_rate** | float | Taxa de juros diária | | **interest_base** | string | Base de cálculo dos juros | | **monthly_rate** | float | Taxa de juros mensal | ### Objeto Installments Response | Campo | Tipo | Descrição | |---|---|---| | **accrual_reference_date** | string | Data de referência de cálculo da parcela | | **additional_costs** | array | Lista de custos adicionais da parcela | | **advanced_paid_amount** | float | Valor pago antecipadamente | | **bank_slip_key** | string | Chave do boleto bancário | | **business_due_date** | string | Data de vencimento ajustada para o próximo dia útil | | **calendar_days** | integer | Dias corridos entre parcelas | | **digitable_line** | string | Linha digitável do boleto | | **due_date** | string | Data de vencimento da parcela | | **due_interest** | float | Valor de juros remanescente na data de vencimento antes do pagamento | | **due_principal** | float | Saldo devedor no momento da parcela | | **fine_amount** | float | Valor de multa aplicado | | **has_interest** | boolean | Indicador de incidência de juros na parcela | | **installment_history** | array | Histórico de eventos da parcela | | **installment_key** | string | Identificador único da parcela (UUID) | | **installment_number** | integer | Número da parcela | | **installment_payment** | array | Lista de pagamentos realizados na parcela | | **installment_status** | string | Status atual da parcela | | **installment_type** | string | Tipo da parcela — sempre "principal" | | **original_due_principal** | float | Saldo devedor original no momento da emissão | | **original_pre_fixed_amount** | float | Valor original dos juros pré-fixados na emissão | | **original_principal_amortization_amount** | float | Valor original de amortização do principal na emissão | | **original_total_amount** | float | Valor total original da parcela na emissão | | **paid_amount** | float | Valor já pago na parcela | | **paid_at** | string | Data do pagamento | | **post_fixed_amount** | float | Valor dos juros pós-fixados — sempre 0 | | **pre_fixed_amount** | float | Valor atual dos juros pré-fixados | | **principal_amortization_amount** | float | Valor de amortização do principal | | **qr_code_key** | string | Chave do QR Code PIX | | **qr_code_url** | string | URL do QR Code PIX | | **renegotiation_proposal_key** | string | Chave da proposta de renegociação, se aplicável | | **tax_amount** | float | Valor do IOF na parcela | | **total_accrual_amount** | float | Valor total de juros acumulados | | **total_amount** | float | Valor total da parcela | | **total_paid_amount** | float | Valor total pago na parcela até o momento | | **workdays** | integer | Dias úteis entre parcelas | --- # Simulação - Emissão Crédito Clean URL: /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: /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: /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: /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: /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: /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: /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: /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: /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: /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: /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: /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: /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: /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: /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: /documentation/manual_qi_sign/ :::danger Atenção! Os webhooks da QI Tech não devem ser mapeadas de forma restrita. Campos adicionais podem ser incluídos aos payloads dos webhooks retornados em nossas APIs. ::: ## Introdução Bem vindo à API de Assinaturas da QiTech! Esta API dá acesso ao serviço de assinatura eletrônica de documentos! ### Problemas? Caso tenha algum problema entre em contato com o nosso suporte (suporte@qitech.com.br) e nós responderemos o mais rápido possível. ### Ambientes Possuímos dois ambientes para os nossos clientes. As URLs base das APIs são: - Produção - `https://api.sign.qitech.com.br/` - Sandbox - `https://api.sandbox.sign.qitech.com.br/` :::danger Aviso Importante! Não devem ser usados dados reais de pessoas físicas e/ou jurídicas nos ambientes de Sandbox da QI Tech. ::: ## Somente HTTPS Por questão de segurança, toda a comunicação com as APIs da QI Tech deve ser realizada utilizando a comunicação HTTPS. Para evitar que, por desatenção ou outro motivo, sejam feitas chamadas HTTP, este servidor somente disponibiliza a porta 443 com comunicação TLS 1.2. Chamadas realizadas utilizando outros protocolos serão automaticamente negadas. ## Autenticação > Para autenticar uma chamada, utilize o código seguinte: ```shell # No shell, você somente precisa adicionar o header adequado em cada requisição curl "api_endpoint_here" -H "Authorization: EXAMPLE_API_KEY" ``` > Substitua a API key 'EXAMPLE_API_KEY' com a sua chave adquirida com o nosso suporte. Utilizamos uma API Key para permitir acesso a nossa API. Ela provavelmente já foi enviada por e-mail para você. Caso você ainda não tenha recebido a sua chave, envie um e-mail para suporte@qitech.com.br . Nossa API espera receber a API Key em todas as requisições ao nosso servidor em um header como o abaixo: `Authorization: EXAMPLE_API_KEY` Você deve substituir EXAMPLE_API_KEY com a API Key recebida do suporte. Envelopes são os objetos que contêm os documentos a serem assinados eletronicamente. Eles são criados a partir de um ou mais arquivos e podem ser enviados para assinatura por e-mail, SMS ou WhatsApp. Para criar um envelope, você deve enviar um arquivo ou um conjunto de arquivos para a API. O envelope será criado e você receberá um identificador único para ele. ## Criando um Envelope Para criar um Envelope, realize uma chamada `POST` para o endpoint `/sign/envelope` com os dados do(s) assinante(s). ```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" } ] }' ``` ## Definição do Objeto Envelope Todas as trocas de informação de um envelope utilizam a seguinte definição para este objeto. Em alguns casos, para facilitar a implementação e diminuir o fluxo de dados entre as partes, algumas informações poderão ser omitidas. | Nome | Tipo | Descrição | | --------------- | ------ | ---------------------------------------------------------------------------------- | | id | string | Identificador único do envelope.
**É essencial que este número seja único** | | subject | string | Título do envelope. Aparece no assunto do email. | | expiration_date | string | Data de expiração do envelope no formato `YYYY-MM-DD`. | | signers | list | Lista de objetos do tipo Signer que descreve os assinantes do envelope. | ### Definição do Objeto Signer | Nome | tipo | descrição | | :------------------------------: | :----: | ------------------------------------------------------------------------------------------------------------------ | | id | string | Identificador da transação do assinante.
**É essencial que este número seja único por envelope** | | email | string | Endereço de e-mail do assinante. | | name | string | Nome completo do assinante. | | birthdate | string | Data de nascimento do assinante no formato `YYYY-MM-DD`. | | document_number | string | Número do documento do assinante. | | phone | object | Objeto que descreve o telefone do assinante. | | phone.international_dial_code | string | Código do país do telefone do assinante. | | phone.area_code | string | Código de área do telefone do assinante. | | phone.number | string | Número do telefone do assinante. | | document_submission_method | enum | Método de envio dos documentos para assinatura.
Métodos disponíveis: **_email, sms e whatsapp _** | | authentication_submission_method | enum | Método de envio do token de autenticação para assinatura.
Métodos disponíveis: **_email, sms e whatsapp _** | - Campo email e phone podem ser enviados juntos ou separados, mas ao menos um deles deve ser enviado. - Todos os campos são obrigatórios. ### Resposta da criação do envelope Após o sucesso na criação do envelope, a resposta será um JSON contendo o id e status do envelope, conforme o exemplo ao lado: > Resposta exemplo ```json { "id": "814e7ed3-4080-4cae-a853-8e12812817ea", "status": "created" } ``` ## Adicionando documentos de identificação ao assinante Para adicionar documentos de identificação ao assinante, realize uma chamada `POST` para o endpoint `/sign/envelope/\{envelope_id\}/signer/\{signer_id\}/personal_document` para cada documento a ser adicionado. O arquivo deve ser enviado no corpo da requisição seguindo o seguinte formato: ```json { "document_b64": "Q5YACgAAAABDlgAbAAAAAEOWAC0AAAAAQ5YAPwAAAABDlgdN...", "template": "cnh_front", "file_type": "jpeg" } ``` ### Templates disponíveis Para cada tipo de documento de identificação, é necessário informar o template correspondente. Os templates disponíveis são: | Template | Descrição | | --------- | ------------------------------------------------------------------------ | | cnh_front | Carteira Nacional de Habilitação brasileira frente (Lado da foto). | | cnh_back | Carteira Nacional de Habilitação brasileira frente (Lado da assinatura). | | rg_front | Carteira de Identidade brasileira frente (Lado da foto). | | rg_back | Carteira de Identidade brasileira verso (Lado dos dados). | ### Descrição dos Atributos de Envio | Atributo | Descrição | | ------------ | -------------------------------------------------------------------------------------------------- | | document_b64 | Documento de identificação codificado em base64. | | template | Declara o template que deve ser aplicado para análise da imagem. | | file_type | Identifica o formato do arquivo enviado, `jpeg`. Caso não seja enviado, o valor `jpeg` é assumido. | - O tamanho máximo do documento de identificação deve ser de 10 MB - Todos os campos são obrigatórios exceto o `file_type`. ### Resposta da adição de documentos de identificação Após o sucesso na adição de documentos de identificação, a resposta será um JSON contendo o `created_at` conforme o exemplo ao lado: > Resposta exemplo ```json { "created_at": "2023-01-01T00:00:00.000Z" } ``` ### Coleta do documento de identificação Caso não seja enviado um documento de identificação do assinante, o mesmo será solicitado para realizar a coleta no momento da assinatura. ## Adicionando documentos ao envelope Para adicionar documentos para assinatura a um envelope, realize uma chamada `POST` para o endpoint `/sign/envelope/\{envelope_id\}/document` para cada documento a ser adicionado. O arquivo deve ser enviado no corpo da requisição seguindo o seguinte formato: ```json { "id": "3dfc5526-ee47-4b63-ad97-ddaf5b1c9110", "document_b64": "Q5YACgAAAABDlgAbAAAAAEOWAC0AAAAAQ5YAPwAAAABDlgdN...", "name": "Laudo de vistoria de entrada", "document_type": "pdf" } ``` - O tamanho máximo do documento deve ser de 10 MB ### Definição do Objeto Document | nome | tipo | descrição | | :-----------: | :----: | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | id | string | Identificador do documento.
**É essencial que este número seja único dentro do envelope**
**Opcional** Caso não seja informado, geraremos uma GUID no padrão UUID4 de 36 caracteres. | | document_b64 | string | Documento codificado em base64. | | name | string | Nome do documento. | | document_type | enum | Tipo do documento.
Tipo disponível: **_pdf_** | ### Resposta da adição de documentos ao envelope Após o sucesso na adição de documentos ao envelope, a resposta será um JSON contendo o identificador do documento e a data de criação, conforme o exemplo abaixo: > Resposta exemplo ```json { "id": "3dfc5526-ee47-4b63-ad97-ddaf5b1c9110", "created_at": "2023-01-01T00:00:00.000Z" } ``` ## Enviando o envelope para assinatura Para enviar o envelope para assinatura, realize uma chamada `PATCH` para o 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": "submitted" }' ``` ### Resposta do envio do envelope para assinatura Após o sucesso no envio do envelope para assinatura, a resposta será um JSON contendo o status do envelope, conforme o exemplo abaixo: > Resposta exemplo ```json { "status": "submitted" } ``` Após o envio do envelope para assinatura, os assinantes receberão um e-mail ou uma mensagem com o link para assinar os documentos. Ao acessar o link o assinante deverá preencher o CPF, assinar o documento e realizar o fluxo de validação facial e/ou documental a depender do fluxo do parceiro. Após a assinatura, o assinante será redirecionado para a página de sucesso. ## Consultando os dados do envelope Para verificar os dados do envelope, como status e assinantes, realize uma chamada GET para o endpoint `/sign/envelope/\{envelope_id\}` ```bash curl -X GET \ https://api.sign.qitech.com.br/sign/envelope/\{envelope_id\} \ -H "Authorization: EXAMPLE_API_KEY" ``` Caso a requisição seja bem sucedida, a resposta será um JSON contendo o status do envelope e informações sobre os assinantes, conforme a exemplo abaixo: > Resposta exemplo ```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" } ] } ] } ``` - O status do envelope pode ser `created`, `submitted`, `completed`, `canceled` ou `expired`. | enumeradores | descrição | | :----------: | -------------------------------------------------------------------- | | created | Envelope criado | | submitted | Envelope enviado para assinatura | | completed | Quando todas as assinaturas do envelope foram concluídas com sucesso | | canceled | Envelope cancelado por solicitação do parceiro | | expired | Envelope expirado por tempo de assinatura | | nome | tipo | descrição | | :-------------: | :------: | ------------------------------------------------------------------------- | | id | string | Identificador único do envelope. | | status | string | Status do envelope. | | expiration_date | string | Data de expiração do envelope. | | signers | Signer | Lista de objetos do tipo Signer que descreve os assinantes do envelope. | | documents | Document | Lista de objetos do tipo Document que descreve os documentos do envelope. | ## Webhook Ao final da assinatura por todos os assinantes e geração do dossiê, será disparada uma chamada por meio de Webhook. Para tanto, é necessário, por meio da equipe do suporte (suporte@qitech.com.br), configurar um endereço do endpoint por onde vamos notificar as atualizações e também uma _signature_key_ que será utilizada para assinar a requisição. O cliente pode, apesar de não recomendável, também utilizar a técnica de [polling]( ). Neste caso, basta não configurar o endpoint de webhook e utilizar os endpoints de recuperação de cadastro para proceder com o polling. ## Assinatura > Exemplo de cálculo de assinatura em Python ```python hmac_obj = hmac.new(signature_key.encode('utf-8'), (endpoint + method + payload).encode('utf-8'), hashlib.sha1) return hmac_obj.hexdigest() ``` Para garantir que a requisição recebida no endpoint do webhook parte dos nossos servidores, uma assinatura HMAC é enviada no Header Signature, semelhante ao processo de autenticação. Após realizar o cálculo do valor esperado da assinatura do lado do servidor, é necessário comparar a assinatura calculada com a enviada. Caso as assinaturas sejam compatíveis, isso significa que a requisição partiu dos nossos servidores e que é confiável. Exemplo de chamada webhook: ```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 } } ] } ``` | nome | tipo | descrição | | :---------------------------------------: | :-----: | -------------------------------------------------------------------------------- | | id | string | Identificador único do envelope. | | status | string | Status do envelope. | | signer.id | string | Identificador único do assinante. | | signer.biometry.face_validation_available | boolean | Indica se o rosto foi encontrado e validado. | | signer.biometry.fraud_base_flag | boolean | Indica se o rosto do assinante foi encontrado na base de fraude. | | signer.biometry.face_validation_score | integer | Indica o score da validação facial. | | signer.liveness.result | string | Indica o resultado da validação de liveness. Valores possíveis `live` ou `spoof` | | signer.document.face_match_score | integer | Indica o score da validação de face match. | ## Baixando os dossiês assinados Caso todos os assinantes tenham assinado todos os documentos do envelope, o status do envelope será `completed` e um dossiê para cada documento, com as assinaturas e dados dos assinantes estará disponível para download. Para isso, realize uma chamada `GET` para o endpoint `/sign/envelope/\{envelope_id\}/report` ```bash curl -X GET \ https://api.sign.qitech.com.br/sign/envelope/\{envelope_id\}/report \ -H "Authorization: EXAMPLE_API_KEY" ``` Caso a requisição seja bem sucedida, a resposta será um JSON contendo o id e status do envelope, além de uma lista com id do documento e a url do dossiê gerado, conforme o exemplo abaixo: > Resposta exemplo ```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" } ] } ``` - O link do relatório para cada documento terá validade de 24 horas. - O status dos relatórios para o envelope pode ser `available` ou `unavailable`. - A propriedade `documents_reports` contem a lista dos documentos do envelope, identificados pelo id do documento e o link do seu relatório. ## Baixando o dossiê por documento assinado Caso todos os assinantes tenham assinado todos os documentos do envelope, o status do envelope será `completed` e um dossiê para cada documento assinado, com as assinaturas e dados dos assinantes estará disponível para download. Para isso, realize uma chamada `GET` para o 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" ``` Caso a requisição seja bem sucedida, a resposta será um JSON contendo id, status, url e o base64 do dossiê do documento, conforme o exemplo abaixo: > Resposta exemplo ```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=..." } ``` - O link para o relatório do documento terá validade de 24 horas. - O status para o relatório do documento pode ser `available` ou `unavailable`. - A propriedade `document_report` é o relatório do documento em PDF codificado em base64. ## Baixando as fotos do rosto dos assinantes É possível recuperar as imagens do rosto dos assinantes. Para isso basta realizar um chamada `GET` para o 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" ``` Caso a requisição seja bem sucedida, a resposta será um JSON contendo a imagem codificada em base64, conforme o exemplo abaixo: > Resposta exemplo ```json { "face_image_url": "https://qisign-face-image.com/4fd09dab-6f3e-4ff5-bfed-6f7debfcde71.jpeg" } ``` ## Cancelando um envelope Para cancelar um envelope, realize uma chamada `PATCH` para o 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" }' ``` Caso a requisição seja bem sucedida, a resposta será um JSON contendo o status do envelope, conforme o exemplo abaixo: > Resposta exemplo ```json { "status": "canceled" } ``` ## Baixando as fotos do documento dos assinantes É possível recuperar as imagens do documento dos assinantes. Para isso basta realizar um chamada `GET` para o 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" ``` Caso a requisição seja bem sucedida, a resposta será um JSON contendo a imagem codificada em base64, conforme o exemplo abaixo: > Resposta exemplo ```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" } ``` ## Consultando o status de um assinante Para verificar o status de um assinante, realize uma chamada GET para o 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" ``` Caso a requisição seja bem sucedida, a resposta será um JSON contendo o status do assinante, conforme a exemplo abaixo: > Resposta exemplo ```json { "name": "John Sample", "email": "johnsample@test.com", "status": "signed", "signed_at": "2023-03-21T15:30:00.000Z" } ``` | nome | tipo | descrição | | :-------: | :----: | ----------------------------------------------------------------------- | | name | string | Nome do assinante. | | email | string | E-mail do assinante. | | status | string | Status da assinatura assinante. | | signed_at | string | Data e hora da última assinatura no formato `YYYY-MM-DDTHH:MM:SS.000Z`. | ## Status HTTP 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 | A requisição enviada possui algum erro de formatação. Na maioria dos casos, retornamos no corpo da mensagem uma explicação de onde está o erro. | | 401 | Unauthorized | Houve algum problema na autenticação, verifique se a API Key está correta e no header correto, de acordo com a seção Autenticação. | | 403 | Forbidden | O endpoint acessado é de uso interno e não está disponível para esta API Key. | | 404 | Not Found | O dado requisitado não foi encontrado usando a chave utilizada. Este status também é retornado quando um endpoint inválido é requisitado. | | 405 | Method Not Allowed | O método HTTP utilizado não se aplica ao endpoint utilizado. | | 406 | Not Acceptable | Os dados enviados no corpo da requisição são inválidos. Em geral, isso significa que os dados enviados não são um JSON válido. | | 409 | Conflict | O id da requisição corresponde a um id já processado anteriormente. Este status é retornado no caso de requisições duplicadas enviadas ao servidor. | | 500 | Internal Server Error | Tivemos um problema para processar esta requisição, ao encontrarmos esse erro nossos especialistas são automaticamente notificados e iniciam a análise e solução imediatamente. | | 503 | Service Unavailable | Você se deparou com uma indisponibilidade, planejada ou não, de infraestrutura dos nossos servidores. |