APP Integration

Resumo

Este guia descreve como emitir uma dívida (operação de crédito) para pessoa física através do fluxo BNPL / e-commerce utilizando o endpoint POST /signed_debt.

Este fluxo suporta pagamentos via QR Code, permitindo coletar as informações necessárias para o desembolso diretamente do QR Code, incluindo o número do documento do beneficiário, número da conta, dígito da conta, número da agência e o valor a desembolsar.

A emissão para pessoa física representa um empréstimo padrão. Nesse cenário:

• O campo financial.disbursed_amount especifica o valor principal a ser desembolsado ao tomador. Ele deve ser igual ao valor registrado no QR Code Pix informado em disbursement_bank_accounts.
• borrower.person_type deve estar definido como natural.
• O campo refinanced_credit_operations não deve ser informado.

A estrutura do borrower, additional_data.contract (assinaturas opt-in), disbursement_bank_accounts e demais objetos da requisição é descrita nas seções a seguir.

disbursed_amount deve ser igual ao valor do QR Code

O valor desembolsado (financial.disbursed_amount) deve ser igual ao valor registrado no QR Code Pix. Decodifique o QR Code primeiro via POST /pix/decode_qrcode_payload (passo 1) para obter o valor e use esse mesmo valor em disbursed_amount na emissão da dívida.

1. Decodificação do QR Code

Requisição

ENDPOINT

pix/decode_qrcode_payload

MÉTODO

POST

Testar no Playground

Corpo da requisição

{
   "qr_code_type": "dynamic_instant",
   "qr_code_payload": "00020101021226850014br.gov.bcb.pix2563qrcodepix.bb.com.br/pix/v2/d373e385-dfe7-49f6-b9ec-14ba60a9b8285204000053039865802BR5925TESTE62070503***63047B7D",
   "pix_key": "teste.cobrancapix@gmail.com.br",
   "receiver_conciliation_id": "fgnb4NTt7pOUBGfrcporERwVVqr0f8PWRfK",
   "amount": "9367.61",
   "status": "ATIVA"
}

Corpo da resposta

Campo	Tipo	Descrição	Disponível
qr_code_type	string	Tipo do QR Code: static, dynamic_instant ou dynamic_term.	Todos
qr_code_payload	string	Payload EMV original recebido na requisição.	Todos
pix_key	string	Chave Pix do recebedor extraída do payload do QR Code.	Todos
transfer_amount	string	Valor da transferência, quando especificado no QR Code.	static
additional_data	string	Dados adicionais contidos no QR Code estático.	static
receiver_conciliation_id	string	Identificador de conciliação do recebedor (txid).	dynamic_*
amount	string	Valor original da cobrança.	dynamic_*
status	string	Status da cobrança dinâmica.	dynamic_*

Status

Para QR Codes dinâmicos, o status do QR Code é retornado conforme a tabela de enumeração abaixo.

Erros

QR Code com formato inválido

{
  "data": "{\"title\": \"Invalid Qr Code Format\", \"description\": \"The Qr Code format is invalid, please enter a valid Qr Code\", \"translation\": \"O formato do Qr Code é inválido, por favor insira um Qr Code válido\", \"extra_fields\": {}, \"code\": \"PXT000070\"}"
}

Tipo de QR Code não identificado no payload

{
  "data": "{\"title\": \"Invalid Qr Code Type\", \"description\": \"The Qr Code payload given did not provide a propper Qr Code type\", \"translation\": \"O payload de QR Code fornecido não contêm um tipo de Qr Code Válido\", \"extra_fields\": {}, \"code\": \"PXT000071\"}"
}

Erro ao solicitar o payload do QR Code à instituição de registro

{
  "data": "{\"title\": \"Error in Qr Code Payload Request\", \"description\": \"An error occurred while requesting the qr code payload to the registry institution\", \"translation\": \"Um erro ocorreu durante a requisição do payload do qr code para a instituição de registro\", \"extra_fields\": {}, \"code\": \"PXT000069\"}"
}

2. Emissão de dívida

Requisição

ENDPOINT

/signed_debt

MÉTODO

POST

Testar no Playground

Corpo da requisição

