# QI Tech — Outros Produtos › Full BNPL Documentação da QI Tech em texto corrido, para colar em um LLM. Fonte: https://docs.qitech.com.br 18 página(s). Índice: - 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 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. :::