{
   "additional_data": {
      "contract": {
         "contract_number": null,
         "signed": true,
         "signatures": [
            {
               "signer": {
                  "name": "Alan Mathison Turing",
                  "phone": { "number": "912345678", "area_code": "11", "country_code": "055" },
                  "email": "alan.turing@email.com",
                  "document_number": "96969879003"
               },
               "signature": {
                  "ip_address": "168.211.22.84",
                  "timestamp": "27-10-2025 11:07:15",
                  "signature_file": { "file_url": "http://qitech.com.br/signature.pdf", "file_type": "pdf" },
                  "geolocation": { "long": "-46.63611", "lat": "-23.5475" },
                  "fingerprint_device": null
               }
            }
         ]
      }
   },
   "financial": {
      "number_of_installments": 2,
      "credit_operation_type": "ccb",
      "interest_type": "pre_price_days",
      "monthly_interest_rate": 0.07,
      "disbursed_amount": 150000,
      "fine_configuration": { "contract_fine_rate": 0.02, "monthly_rate": 0.15, "interest_base": "calendar_days" },
      "interest_grace_period": 0,
      "disbursement_date": "2026-04-11",
      "first_due_date": "2026-05-10",
      "principal_grace_period": 0
   },
   "purchaser_document_number": "32402502000135",
   "requester_identifier_key": "40822732-c4ce-41fb-9ee5-5e0304cd04a7",
   "document_template_key": "518a0b57-2ce3-4309-94e5-6a95bc056d12",
   "borrower": {
      "email": "alan.turing@email.com",
      "document_identification": "494598fd-c226-4332-a500-591ae3884673",
      "document_identification_back": "494598fd-c226-4332-a500-591ae3884673",
      "birth_date": "1998-06-03",
      "person_type": "natural",
      "is_pep": false,
      "mother_name": "Nome completo da mãe",
      "profession": "Servidor público",
      "individual_document_number": "82744088021",
      "address": {
         "city": "São Paulo",
         "neighborhood": "CENTRO",
         "street": "Avenida Feliz",
         "complement": "",
         "postal_code": "49026100",
         "state": "SP",
         "number": ""
      },
      "phone": { "country_code": "055", "number": "912345678", "area_code": "11" },
      "document_identification_number": "47003534819",
      "name": "Alan Mathison Turing"
   },
   "disbursement_bank_accounts": [
      {
         "qr_code_url": "00020126930014br.gov.bcb.pix2571qrcode-h.sandbox.qitech.app/bacen/cobv/3fecc731adf542659b84be038ec4151e5204000053039865802BR5925LogcardMeiosDePagamentoLt6008SaoPaulo61080145200062070503***6304A936"
      }
   ]
}

Atenção

A emissão para pessoa física utiliza borrower.person_type: "natural" e um individual_document_number (CPF). financial.disbursed_amount deve ser igual ao valor registrado no QR Code Pix enviado em disbursement_bank_accounts — decodifique o QR Code antes via POST /pix/decode_qrcode_payload. Omita refinanced_credit_operations (esse campo só é utilizado quando há quitação de operações existentes em refinanciamento).

Parâmetros do corpo

Campo	Tipo	Descrição	Máx caracteres
additional_data *	object	Metadados do contrato e evidências de assinatura em additional_data.contract (número do contrato, flag de assinatura, signatures[] com signer e evidências).	-
borrower *	object	Objeto borrower — pessoa física tomadora do crédito.	-
disbursement_bank_accounts *	array	Contas de desembolso — array contendo o QR Code que recebe o desembolso (um único item neste fluxo).	-
financial *	object	Objeto financial — condições financeiras; use disbursed_amount para o valor a desembolsar ao tomador.	-
purchaser_document_number *	string	CNPJ do cessionário (somente dígitos, sem formatação).	-
requester_identifier_key	string	Chave de rastreio do cliente para a requisição.	50
document_template_key	string	Chave do template do contrato a ser utilizado na operação.	UUID

Objeto borrower

Campo	Tipo	Descrição	Máx caracteres
name *	string	Nome completo do tomador	100
email	string	E-mail do tomador	254
phone	object	Objeto phone — telefone de contato	-
is_pep *	boolean	Indicador de PEP (http://www.portaldatransparencia.gov.br/download-de-dados/pep)	-
address *	object	Objeto address — endereço do tomador	-
role_type	enum	Papel do tomador no contrato. Padrão: issuer.	-
birth_date *	date	Data de nascimento (YYYY-MM-DD)	-
mother_name *	string	Nome completo da mãe	100
nationality	string	Nacionalidade	50
profession	string	Profissão do tomador	100
person_type *	string	Tipo de pessoa — deve ser natural para pessoas físicas	-
individual_document_number *	string	CPF do tomador (somente dígitos)	11
document_identification *	string	DOCUMENT_KEY do PDF do documento (RG ou CNH), enviado previamente	UUID
document_identification_back	string	DOCUMENT_KEY do verso do documento (enviado previamente)	UUID
document_identification_number	string	Número do documento de identificação do tomador (RG ou CNH), somente dígitos	20

Objeto address

Campo	Tipo	Descrição	Máx caracteres
city *	string	Cidade	100
state *	string	Estado (duas letras maiúsculas)	2
number *	string	Número	10
street *	string	Logradouro	100
complement *	string	Complemento do endereço (texto livre)	100
postal_code *	string	CEP (https://www.buscacep.correios.com.br/)	8
neighborhood *	string	Bairro	100

Objeto phone

Campo	Tipo	Descrição	Máx caracteres
number *	string	Número do telefone	10
area_code *	string	DDD (https://ddd.guiamais.com.br/)	2
country_code *	string	DDI (https://ddi.guiamais.com.br/)	3

Contas de desembolso

Neste fluxo, o desembolso é liquidado pelo pagamento do QR Code dinâmico Pix fornecido pelo lojista. Em vez de enviar as coordenadas bancárias do beneficiário, envie o payload do QR Code dentro de disbursement_bank_accounts — a QI Tech decodifica e roteia o desembolso para o dono do QR Code.

disbursement_bank_accounts é um array com um único item contendo apenas o payload do QR Code:

Campo	Tipo	Descrição	Máx caracteres
qr_code_url *	string	Payload EMV do QR Code dinâmico Pix a ser pago.	250

Consistência de valor

O valor registrado no QR Code deve ser igual a financial.disbursed_amount. Decodifique o QR Code via POST /pix/decode_qrcode_payload (passo 1) para obter o valor e use esse mesmo valor em disbursed_amount na emissão da dívida.

Objeto financial

O objeto financial descreve as condições financeiras da operação de crédito.

Campo	Tipo	Descrição	Máx caracteres
disbursed_amount *	float	Valor desembolsado ao tomador (principal da operação)	-
interest_type	enum	Tipo de juros — amortização e cálculo de juros	-
credit_operation_type	enum	Tipo da operação de crédito — tipo de instrumento	-
monthly_interest_rate	float	Taxa de juros mensal prefixada (decimal)	-
disbursement_date	date	Data de desembolso (YYYY-MM-DD)	-
first_due_date	date	Data do primeiro vencimento (YYYY-MM-DD)	-
interest_grace_period	int	Carência de juros (meses)	-
principal_grace_period	int	Carência do principal	-
number_of_installments	int	Número de parcelas	-
fine_configuration	object	Configuração de multa — juros de mora e multa	-

Objeto fine_configuration

A configuração de multa define a multa e os juros de mora aplicáveis à operação.

Campo	Tipo	Descrição	Máx caracteres
contract_fine_rate	float	Taxa de multa contratual	-
interest_base	enum	Base de juros — base de cálculo dos juros	-
monthly_rate	float	Taxa de juros de mora mensal	-

Enumeradores

Person type

Valor	Descrição
natural	Pessoa física
legal	Pessoa jurídica

Account type

Valor	Descrição
checking_account	Conta corrente
deposit_account	Conta de depósito
guaranteed_account	Conta garantida
investment_account	Conta de investimento
payment_account	Conta de pagamento
saving_account	Poupança
salary_account	Conta salário

Interest type

Valor	Descrição
pre_price_days	Método Price (parcelas iguais) com juros prefixados diários
pre_price	Método Price (parcelas iguais) com juros prefixados em períodos fixos de 30 dias
pre_sac	SAC (amortização constante) com juros prefixados diários
post_sac	SAC com taxa prefixada + índice pós-fixado (CDI, IPCA ou IGP-M), diário
post_price	Price com taxa prefixada + índice pós-fixado em períodos fixos de 30 dias
post_price_days	Price com taxa prefixada + índice pós-fixado, diário

Credit operation type

Valor	Descrição
ccb	Cédula de Crédito Bancário
cce	Cédula de Crédito à Exportação
nce	Nota de Crédito à Exportação

BNPL

No fluxo BNPL / e-commerce, ccb é o valor utilizado na prática.

Interest base

Valor	Descrição
workdays	Dias úteis, ano de 252 dias
calendar_days	Dias corridos, ano de 360 dias
calendar_days_365	Dias corridos, ano de 365 dias

Resposta (HTTP 200)

A resposta síncrona ecoa o corpo da requisição com campos completados pela plataforma (por exemplo contract.contract_number e requester_identifier_key).

STATUS

200

Corpo da resposta

{
   "additional_data": {
      "contract": {
         "contract_number": "TEST7886216399",
         "signed": true,
         "signatures": [
            {
               "signer": {
                  "name": "Alan Mathison Turing",
                  "phone": { "number": "912345678", "area_code": "11", "country_code": "055" },
                  "email": "alan.turing@email.com",
                  "document_number": "96969879003"
               },
               "signature": {
                  "ip_address": "168.211.22.84",
                  "timestamp": "27-10-2025 11:07:15",
                  "signature_file": { "file_url": "http://qitech.com.br/signature.pdf", "file_type": "pdf" },
                  "geolocation": { "long": "-46.63611", "lat": "-23.5475" },
                  "fingerprint_device": null
               }
            }
         ]
      }
   },
   "financial": {
      "number_of_installments": 2,
      "credit_operation_type": "ccb",
      "interest_type": "pre_price_days",
      "monthly_interest_rate": 0.07,
      "disbursed_amount": 150000,
      "fine_configuration": { "contract_fine_rate": 0.02, "monthly_rate": 0.15, "interest_base": "calendar_days" },
      "interest_grace_period": 0,
      "disbursement_date": "2026-04-11",
      "first_due_date": "2026-05-10",
      "principal_grace_period": 0
   },
   "purchaser_document_number": "32402502000135",
   "requester_identifier_key": "40822732-c4ce-41fb-9ee5-5e0304cd04a7",
   "document_template_key": "518a0b57-2ce3-4309-94e5-6a95bc056d12",
   "borrower": {
      "email": "alan.turing@email.com",
      "document_identification": "494598fd-c226-4332-a500-591ae3884673",
      "document_identification_back": "494598fd-c226-4332-a500-591ae3884673",
      "birth_date": "1998-06-03",
      "person_type": "natural",
      "is_pep": false,
      "mother_name": "Nome completo da mãe",
      "profession": "Servidor público",
      "individual_document_number": "82744088021",
      "address": { "city": "São Paulo", "neighborhood": "CENTRO", "street": "Avenida Feliz", "complement": "", "postal_code": "49026100", "state": "SP", "number": "" },
      "phone": { "country_code": "055", "number": "912345678", "area_code": "11" },
      "document_identification_number": "47003534819",
      "name": "Alan Mathison Turing"
   },
   "disbursement_bank_accounts": [
      {
         "qr_code_url": "00020126930014br.gov.bcb.pix2571qrcode-h.sandbox.qitech.app/bacen/cobv/3fecc731adf542659b84be038ec4151e5204000053039865802BR5925LogcardMeiosDePagamentoLt6008SaoPaulo61080145200062070503***6304A936"
      }
   ]
}

Webhook (webhook_type: debt)

Após a operação ser processada, a QI Tech notifica seu endpoint com os dados consolidados da dívida, incluindo o valor emitido, breakdown de IOF, taxa de juros prefixada e o cronograma de parcelas.

Corpo do webhook

{
   "webhook_type": "debt",
   "key": "4e1ed268-9f29-44ce-9991-3bdf036aeacd",
   "status": "waiting_disbursement",
   "event_datetime": "2026-04-14 03:38:14",
   "data": {
      "borrower": {
         "name": "Alan Mathison Turing",
         "document_number": "82744088021",
         "related_party_key": "71b28fde-5d75-48b4-9c3f-ee531dccac66"
      },
      "contract": {
         "document_key": null,
         "number": "TEST7886216399",
         "urls": [],
         "signature_information": [
            {
               "signer_name": "Alan Mathison Turing",
               "signer_document_number": "82744088021",
               "signer_role": "issuer",
               "signer_email": null,
               "signer_external_key": null,
               "signature_url": null
            }
         ]
      },
      "requester_identifier_key": "40822732-c4ce-41fb-9ee5-5e0304cd04a7",
      "iof_charge_method": "financed",
      "collaterals": [],
      "contract_fees": [ { "fee_type": "spread", "fee_amount": 453.39 } ],
      "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": 453.39,
      "issue_amount": 151131.6,
      "assignment_amount": 151584.99,
      "cet": "7,6600%",
      "annual_cet": "142,4473%",
      "number_of_installments": 2,
      "base_iof": 557.3,
      "additional_iof": 574.3,
      "total_iof": 1131.6,
      "ipoc_code": "324025020203182744088021TEST7886216399",
      "prefixed_interest_rate": {
         "annual_rate": 1.252191589,
         "created_at": "2026-04-14T03:38:10",
         "daily_rate": 0.0022578334,
         "interest_base": "calendar_days",
         "monthly_rate": 0.07
      },
      "installments": [
         {
            "business_due_date": "2026-05-11",
            "calendar_days": 29,
            "due_date": "2026-05-10",
            "due_interest": 0,
            "due_principal": 151131.6,
            "has_interest": true,
            "installment_key": "c00dbecc-efb9-4384-8db3-dadba82f2d70",
            "installment_number": 1,
            "installment_status": "created",
            "installment_type": "principal",
            "pre_fixed_amount": 10214.91484159,
            "principal_amortization_amount": 73277.28515841,
            "tax_amount": 174.25338411,
            "total_amount": 83492.2,
            "workdays": 18
         },
         {
            "business_due_date": "2026-06-10",
            "calendar_days": 31,
            "due_date": "2026-06-10",
            "due_interest": 0,
            "due_principal": 77854.31484159,
            "has_interest": true,
            "installment_key": "d3a2f42d-80cb-4891-b2be-ce80ffd383b2",
            "installment_number": 2,
            "installment_status": "created",
            "installment_type": "principal",
            "pre_fixed_amount": 5637.88515841,
            "principal_amortization_amount": 77854.31484159,
            "tax_amount": 383.04322902,
            "total_amount": 83492.2,
            "workdays": 22
         }
      ],
      "total_pre_fixed_amount": 15852.8
   }
}

3. Consulta de dívida

Você pode consultar a dívida posteriormente para recuperar informações ou acompanhar o status atual.

Requisição

ENDPOINT

/v2/credit_operation/requester_identifier_key/REQUESTER-IDENTIFIER-KEY

MÉTODO

GET

Testar no Playground

Parâmetros de path

Campo	Tipo	Descrição	Máx caracteres
requester_identifier_key *	string	Chave de rastreio do cliente enviada na emissão da dívida	50

Rota alternativa

Caso possua o credit_operation_key (UUID), utilize GET /v2/credit_operation/{credit_operation_key}.

Resposta

STATUS

200

Corpo da resposta

{
   "credit_operation_key": "0773a1b1-675a-4a10-80a2-a10308c7281e",
   "issue_amount": 151131.6,
   "origin_key": "0773a1b1-675a-4a10-80a2-a10308c7281e",
   "total_iof": 1131.6,
   "assigned_at": null,
   "disbursement_start_date": "2026-04-11",
   "disbursement_end_date": "2026-04-11",
   "issue_date": "2026-04-11",
   "requester_identifier_key": "40822732-c4ce-41fb-9ee5-5e0304cd04a7",
   "installments": [
      {
         "due_date": "2026-05-10",
         "calendar_days": 29,
         "due_principal": 151131.6,
         "has_interest": true,
         "installment_key": "c00dbecc-efb9-4384-8db3-dadba82f2d70",
         "installment_number": 1,
         "installment_status": "created",
         "installment_type": "principal",
         "pre_fixed_amount": 10214.91484159,
         "principal_amortization_amount": 73277.28515841,
         "tax_amount": 174.25338411,
         "total_amount": 83492.2
      }
   ]
}

4. Especificações técnicas e enumeradores

Objeto installments

Campo	Tipo	Descrição
calendar_days	integer	Número de dias corridos entre parcelas
due_date	string	Data de vencimento da parcela em dias corridos
due_principal	float	Saldo do principal na data de vencimento da parcela, antes do pagamento
has_interest	boolean	Se verdadeiro, há incidência de juros na parcela
installment_number	integer	Número da parcela
pre_fixed_amount	float	Valor de juros prefixados pago na parcela
principal_amortization_amount	float	Valor do principal amortizado na parcela
tax_amount	float	Valor base de IOF da parcela
total_amount	float	Valor total da parcela
due_interest	float	Saldo de juros após a data de vencimento da parcela, antes do pagamento
workdays	integer	Dias úteis entre parcelas

Objeto interest_rate

Campo	Descrição
annual_rate	Taxa de juros anual prefixada/flutuante (decimal)
daily_rate	Taxa de juros diária prefixada/flutuante (decimal)
interest_base	Base de juros — base de cálculo dos juros
monthly_rate	Taxa de juros mensal prefixada/flutuante (decimal)

Objeto tax_configuration

Campo	Descrição
base_rate	Valor da alíquota base de IOF
additional_rate	Valor da alíquota adicional de IOF

---

Fluxo de reembolso

Este guia explica como processar reembolsos totais e parciais para operações de crédito originadas via fluxo BNPL / e-commerce utilizando o endpoint POST /signed_debt.

O fluxo de reembolso é composto por duas etapas principais:

1. Notificação de chargeback — um webhook é enviado sempre que um chargeback é processado, independentemente de representar um reembolso total ou parcial. O webhook contém todas as informações necessárias para identificar e processar o chargeback.
2. Renegociação — após processar o webhook com sucesso, é possível iniciar uma renegociação para gerar um novo cronograma de parcelas refletindo o valor reembolsado. Os termos da renegociação são totalmente configuráveis e devem seguir suas regras e políticas de negócio.

Webhook — Reembolso recebido

Visão geral

Assim que um reembolso identificado for recebido, a QI Tech enviará um webhook contendo os detalhes do reembolso, incluindo se trata-se de reembolso total ou parcial e o valor creditado na conta do FIDC.

Com base nessas informações, você poderá aplicar suas políticas de negócio e determinar como proceder com o reembolso solicitado por seu cliente.

Corpo do webhook

{
   "origin_key": "d5c88545-4d17-4679-b262-ae170618078a",
   "refund_date": "2026-06-26",
   "webhook_type": "laas.transitory_conciliation.refund",
   "amount": "200.00",
   "event_datetime": "2026-06-12T11:52:22"
}

Renegociação — Simulação

Visão geral

Antes de criar uma proposta, é possível simular os valores do estorno para a operação. A simulação retorna as parcelas afetadas, o valor presente, o desconto e o valor total.

O fluxo de reembolso utiliza dois tipos de amortização:

• equal_amount — estorno parcial. Distribui payment_amount proporcionalmente entre as parcelas em aberto, reduzindo o saldo devedor. 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.

Requisição

ENDPOINT

/renegotiation/simulation

MÉTODO

POST

Testar no Playground

Corpo da requisição

equal_amount (parcial)

{
    "debt_key": "72760166-4ddf-41fb-8a8c-605f8f4fc35c",
    "amortization_type": "equal_amount",
    "reference_date": "2026-04-13",
    "payment_amount": 50.00
}

full_settle (total)

{
    "debt_key": "72760166-4ddf-41fb-8a8c-605f8f4fc35c",
    "amortization_type": "full_settle",
    "reference_date": "2026-04-13",
    "payment_amount": 1043.55
}

Parâmetros do corpo

Campo	Tipo	Descrição	Máx tamanho
debt_key *	string	Chave única da operação de crédito (DEBT-KEY)	UUID
amortization_type *	string	Modalidade do estorno	Valores do amortization_type
payment_amount *	float	Valor do estorno em reais. Em equal_amount, valor parcial a ser abatido. Em full_settle, deve cobrir o saldo total na reference_date.	15,2
reference_date	string	Data de referência para cálculo do valor presente (YYYY-MM-DD). Não pode ser anterior à data de desembolso.	10
discount_percentage	float	Percentual de desconto opcional sobre o valor presente. Não pode ser enviado junto com discount_amount.	-
discount_amount	float	Valor de desconto opcional sobre o valor presente. Não pode ser enviado junto com discount_percentage.	-

Valores do amortization_type

Valor	Descrição
equal_amount	Estorno parcial. payment_amount é distribuído proporcionalmente entre as parcelas em aberto; 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.

Resposta

STATUS

200

Exemplo de corpo de resposta

{
    "amortization_type": "equal_amount",
    "payment_amount": 50.00,
    "discount_percentage": 0,
    "discount_amount": 0,
    "reference_date": "2026-04-13",
    "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
        }
    ]
}

Renegociação — Proposta

Visão geral

Após validar a simulação, crie a proposta de renegociação. Para o fluxo de estorno, envie payment_type: "internal" — o valor é debitado diretamente da account_key informada, sem geração de boleto ou Pix.

Atenção

• A operação deve estar ativa e já desembolsada.
• reference_date não pode ser anterior à data de desembolso.
• request_control_key é obrigatório para idempotência.

Requisição

ENDPOINT

/renegotiation/proposal

MÉTODO

POST

Testar no Playground

Corpo da requisição

equal_amount (parcial)

{
    "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)

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

Parâmetros do corpo

Campo	Tipo	Descrição	Máx tamanho
debt_key *	string	Chave única da operação de crédito (DEBT-KEY)	UUID
payment_type *	string	Para fluxo de estorno, use internal.	Valores do payment_type
amortization_type *	string	Modalidade do estorno	Valores do amortization_type
payment_amount *	float	Valor do estorno em reais.	15,2
account_key *	string	Chave da conta interna de onde o valor será debitado.	UUID
request_control_key *	string	Chave de idempotência do cliente. Use um valor único por tentativa.	50
reference_date	string	Data de referência para cálculo do valor presente (YYYY-MM-DD). Não pode ser anterior à data de desembolso.	10
discount_percentage	float	Percentual de desconto opcional sobre o valor presente. Não pode ser enviado junto com discount_amount.	-
discount_amount	float	Valor de desconto opcional sobre o valor presente. Não pode ser enviado junto com discount_percentage.	-

Valores do payment_type

Valor	Descrição
internal	Débito interno na account_key (automático, sem boleto ou Pix). Usado para o fluxo de estorno.
bank_slip	Gera boleto bancário e Pix.
pix	Somente Pix.
manual	Pagamento manual (sem geração de meio de pagamento).

Valores do amortization_type

Valor	Descrição
equal_amount	Estorno parcial. payment_amount é distribuído proporcionalmente entre as parcelas em aberto; 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.

Resposta

STATUS

201

Exemplo de corpo de resposta

{
    "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 da resposta

Campo	Tipo	Descrição
proposal_key	string	Chave única da proposta (UUID). Use para consulta e correlação com webhook.
proposal_status	string	Estado da proposta. Inicia em pending_payment; vai para paid quando o débito interno é processado.
affected_installments	array	Parcelas que receberam o estorno. Mostra a composição do paid_amount entre principal, juros e multa.
remaining_installments	array	Parcelas que permanecem em aberto após o estorno. Vazio em full_settle.
payment.payment_data.target_account_key	string	Conta de destino do débito interno.
payment.payment_data.transaction_amount	float	Valor efetivamente debitado da account_key.
devolution_amount	float	Sobrepagamento devolvido ao fundo. Só é diferente de zero quando um pagamento prévio somado ao estorno excede o saldo devedor.
request_control_key	string	Eco da chave de idempotência enviada na requisição.

Webhook de quitação

Quando um estorno quita integralmente a operação — tipicamente em full_settle, também possível quando equal_amount em sequência zera o saldo — a QI Tech envia um webhook webhook_type: debt com status: settled. Use para confirmar a quitação de forma assíncrona.

Renegociação — Cancelar proposta

Visão geral

DELETE /renegotiation/proposal/{proposal_key} cancela uma proposta que ainda não foi finalizada. Apenas propostas com proposal_status: "pending_payment" são canceláveis. Quaisquer meios de pagamento associados (boleto, Pix) são invalidados.

Requisição

ENDPOINT

/renegotiation/proposal/{proposal_key}

MÉTODO

DELETE

Parâmetros de path

Campo	Tipo	Descrição	Máx tamanho
proposal_key *	string	Chave da proposta retornada em POST /renegotiation/proposal.	UUID

Resposta

STATUS

200

Exemplo de corpo de resposta

{
    "proposal_key": "bcc16a6d-ce21-4cd4-8d8c-d26f89ccc685",
    "proposal_status": "canceled",
    "request_control_key": "94b31045-c8e7-45be-a88d-2ae25c5df5db"
}

Consultar status da proposta

Após criar a proposta, é possível consultar seu status pelo request_control_key.

ENDPOINT

/renegotiation/proposal/request_control_key/REQUEST-CONTROL-KEY

MÉTODO

GET

A resposta segue o mesmo formato do retorno do POST /renegotiation/proposal. O proposal_status indica o andamento:

Status	Descrição
pending_payment	Proposta criada, aguardando processamento do débito interno.
paid	Débito processado. Em full_settle, a operação já está em settled.
canceled	Proposta cancelada via DELETE /renegotiation/proposal/{proposal_key}.

---

Renegociação em lote

Para cenários em que é necessário renegociar múltiplas operações do mesmo emissor de uma só vez — gerando um único meio de pagamento (boleto e/ou Pix) cobrindo todo o lote — utilize os endpoints em lote.

Atenção

• A renegociação em lote só pode incluir operações do mesmo emissor e da mesma chave de integração.
• Limite de 50 operações por lote.
• Os endpoints em lote suportam um conjunto distinto de tipos de amortização: installment_payment, overdue_installment_payment, present_amount. equal_amount e full_settle não estão disponíveis em lote.

Renegociação — Simulação em lote

Visão geral

Antes de criar uma proposta em lote, simule os valores. A simulação retorna as parcelas afetadas, os descontos e o valor total devido entre todas as operações.

Para present_amount na simulação, cada item de installments[] contém apenas installment_key. Os campos por parcela paid_amount e discount_amount são obrigatórios apenas no endpoint proposta em lote.

Requisição

ENDPOINT

/renegotiation/batch_proposal_simulation

MÉTODO

POST

Testar no Playground

Atenção

Na raiz, discount_amount e discount_percentage são mutuamente exclusivos.

Corpo da requisição

{
   "amortization_type": "installment_payment",
   "reference_date": "2026-04-08",
   "operations": [
      {
         "debt_key": "1baea8a0-0fca-4f7c-8857-a227d4da72f8",
         "installments": [
            { "installment_key": "ca5741c7-99a2-42e7-92a1-9328a36e4e88" }
         ]
      },
      {
         "debt_key": "2cbfb9b1-1fdb-5f8d-9967-b338e5eb83f9",
         "installments": [
            { "installment_key": "2ef25ed8-7124-44f5-9e3d-1d1a7196166e" }
         ]
      }
   ]
}

Parâmetros do corpo

Campo	Tipo	Descrição	Máx tamanho
amortization_type *	string	Tipo de amortização do lote	Valores do amortization_type em lote
operations *	array	Operações a renegociar	Objeto operations
reference_date	string	Data de referência para cálculo do valor presente (YYYY-MM-DD).	10
discount_percentage	float	Percentual de desconto opcional sobre o valor presente (nível raiz, global).	-
discount_amount	float	Valor de desconto opcional sobre o valor presente (nível raiz, global).	-

Objeto operations

Campo	Tipo	Descrição	Máx tamanho
debt_key *	string	Chave única da operação de crédito (DEBT-KEY)	UUID
installments *	array	Parcelas a renegociar	Objeto installments

Objeto installments

Campo	Tipo	Descrição	Máx tamanho
installment_key *	string	Chave da parcela	UUID

Valores do amortization_type em lote

Valor	Descrição
installment_payment	Pagar parcelas específicas. Cada item de installments[] contém apenas installment_key.
overdue_installment_payment	Pagar parcelas em atraso. Mesma estrutura de installment_payment.
present_amount	Valor presente por parcela. Na simulação, enviar apenas installment_key. No endpoint de proposta, enviar também paid_amount e discount_amount.

Resposta

STATUS

200

Exemplo de corpo de resposta

{
   "batch_proposal_key": "429fd784-e13e-47a1-ad9f-291209e0e621",
   "amortization_type": "installment_payment",
   "payment_amount": 78389.55,
   "discount_percentage": 0,
   "discount_amount": 0,
   "requester_name": "Castello (BNPL)",
   "requester_key": "3e69b448-9afb-4aef-9c0d-0a3059350d80",
   "issuer_name": "Alan Mathison Turing",
   "issuer_document_number": "82744088021",
   "reference_date": "2026-04-08",
   "operations": [
      {
         "requester_key": "3e69b448-9afb-4aef-9c0d-0a3059350d80",
         "contract_number": "TEST00790",
         "payment_amount": 78389.55,
         "discount_amount": 0,
         "affected_installments": [
            {
               "installment_key": "24b5deae-304e-4773-9b25-e42dbd450241",
               "due_date": "2026-05-10",
               "principal_amount": 73107.75,
               "interest_amount": 10580.11,
               "fine_amount": 0,
               "total_amount": 83687.87,
               "present_amount": 78389.55,
               "paid_amount": 78389.55,
               "principal_amortization_payment_amount": 78048.30,
               "prefixed_interest_payment_amount": 341.25,
               "fine_payment_amount": 0,
               "discount_amount": 0
            }
         ],
         "remaining_installments": [
            {
               "installment_key": "2b1d9423-4dab-44b3-bf8c-efc8433176dd",
               "due_date": "2026-06-10",
               "principal_amount": 73096.23,
               "interest_amount": 10591.64,
               "fine_amount": 0,
               "total_amount": 83687.87
            }
         ],
         "debt_key": "388c47fa-6c6c-4d2b-8f00-ccc2d571fcb0"
      }
   ]
}

Renegociação — Proposta em lote

Visão geral

Após simular os valores, crie a proposta em lote. A proposta gera um único meio de pagamento (boleto e/ou Pix) cobrindo todas as operações.

Para amortization_type: present_amount, cada item em operations[].installments[] deve incluir paid_amount e discount_amount (além de installment_key). Para installment_payment / overdue_installment_payment, apenas installment_key é obrigatório.

Requisição

ENDPOINT

/renegotiation/batch_proposal

MÉTODO

POST

Testar no Playground

Corpo da requisição

installment_payment

{
   "amortization_type": "installment_payment",
   "reference_date": "2026-04-08",
   "proposal_due_date": "2026-04-15",
   "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" }
         ]
      },
      {
         "debt_key": "2cbfb9b1-1fdb-5f8d-9967-b338e5eb83f9",
         "installments": [
            { "installment_key": "2ef25ed8-7124-44f5-9e3d-1d1a7196166e" }
         ]
      }
   ]
}

present_amount

{
   "amortization_type": "present_amount",
   "reference_date": "2026-04-08",
   "proposal_due_date": "2026-04-15",
   "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 }
         ]
      }
   ]
}

Parâmetros do corpo

Campo	Tipo	Descrição	Máx tamanho
amortization_type *	string	Tipo de amortização do lote	Valores do amortization_type em lote
payment_type *	string	Tipo de pagamento em lote	Valores do payment_type em lote
operations *	array	Operações a renegociar	Objeto operations
proposal_due_date *	string	Data de vencimento da proposta (YYYY-MM-DD)	10
reference_date *	string	Data de referência (YYYY-MM-DD)	10
request_control_key	string	Chave de idempotência do cliente. Necessária para cancelamento por request_control_key.	50
discount_percentage	float	Percentual de desconto global opcional sobre o valor presente.	-
discount_amount	float	Valor de desconto global opcional sobre o valor presente.	-
payer_document_number	string	CNPJ do pagador (somente dígitos).	14
payer_name	string	Nome do pagador. Obrigatório quando payer_document_number é enviado.	200

Objeto operations

Campo	Tipo	Descrição	Máx tamanho
debt_key *	string	Chave única da operação de crédito (DEBT-KEY)	UUID
installments *	array	Parcelas a renegociar	Objeto installments

Objeto installments

Campo	Tipo	Descrição	Máx tamanho
installment_key *	string	Chave da parcela	UUID
paid_amount	float	Valor pago/alocado na parcela (BRL). Obrigatório quando amortization_type é present_amount.	15,2
discount_amount	float	Desconto em BRL aplicado à parcela. Obrigatório quando amortization_type é present_amount (use 0 se não houver).	15,2

Valores do payment_type em lote

Valor	Descrição
bank_slip	Boleto bancário (também gera Pix).
pix	Somente Pix.
manual	Pagamento manual (sem geração de meio de pagamento).

Valores do amortization_type em lote

Valor	Descrição
installment_payment	Pagar parcelas específicas — cada item em operations[].installments[] requer apenas installment_key.
overdue_installment_payment	Pagar parcelas em atraso — mesma estrutura de installment_payment.
present_amount	Valor presente por parcela — cada item requer installment_key, paid_amount, discount_amount.

Resposta

STATUS

201

Exemplo de corpo de resposta

{
   "batch_proposal_key": "37879d40-c16e-4d7f-a16f-d79d20c50d42",
   "amortization_type": "installment_payment",
   "payment_amount": 78206.27,
   "discount_percentage": 0,
   "discount_amount": 0,
   "requester_name": "Castello (BNPL)",
   "requester_key": "3e69b448-9afb-4aef-9c0d-0a3059350d80",
   "issuer_name": "Alan Mathison Turing",
   "issuer_document_number": "82744088021",
   "reference_date": "2026-04-08",
   "proposal_due_date": "2026-04-15",
   "payment_type": "pix",
   "batch_proposal_status": "pending_payment",
   "request_control_key": "94b31045-c8e7-45be-a88d-2ae25c5df5db",
   "operations": [
      {
         "requester_key": "3e69b448-9afb-4aef-9c0d-0a3059350d80",
         "contract_number": "TEST1570594223",
         "payment_amount": 78206.27,
         "debt_key": "6564493d-75c3-4efe-9f11-82fa5cff9a78",
         "affected_installments": [
            {
               "installment_key": "1162e382-8bd6-4c0b-9111-8390d9794102",
               "due_date": "2026-05-10",
               "principal_amount": 73277.29,
               "interest_amount": 10214.91,
               "fine_amount": 0,
               "total_amount": 83492.20,
               "present_amount": 78206.27,
               "paid_amount": 78206.27,
               "principal_amortization_payment_amount": 78206.27,
               "prefixed_interest_payment_amount": 0,
               "fine_payment_amount": 0,
               "discount_amount": 0
            }
         ],
         "remaining_installments": [
            {
               "installment_key": "58eea645-5682-440d-aa6b-a3b124253684",
               "due_date": "2026-06-10",
               "principal_amount": 72925.33,
               "interest_amount": 10566.87,
               "fine_amount": 0,
               "total_amount": 83492.20
            }
         ]
      }
   ],
   "payment": {
      "digitable_line": null,
      "qr_code_url": "00020126930014br.gov.bcb.pix2571qrcode-h.sandbox.qitech.app/bacen/cobv/426661142f5d4cd9954dcae3725d020d5204000053039865802BR5925QISOCIEDADEDECREDITODIRET6008SaoPaulo61080145200062070503***6304B878",
      "qr_code_key": "42666114-2f5d-4cd9-954d-cae3725d020d",
      "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": "37879d40-c16e-4d7f-a16f-d79d20c50d42"
      }
   }
}

Renegociação — Cancelar proposta em lote

Visão geral

Cancela uma proposta em lote que ainda esteja em estado cancelável. Apenas propostas com batch_proposal_status: "pending_payment" são canceláveis. Quaisquer meios de pagamento associados (boleto, Pix) são invalidados.

Duas rotas estão disponíveis:

• Por batch_proposal_key (UUID retornado em POST /renegotiation/batch_proposal)
• Por request_control_key (chave de idempotência enviada na criação) — útil quando o cliente rastreia as operações pela própria chave

Cancelar por batch_proposal_key

ENDPOINT

/renegotiation/batch_proposal/{batch_proposal_key}

MÉTODO

DELETE

Parâmetros de path

Campo	Tipo	Descrição	Máx tamanho
batch_proposal_key *	string	Chave da proposta retornada em POST /renegotiation/batch_proposal.	UUID

Cancelar por request_control_key

ENDPOINT

/renegotiation/batch_proposal/request_control_key/{request_control_key}

MÉTODO

DELETE

Parâmetros de path

Campo	Tipo	Descrição	Máx tamanho
request_control_key *	string	Chave de idempotência enviada em POST /renegotiation/batch_proposal.	50

Resposta

Ambas as rotas retornam a mesma resposta.

STATUS

204