对接路线图 - BNPL

概述

本文档指导客户完成与 QI Tech 平台的先买后付（BNPL）集成。文档概述了必要步骤，并解答常见问题。

1. 文件查询

可通过以下请求进行文件查询：

请求体上传

ENDPOINT

/document/[document_key]/url

METHOD

GET

路径参数

字段	描述
`document_key`	文件唯一标识符

注意

文件 URL 将在生成后 10 分钟内过期。

Response Body

{
	"document_key": "8a1e62f3-7add-4240-a51d-e0f1a2f421fa",
	"document_url": "expirable_url",
	"signed_document_url": "expirable_url",
	"expiration_datetime": "2024-05-01T01:00:00.000Z"
}

2. 文件上传

要获取债务发行文件的 document_key，您需要通过以下请求上传文件：

请求体上传

ENDPOINT

/upload

METHOD

POST

Response Body

{
  "document_key": "cfbc8469-89ea-4a80-9f64-ba7b1566c68b",
  "document_md5": "cd451103fa512frc98ce684d3896698c"
}

注意

请保存 document_key，查询文件时需要用到此密钥。

API 调用示例

以下为从 URL 上传图片的示例。

Python
Node.js

import jwt
import hashlib
import requests
from requests_toolbelt.multipart.encoder import MultipartEncoder
import json
from datetime import datetime

BASE_URL = "https://api-auth.sandbox.qitech.app"
API_KEY = "4c268c0a-53ff-429b-92b6-47ef98a6d89a" # This key is an example; please use your own key.
CLIENT_PRIVATE_KEY = ''''
-----BEGIN EC PRIVATE KEY-----
MIHbAgEBBEHh1hIeOPE5XNNhn6bxRAmVswsPZ0wZCmzVvP8Tl/LZK9ofVmRVGzll
srU1uezJEyHKYdOHrE2p52xUj+pHzjJvb6AHBgUrgQQAI6GBiQOBhgAEAAofUz1J
hBSOyGHLsnV9Sz0DSWmhl7U+ljqbfa8PKVFWSV3w16I1v2zME5/UzUhHn1gWsjnv
7/ekcLLAQbvqMPNXAfjIhFXLAPzqbB9iCuVua1v0Vgy52rBemOWrJka/Ws2bnKR8
h1N1OxOYeYr6C2jqMygBLktKMAs+282CEiEb4bIv
-----END EC PRIVATE KEY----- 
''' # This key is an example; please use your own key.

def get_document(url):
    try:
        response = requests.get(url)
        return response.content
    except Exception as error:
        print("Error fetching document:", error)
        raise

def upload_document(array_buffer):
    endpointeger= "/upload"
    method = "POST"
    timestamp = datetime.utcnow().strftime("%Y-%m-%dT%H:%M:%S.%f")[:-3] + "Z"
    md5_hash = hashlib.md5(array_buffer).hexdigest()

    jwt_header = {
        "typ": "JWT",
        "alg": "ES512",
    }

    jwt_body = {
        "payload_md5": md5_hash,
        "timestamp": timestamp,
        "method": method,
        "uri": endpoint,
    }

    encoded_header_token = jwt.encode(jwt_body, CLIENT_PRIVATE_KEY, algorithm="ES512", headers=jwt_header)

    signed_header = {
        "Authorization": encoded_header_token,
        "API-CLIENT-KEY": API_KEY,
        "Content-Type": "multipart/form-data",
    }

    url = f"{BASE_URL}{endpoint}"
    multipart_data = MultipartEncoder(
        fields={'file': ('image.jpeg', array_buffer, 'image/jpeg')}
    )
    signed_header['Content-Type'] = multipart_data.content_type

    try:
        response = requests.post(url, headers=signed_header, data=multipart_data)
        response_data = response.json()
        document_key = response_data.get('document_key')
        print(f'Response data is: {response_data} and document_key is: {document_key}')
        return document_key
    except Exception as error:
        print('Error:', error)
        raise


def main():
    file_url = "{FILE_URL}"

    document_buffer = get_document(file_url)

    document_key = upload_document(document_buffer)

    print("document_key is", document_key)

if __name__ == "__main__":
    main()

const jwt = require('jsonwebtoken')
const crypto = require('crypto')
const axios = require('axios')
const FormData = require('form-data')
const fs = require('fs')
const fetch = require('node-fetch')

async function getDocument(url) {
  try {
    const response = await axios.get(url, { responseType: 'arraybuffer' })
    return response.data
  } catch (error) {
    console.error('Error fetching document:', error)
    throw error
  }
}

async function uploadDocument(arrayBuffer) {
  const endpointeger= '/upload'
  const method = 'POST'
  const timestamp = new Date().toISOString()
  const md5_hash = crypto.createHash('md5').update(arrayBuffer).digest('hex')
  const client_private_key = `-----BEGIN EC PRIVATE KEY-----
    MIHbAgEBBEHh1hIeOPE5XNNhn6bxRAmVswsPZ0wZCmzVvP8Tl/LZK9ofVmRVGzll
    srU1uezJEyHKYdOHrE2p52xUj+pHzjJvb6AHBgUrgQQAI6GBiQOBhgAEAAofUz1J
    hBSOyGHLsnV9Sz0DSWmhl7U+ljqbfa8PKVFWSV3w16I1v2zME5/UzUhHn1gWsjnv
    7/ekcLLAQbvqMPNXAfjIhFXLAPzqbB9iCuVua1v0Vgy52rBemOWrJka/Ws2bnKR8
    h1N1OxOYeYr6C2jqMygBLktKMAs+282CEiEb4bIv
    -----END EC PRIVATE KEY-----`; // This key is an example; please use your own key.
  const api_key = '4c268c0a-53ff-429b-92b6-47ef98a6d89a' // This key is an example; please use your own key.

  try {
    const jwt_header = {
      typ: 'JWT',
      alg: 'ES512',
    }

    const jwt_body = {
      payload_md5: md5_hash,
      timestamp: timestamp,
      method: method,
      uri: endpoint,
    }

    const encoded_header_token = jwt.sign(jwt_body, client_private_key, {
      algorithm: 'ES512',
      header: jwt_header,
    })

    const signed_header = {
      AUTHORIZATION: encoded_header_token,
      'API-CLIENT-KEY': api_key,
      'Content-Type': 'multipart/form-data',
    }

    const url = `${base_url}${endpoint}`
    const formData = new FormData()
    formData.append('file', Buffer.from(arrayBuffer), {
      filename: 'image.jpeg',
    })

    fetch(url, {
      method: 'POST',
      headers: signed_header,
      body: formData,
    })
      .then(data => {
        console.log('Response data is: ' + data)

        return data.document_key
      })
      .catch(error => {
        console.log('Error: ' + error)
      })
  } catch (error) {
    console.error('Error:', error)
  }
}

async function main() {
  const fileUrl = '<URL_LINK_TO_DOCUMENT_IMAGE>'
  const documentBuffer = await getDocument(fileUrl)
  const documentKey = await uploadDocument(documentBuffer)

  console.log('Document key is: ' + documentKey)
}

main()

备注：上述示例使用 node-fetch 库进行调用，您也可以使用自己选择的库。重要的是，调用必须使用 POST 方法，Content-Type 请求头设置为 multipart/form-data，请求体必须是包含键名为 file、值为待发送文件二进制数据的 FormData 对象。

警告

'Axios' 库存在一个导致 FormData 发送为空的 bug，相关问题可在 GitHub 仓库中查看。如果在您集成时该问题尚未解决，建议使用 'node-fetch' 库进行此调用。

3. 债务模拟

请求债务模拟

QI Tech 为客户提供在实际发行信贷操作之前模拟其金额的功能。模拟与债务发行请求遵循相同的模式，但无需提供借款人的注册信息和放款账户详情。以下端点是 /debt_simulation 的简化版本，经过高度优化，仅用于计算单一放款选项。

ENDPOINT

/v2/credit_operation/simulation

METHOD

POST

Request Body

{
    "credit_operation_type": "ccb",
    "disbursed_issue_amount": 2800,
    "disbursement_date": "2025-09-24",
    "first_due_date": "2025-10-24",
    "force_installments_on_workdays": true,
    "interest_type": "pre_price_days",
    "issuer_person_type": "natural",
    "monthly_interest_rate": 0.04488,
    "number_of_installments": 12,
    "principal_amortization_month_period": 1
}

请求体字段详情

字段	类型	描述	最大字符数
credit_operation_type*	string	信贷协议类型	信贷操作类型枚举值
disbursed_issue_amount*	float	实际发放给借款人的金额	15,2
disbursement_date*	string	贷款资金可用的具体日期	10
first_due_date*	string	第一期分期付款的到期日	10
force_installments_on_workdays*	boolean	如为 true，确保所有分期付款到期日顺延至下一个工作日	5
interest_type*	string	摊销方法	利息类型枚举值
issuer_person_type*	string	定义发行人是自然人还是法人（企业/公司）	人员类型枚举值
monthly_interest_rate*	float	每月对本金余额收取的百分比利率	10,6
number_of_installments*	integer	分期付款期数	3
principal_amortization_month_period*	integer	分期付款之间的月数	1

债务模拟响应

STATUS

200

Response Body

    {
        "disbursement_date": "2025-09-24",
        "issue_amount": 2821.32,
        "interest_type": "pre_price_days",
        "assignment_amount": 2829.78,
        "base_iof": 10.6,
        "total_iof": 21.32,
        "additional_iof": 10.72,
        "cet": 5.09,
        "annual_cet": 81.39,
        "first_due_date": "2025-10-24",
        "disbursed_amount": 2800,
        "prefixed_interest_rate": {
            "annual_rate": 0.6935459998,
            "daily_rate": 0.0014644728,
            "interest_base": "calendar_days",
            "monthly_rate": 0.04488
        },
        "tax_configuration": {
            "base_rate": 8.2e-05,
            "additional_rate": 0.0038
        },
        "fees": [
            {
                "amount": 0.3,
                "fee_amount": 8.46,
                "amount_type": "percentage",
                "fee_type": "spread",
                "type": "internal"
            }
        ],
        "installments": [
            {
                "due_date": "2025-10-24",
                "amount": 1507.4,
                "due_principal": 2821.32,
                "due_interest": 0,
                "has_interest": true,
                "period": 1,
                "period_workdays": 1.1,
                "calendar_days": 30,
                "workdays": 22,
                "installment_number": 1,
                "period_to_disbursement": 1,
                "prefixed_amount": 126.62083829,
                "period_workdays_to_disbursement": 1.1,
                "calendar_days_to_disbursement": 30,
                "workdays_to_disbursement": 22,
                "tax_amount": 3.39671674,
                "principal_amortization_amount": 1380.77916171
            },
            {
                "due_date": "2025-11-24",
                "amount": 1507.4,
                "due_principal": 1440.54083829,
                "due_interest": 0,
                "has_interest": true,
                "period": 1,
                "period_workdays": 1,
                "calendar_days": 31,
                "workdays": 20,
                "installment_number": 2,
                "period_to_disbursement": 2,
                "prefixed_amount": 66.85916171,
                "period_workdays_to_disbursement": 2.1,
                "calendar_days_to_disbursement": 61,
                "workdays_to_disbursement": 42,
                "tax_amount": 7.20558527,
                "principal_amortization_amount": 1440.54083829
            }
        ]
    }

响应体字段详情

字段	类型	描述
annual_cet	float	以小数表示的年总有效成本
assignment_amount	float	信贷操作的收购价值
cet	float	以小数表示的月总有效成本
fees	object	费用对象 - QI Tech 对操作收取的费用列表
disbursed_amount	float	信贷操作中的放款金额
disbursement_date	string	操作放款日期
installments	array	分期付款对象 - 操作的分期付款信息
interest_type	string	利息类型枚举值 - 摊销方法和利息计算方法
additional_iof	float	对交易本金征收的固定利率税，与信贷操作期限无关
base_iof	float	作为金融操作税计算基础的应税金额或本金价值
total_iof	float	对交易征收的金融操作税总额
issue_amount	float	信贷操作的发行/名义价值
tax_configuration	object	税务配置对象 - IOF 利率值
first_due_date	string	第一期分期付款到期日
prefixed_interest_rate	object	利率对象 - 名义利率

4. 自然人债务发行

此端点通过 opt-in 方式发行债务并处理合同签名。放款在发行后立即自动进行。无需预注册；只需在债务请求时提供借款人详情即可。

请求

ENDPOINT

/signed_debt

METHOD

POST

Request Body

{
    "additional_data": {
        "contract": {
            "contract_number": "TIK11267101100",
            "signed": true,
            "signatures": [
                {
                    "signer": {
                        "name": "Alan Mathison Turing",
                        "phone": {
                            "number": "912345678",
                            "area_code": "11",
                            "country_code": "055"
                        },
                        "email": "alan.turing@email.com",
                        "document_number": "96969879003"
                    },
                    "signature": {
                        "ip_address": "168.211.22.84",
                        "timestamp": "27-10-2025 11:07:15",
                        "signature_file": {
                            "file_url": "http://qitech.com.br/signature.pdf",
                            "file_type": "pdf"
                        },
                        "geolocation": {
                            "long": "-46.63611",
                            "lat": "-23.5475"
                        },
                        "fingerprint_device": null
                    }
                }
            ]
        }
    },
    "financial": {
        "number_of_installments": 2,
        "credit_operation_type": "ccb",
        "interest_type": "pre_price_days",
        "monthly_interest_rate": 0.07,
        "disbursed_amount": 200,
        "fine_configuration": {
            "contract_fine_rate": 0.02,
            "monthly_rate": 0.15,
            "interest_base": "calendar_days"
        },
        "interest_grace_period": 0,
        "disbursement_date": "2026-02-06",
        "first_due_date": "2026-03-06",
        "principal_grace_period": 0
    },
    "disbursement_bank_accounts": [
        {
            "account_digit": "5",
            "document_number": "32402502000135",
            "bank_code": "329",
            "account_number": "00002",
            "percentage_receivable": 100,
            "branch_number": "0001",
            "name": "Accout Name"
        }
    ],
    "requester_identifier_key":"6b558426-6b6c-4c9e-bfb3-5734fe45a651",
    "purchaser_document_number": "32402502000135",
    "borrower": {
        "email": "alan.turing@email.com",
        "document_identification": "494598fd-c226-4332-a500-591ae3884673",
        "document_identification_back": "494598fd-c226-4332-a500-591ae3884673",
        "birth_date": "1990-11-20",
        "person_type": "natural",
        "is_pep":false,
        "profession": "Public server",
        "individual_document_number": "96969879003",
        "address": {
            "city": "São Paulo",
            "neighborhood": "CENTRO",
            "street": "Avenida Feliz",
            "complement": "AP 801",
            "postal_code": "49026100",
            "state": "SP",
            "number": "1000"
        },
        "phone": {
            "country_code": "055",
            "number": "912345678",
            "area_code": "11"
        },
        "mother_name": "MARIA TURING",
        "document_identification_number": "96969879003",
        "name": "Alan Mathison Turing"
    }
}

请求体字段详情

字段	类型	描述	最大字符数
borrower *	object	借款人对象 - 信贷操作的债务人	借款人对象
disbursement_bank_account *	object	操作资金将存入的银行账户技术详情。	放款银行账户对象
financial *	object	包含操作的所有财务详情和计算参数。	财务对象
purchaser_document_number *	string	受让人税务识别码 – 信贷操作的买方（FIDC/应收账款投资基金）。	14
additional_data *	object	受让人税务识别码 – 信贷操作的买方（FIDC/应收账款投资基金）。	附加数据对象

借款人对象

字段	类型	描述	最大字符数
name *	string	借款人全名	100
email	string	借款人电子邮箱地址	254
phone	object	借款人联系电话详情	电话对象
is_pep *	boolean	政治敏感人士（PEP）指示符	5
address *	object	借款人住宅地址详情	地址对象
role_type *	enum	该人员在操作中的角色。默认值：issuer	-
birth_date *	date	借款人出生日期（格式："YYYY-MM-DD"）	10
mother_name *	string	借款人母亲全名	100
nationality	string	借款人国籍	50
person_type *	string	人员分类	7
individual_document_number *	string	借款人税务识别码（CPF）- 仅数字	11
document_identification *	string	已上传身份证件（RG 或 CNH）的 DOCUMENT_KEY	36
document_identification_back	string	已上传身份证件背面的 DOCUMENT_KEY	36

地址对象

字段	类型	描述	最大字符数
city *	string	地址所在城市名称	100
state *	string	州缩写（两个大写字母）	2
number *	string	门牌号	10
street *	string	街道名称	100
complement *	string	地址补充信息（自由文本）	100
postal_code *	string	邮政编码（CEP）- 仅数字	8
neighborhood *	string	街区或地区名称	100

电话对象

字段	类型	描述	最大字符数
number *	string	用户电话号码	9
area_code *	string	两位数区号（例如："11"）	2
country_code *	string	国际拨号代码（例如："055"）	3

放款银行账户对象

字段	类型	描述	最大字符数
name	string	账户持有人全名	50
document_number	string	账户持有人税务识别码（CPF）	11
bank_code *	string	金融机构 COMPE 代码	3
branch_number *	string	支行号码（请勿包含支行验证码！）	4
account_number *	string	账号（请勿包含账户验证码！）	10
account_digit *	string	账户验证码（用零代替字母）	1
account_type	enum	账户类型枚举值 - 银行账户类型	账户类型对象

附加数据对象

字段	类型	描述	最大字符数
contract_number *	string	合同的唯一标识符或参考编号	12
signed *	boolean	表示合同是否已成功签署	5
signatures *	array	数字签名证据对象列表（Opt-in）	-
name *	string	签署人全名	255
document_number *	string	签署人税务识别码（CPF）	11
email *	string	签署人电子邮箱地址	100
area_code *	string	两位数区号（例如："11"）	2
number *	string	用户电话号码	9
country_code *	string	国际拨号代码（例如："055"）	3
ip_address *	string	签署过程中使用的 IP 地址	45
timestamp *	string	签署日期和时间（DD-MM-YYYY HH:mm:ss）	19
file_url *	string	已签署合同文件（PDF）的直接链接	2048
file_type *	string	签名文件格式（例如："pdf"）	4
long *	string	签署位置的地理经度坐标	20
lat *	string	签署位置的地理纬度坐标	20
fingerprint_device	string	使用设备的唯一数字标识符	-

响应

此债务请求的响应将返回还款计划以及一个 DEBT-KEY，即该债务在 QI SCD 中的标识符。

STATUS

201

Response Body

{
    "webhook_type": "debt",
    "key": "a6dbf441-31b0-44df-9bb8-593553de2c45",
    "status": "issued",
    "event_datetime": "2026-02-10 00:01:20",
    "data": {
        "borrower": {
            "name": "Alan Mathison Turing",
            "document_number": "96969879003",
            "related_party_key": "6995ff6e-27c2-47e9-b4bf-640934b56b23"
        },
        "contract": {
            "document_key": null,
            "number": "TIK11267101100",
            "urls": [],
            "signature_information": [
                {
                    "signer_name": "Alan Mathison Turing",
                    "signer_document_number": "96969879003",
                    "signer_role": "issuer",
                    "signer_email": "alan.turing@email.com",
                    "signer_external_key": null,
                    "signature_url": null
                }
            ]
        },
        "requester_identifier_key": "6b558426-6b6c-4c9e-bfb3-5734fe45a651",
        "iof_charge_method": "financed",
        "collaterals": [],
        "contract_fees": [
            {
                "fee_type": "spread",
                "fee_amount": 0.6
            }
        ],
        "external_contract_fees": [],
        "external_contract_fee_amount": 0,
        "net_external_contract_fee_amount": 0,
        "contract_fee_amount": 0.6,
        "issue_amount": 201.49,
        "assignment_amount": 202.09,
        "cet": "7,6600%",
        "annual_cet": "142,5744%",
        "number_of_installments": 2,
        "base_iof": 0.73,
        "additional_iof": 0.76,
        "total_iof": 1.49,
        "ipoc_code": "324025020203196969879003TIK11267101100",
        "prefixed_interest_rate": {
            "annual_rate": 1.252191589,
            "created_at": "2026-02-10T00:01:18",
            "daily_rate": 0.0022578334,
            "interest_base": "calendar_days",
            "monthly_rate": 0.07
        },
        "installments": [
            {
                "accrual_reference_date": null,
                "additional_costs": [],
                "advanced_paid_amount": 0,
                "bank_slip_key": null,
                "business_due_date": "2026-03-06",
                "calendar_days": 28,
                "digitable_line": null,
                "due_date": "2026-03-06",
                "due_interest": 0,
                "due_principal": 201.49,
                "fine_amount": null,
                "has_interest": true,
                "installment_history": [],
                "installment_key": "5c121fac-20f8-4481-b7b6-d0647a0ce524",
                "installment_number": 1,
                "installment_payment": [],
                "installment_status": "created",
                "installment_type": "principal",
                "original_due_principal": 201.49,
                "original_pre_fixed_amount": 13.13403553,
                "original_principal_amortization_amount": 97.92596447,
                "original_total_amount": 111.06,
                "paid_amount": 0,
                "paid_at": null,
                "post_fixed_amount": 0,
                "pre_fixed_amount": 13.13403553,
                "principal_amortization_amount": 97.92596447,
                "qr_code_key": null,
                "qr_code_url": null,
                "renegotiation_proposal_key": null,
                "tax_amount": 0.22483801,
                "total_accrual_amount": null,
                "total_amount": 111.06,
                "total_paid_amount": 0,
                "workdays": 18
            },
            {
                "accrual_reference_date": null,
                "additional_costs": [],
                "advanced_paid_amount": 0,
                "bank_slip_key": null,
                "business_due_date": "2026-04-06",
                "calendar_days": 31,
                "digitable_line": null,
                "due_date": "2026-04-06",
                "due_interest": 0,
                "due_principal": 103.56403553,
                "fine_amount": null,
                "has_interest": true,
                "installment_history": [],
                "installment_key": "a8a21d7a-481e-43ba-b115-fd89253bcde9",
                "installment_number": 2,
                "installment_payment": [],
                "installment_status": "created",
                "installment_type": "principal",
                "original_due_principal": 103.56403553,
                "original_pre_fixed_amount": 7.49596447,
                "original_principal_amortization_amount": 103.56403553,
                "original_total_amount": 111.06,
                "paid_amount": 0,
                "paid_at": null,
                "post_fixed_amount": 0,
                "pre_fixed_amount": 7.49596447,
                "principal_amortization_amount": 103.56403553,
                "qr_code_key": null,
                "qr_code_url": null,
                "renegotiation_proposal_key": null,
                "tax_amount": 0.5010428,
                "total_accrual_amount": null,
                "total_amount": 111.06,
                "total_paid_amount": 0,
                "workdays": 20
            }
        ],
        "total_pre_fixed_amount": 20.63
    }
}

5. Webhooks

成功响应后，您将收到一个包含已签署 CCB 的 webhook，以及一个表示放款成功或失败的 webhook。

签名 webhook

Response Body

{
    "key": "1ebd4a90-2721-4c39-a399-427fa16bca65",
    "status": "signature_finished",
    "webhook_type": "debt",
    "event_datetime": "2025-10-27 17:09:33",
    "signed_contract_url": "https://storage.googleapis.com/sandbox-doc-api/documents/c8b191cb-7b90-4e37-9280-397a597babc1/RAFAELAEBENJAMINFINANCEIRALTDA-ALAN_MATHISON_TURING-CCB-TIK11267101212-20251027170925_signed.pdf"
}

放款 webhook

Response Body

{
    "key": "1ebd4a90-2721-4c39-a399-427fa16bca65",
    "data": {
      "installments": [
        {
          "due_date": "2025-11-27",
          "total_amount": 87.43,
          "installment_key": "e25fb146-0a61-4319-a722-d01b2213d0f9",
          "pre_fixed_amount": 29.26477451,
          "installment_number": 1,
          "principal_amortization_amount": 58.16522549
        },
        {
          "due_date": "2025-12-27",
          "total_amount": 87.43,
          "installment_key": "2557de2b-6df1-4a8a-b46a-59206ece157f",
          "pre_fixed_amount": 20.11446867,
          "installment_number": 2,
          "principal_amortization_amount": 67.31553133
        },
        {
          "due_date": "2026-01-27",
          "total_amount": 87.43,
          "installment_key": "cc503d1d-6387-4a1f-bd78-62b248d02ec8",
          "pre_fixed_amount": 11.07075682,
          "installment_number": 3,
          "principal_amortization_amount": 76.35924318
        }
      ],
      "ted_receipt_list": [],
      "requester_identifier_key": null
    },
    "status": "disbursed",
    "webhook_type": "debt",
    "event_datetime": "2025-10-27 17:10:21"
}

如果债务放款失败或被退回，您将收到取消 webhook。

取消 webhook

Response Body

{
     "webhook_type": "debt",
     "key":"1ebd4a90-2721-4c39-a399-427fa16bca65",
     "event_datetime": "2025-10-27 16:38:59",
    "data": {
        "cancel_reason": "Operacao cancelada manualmente",
        "cancel_reason_enumerator": "manual"
    },
     "status":"canceled"
  }

取消原因

cancel_reason_enumerator	描述
disbursing_error	操作因放款过程中出现错误而取消。
waiting_signature	操作因缺少签名而取消。
pix_max_retry	操作因收款银行无法处理放款而取消。
manual	操作被手动取消。
agencia_conta_invalida	机构号或收款账户号无效。
invalid_account	目标账号不存在或无效。
invalid_document_number	目标账户的 CPF/CNPJ 不正确。
unsupported_transaction	目标账户不支持此类交易。
invalid_ispb	ISPB 号码无效或不存在。
rejected_payment	付款指令被收款银行拒绝。
refund_after_payee_request	收款方申请退款
invalid_account	目标账号不存在或无效。
invalid_document_number	目标账户的 CPF/CNPJ 不正确。
rejected_payment	付款被收款银行拒绝。
blocked_account	目标账户已被冻结。
unsupported_transaction	目标账户不支持此类交易。
amount_too_great	付款/退款金额超过收款目标账户的限额。
invalid_ispb	ISPB 号码无效或不存在。
receiver_error	由于收款方 PSP 出现错误，交易中断。
closed_account	目标账户已注销。
disbursing_hour_closed	放款发生在允许的时间窗口之外。
unregistered_pix_key	PIX 密钥未被使用。
manual	操作被手动取消。
spi_timeout	SPI 超时控制。

6. 取消

放款前取消债务

请求体

ENDPOINT

/debt/DEBT-KEY/cancel

MÉTODO

PATCH

路径参数

字段	类型	描述	最大字符数
`debt_key` *	string	创建信贷操作时返回的债务唯一标识键。	32

响应体

STATUS

200

Response Body

{
  "data": [
    {
      "borrower": {
        "document_number": "68394265057",
        "name": "Xuxa Meneguel"
      },
      "contract_fee_amount": 5.56,
      "installments": [
        {
          "bank_slip_key": null,
          "calendar_days": 57,
          "due_date": "2020-09-30",
          "due_principal": -0.00217819,
          "fine_amount": null,
          "has_interest": true,
          "installment_key": "28eb5907-ed25-4a86-bb9d-b6dc944f13df",
          "installment_number": 1,
          "installment_status": "opened",
          "installment_type": "principal",
          "paid_amount": 0,
          "post_fixed_amount": 0,
          "pre_fixed_amount": 268.75782181,
          "principal_amortization_amount": 1111.9,
          "tax_amount": 0,
          "total_amount": 1380.66,
          "workdays": 40
        }
      ],
      "operation_key": "7986dcc7-4331-478f-af47-adfbdf7f4a36",
      "status": "opened"
    }
  ],
  "pagination": {
    "current_page": 1,
    "next_page": null,
    "rows_per_page": 100,
    "total_pages": 1,
    "total_rows": 55
  }
}

放款后七天内取消债务

请求体

ENDPOINT

/debt/reversal

MÉTODO

POST

Request Body

{
    "contract_number": "0000049343/TW"
}

请求体字段详情

字段	类型	描述	最大字符数
`contract_number` *	string	CCB 的合同编号

响应体

STATUS

200

Response Body

{
  "amount": "2026.93",
  "copy_paste_pix": "00020126930014br.gov.bcb.pix2571qrcode-h.dev.qitech.app/bacen/cobv/dece8d3e-32ce-439e-8204000053039865802BR5925Joao61080150400062070503***63046ECD",
  "expiration_date": "2022-09-28",
  "payer_document_number": "000000000008",
  "payer_name": "Teste",
  "reversal_key": "f98a1b7c-5e3c-4e6f-8887-c7fedfa0d5b5",
  "status": "waiting_payment"
}

7. 债务查询

您也可以在之后查询债务以获取信息或跟踪其状态：

ENDPOINT

/v2/credit_operation/CREDIT-OPERATION-KEY

METHOD

GET

路径参数

字段	类型	描述	最大字符数
`credit_operation_key` *	string	信贷操作密钥。	UUID

响应

STATUS

200

Response Body

{
    "credit_operation_key": "1ebd4a90-2721-4c39-a399-427fa16bca65",
    "issue_amount": 201.84,
    "origin_key": "1ebd4a90-2721-4c39-a399-427fa16bca65",
    "total_iof": 1.84,
    "disbursement_start_date": "2025-10-27",
    "disbursement_end_date": "2025-10-27",
    "issue_date": "2025-10-27",
    "requester_identifier_key": "1ebd4a90-2721-4c39-a399-427fa16bca65",
    "installments": [
        {
            "business_due_date": "2025-11-28",
            "due_date": "2025-11-27",
            "calendar_days": 31,
            "due_interest": 0,
            "due_principal": 201.84,
            "fine_amount": 0,
            "has_interest": true,
            "post_fixed_amount": 0,
            "pre_fixed_amount": 29.26,
            "principal_amortization_amount": 58.17,
            "tax_amount": 0.15,
            "total_amount": 87.43,
            "workdays": 22,
            "accrual_reference_date": null,
            "advanced_paid_amount": 0,
            "bank_slip_key": "524440c0-302b-4553-8211-5cf012f2e718",
            "digitable_line": "32990001031000700326159000000204112780000008743",
            "installment_key": "e25fb146-0a61-4319-a722-d01b2213d0f9",
            "installment_status": "opened",
            "installment_type": "principal",
            "original_due_principal": 201.84,
            "original_pre_fixed_amount": 29.26,
            "original_principal_amortization_amount": 58.17,
            "paid_amount": 0,
            "original_total_amount": 87.43,
            "qr_code_key": "eeb4f5a6-6cba-4901-8113-21c7261b54ac",
            "qr_code_url": "00020126930014br.gov.bcb.pix2571qrcode-h.sandbox.qitech.app/bacen/cobv/eeb4f5a66cba4901811321c7261b54ac5204000053039865802BR5925QISOCIEDADEDECREDITODIRET6008SaoPaulo61080145200062070503***6304D300",
            "renegotiation_proposal_key": null,
            "total_accrual_amount": 0,
            "total_paid_amount": 0,
            "installment_number": 1,
            "paid_at": null,
            "updated_at": "2025-10-27T17:10:21",
            "principal_amortization_payment_amount": 0,
            "prefixed_interest_payment_amount": 0
        },
        {
            "business_due_date": "2025-12-30",
            "due_date": "2025-12-27",
            "calendar_days": 30,
            "due_interest": 0,
            "due_principal": 143.67477451,
            "fine_amount": 0,
            "has_interest": true,
            "post_fixed_amount": 0,
            "pre_fixed_amount": 20.11,
            "principal_amortization_amount": 67.32,
            "tax_amount": 0.34,
            "total_amount": 87.43,
            "workdays": 20,
            "accrual_reference_date": null,
            "advanced_paid_amount": 0,
            "bank_slip_key": "ece5355a-4b51-48af-aa4b-f074b93c9fef",
            "digitable_line": "32990001031000700326160000000202613080000008743",
            "installment_key": "2557de2b-6df1-4a8a-b46a-59206ece157f",
            "installment_status": "opened",
            "installment_type": "principal",
            "original_due_principal": 143.67,
            "original_pre_fixed_amount": 20.11,
            "original_principal_amortization_amount": 67.32,
            "paid_amount": 0,
            "original_total_amount": 87.43,
            "qr_code_key": "98781ab0-318a-43c4-9ce6-fdc22514c540",
            "qr_code_url": "00020126930014br.gov.bcb.pix2571qrcode-h.sandbox.qitech.app/bacen/cobv/98781ab0318a43c49ce6fdc22514c5405204000053039865802BR5925QISOCIEDADEDECREDITODIRET6008SaoPaulo61080145200062070503***63040687",
            "renegotiation_proposal_key": null,
            "total_accrual_amount": 0,
            "total_paid_amount": 0,
            "installment_number": 2,
            "paid_at": null,
            "updated_at": "2025-10-27T17:10:21",
            "principal_amortization_payment_amount": 0,
            "prefixed_interest_payment_amount": 0
        },
        {
            "business_due_date": "2026-01-28",
            "due_date": "2026-01-27",
            "calendar_days": 31,
            "due_interest": 0,
            "due_principal": 76.35924318,
            "fine_amount": 0,
            "has_interest": true,
            "post_fixed_amount": 0,
            "pre_fixed_amount": 11.07,
            "principal_amortization_amount": 76.36,
            "tax_amount": 0.58,
            "total_amount": 87.43,
            "workdays": 21,
            "accrual_reference_date": null,
            "advanced_paid_amount": 0,
            "bank_slip_key": "09888b40-6844-4c8c-a474-f22a94e463a9",
            "digitable_line": "32990001031000700326161000000200313390000008743",
            "installment_key": "cc503d1d-6387-4a1f-bd78-62b248d02ec8",
            "installment_status": "opened",
            "installment_type": "principal",
            "original_due_principal": 76.36,
            "original_pre_fixed_amount": 11.07,
            "original_principal_amortization_amount": 76.36,
            "paid_amount": 0,
            "original_total_amount": 87.43,
            "qr_code_key": "289792ad-3e5a-4308-8e3d-7b75afe0fea5",
            "qr_code_url": "00020126930014br.gov.bcb.pix2571qrcode-h.sandbox.qitech.app/bacen/cobv/289792ad3e5a43088e3d7b75afe0fea55204000053039865802BR5925QISOCIEDADEDECREDITODIRET6008SaoPaulo61080145200062070503***630443CC",
            "renegotiation_proposal_key": null,
            "total_accrual_amount": 0,
            "total_paid_amount": 0,
            "installment_number": 3,
            "paid_at": null,
            "updated_at": "2025-10-27T17:10:21",
            "principal_amortization_payment_amount": 0,
            "prefixed_interest_payment_amount": 0
        }
    ],
    "first_due_date": "2025-11-27",
    "requester_key": "6ca83592-ce8c-42f5-ac0d-5ce182dbe794",
    "original_total_iof": null,
    "contract_number": "TIK11267101212",
    "credit_operation_status_enumerator": "opened",
    "operation_type_enumerator": "structured_operation",
    "disbursement_date": "2025-10-27",
    "issuer_name": "Alan Mathison Turing",
    "issuer_document_number": "96969879003",
    "external_contract_fees": [],
    "cet": 14.75,
    "annual_cet": 421.33,
    "final_disbursement_amount": 200,
    "number_of_installments": 3,
    "disbursement_issue_amount": 200,
    "prefixed_interest_rate": {
        "annual_rate": 3.81790482,
        "daily_rate": 0.0043771607,
        "interest_base": {
            "enumerator": "calendar_days",
            "year_days": 360
        },
        "monthly_rate": 0.14
    },
    "fine_configuration": {
        "contract_fine_rate": 0.02,
        "fine_delay_rate": {
            "annual_rate": 4.35025011,
            "daily_rate": 0.0046696,
            "interest_base": {
                "enumerator": "calendar_days",
                "year_days": 360
            },
            "monthly_rate": 0.15
        }
    },
    "attached_documents": [
        {
            "document_key": "494598fd-c226-4332-a500-591ae3884673",
            "document_url": "https://storage.googleapis.com/sandbox-doc-api/documents/494598fd-c226-4332-a500-591ae3884673/3d684e68e7df4e557d0480d98e26be92.jpg",
            "signature_url": null,
            "document_type": "document_identification",
            "signature_required": false,
            "signed": false
        },
        {
            "document_key": "494598fd-c226-4332-a500-591ae3884673",
            "document_url": "https://storage.googleapis.com/sandbox-doc-api/documents/494598fd-c226-4332-a500-591ae3884673/3d684e68e7df4e557d0480d98e26be92.jpg",
            "signature_url": null,
            "document_type": "document_identification_back",
            "signature_required": false,
            "signed": false
        },
        {
            "document_key": "c8b191cb-7b90-4e37-9280-397a597babc1",
            "document_url": "https://storage.googleapis.com/sandbox-doc-api/documents/c8b191cb-7b90-4e37-9280-397a597babc1/RAFAELAEBENJAMINFINANCEIRALTDA-ALAN_MATHISON_TURING-CCB-TIK11267101212-20251027170925.pdf",
            "signature_url": "https://storage.googleapis.com/sandbox-doc-api/documents/c8b191cb-7b90-4e37-9280-397a597babc1/RAFAELAEBENJAMINFINANCEIRALTDA-ALAN_MATHISON_TURING-CCB-TIK11267101212-20251027170925_signed.pdf",
            "document_type": "ccb_pre_price_days",
            "signature_required": true,
            "signed": true
        }
    ]
}

STATUS

400

Response Body

{
  "data": "{\"title\": \"Bad Request\", \"description\": \"Invalid request body.\", \"translation\": \"Corpo da requisição inválido.\", \"extra_fields\": {}, \"code\": \"LEG000069\"}"
}

8. 转让查询

转让确认 Webhook

此 webhook 用于通知客户转让流程已启动。它提供了跟踪转让所需的基本元数据。

Response Body

{
  "assignment_key": "77997168-5d61-430f-b5ae-08eb3d7b8c0e",
  "term_of_assignment_url": "https://example.com/assignment.pdf",
  "number_of_items": 5,
  "total_amount": 120000.00,
  "reference_date": "2026-02-06"
}

字段	类型	描述	最大长度
assignment_key	string	转让操作的唯一标识符	36
term_of_assignment_url	string	下载转让条款（PDF）的 URL	2048
number_of_items	integer	本次转让包含的信贷操作（条目）总数	5
total_amount	float	转让中所有条目现值之和	15,2
reference_date	string	用于转让计算的基准日期（YYYY-MM-DD）	10

要查询特定转让，客户可以使用转让标识键（assignment_key）对端点执行 GET 请求。

请求体

ENDPOINT

/v2/assignment/[assignment_key]

METHOD

GET

参数

字段	描述
`assignment_key`	转让唯一标识键

响应

STATUS

200

Response Body

{
  "assignment_key": "77997168-5d61-430f-b5ae-08eb3d7b8c0e",
  "creation_datetime": "2023-10-01T12:00:00",
  "reference_date": "2023-10-01",
  "total_amount": 120000,
  "number_of_items": 5,
  "term_of_assignment_url": "https://example.com/assignment.pdf",
  "status": "settled",
  "signable_term_url": "https://example.com/signable_term.pdf"
}

要查询转让中的合同，请使用相同的 assignment_key 对端点执行 GET 请求。

请求体

ENDPOINT

/v2/assignment/[assignment_key]/assignment_items

METHOD

GET

参数

字段	描述
`assignment_key`	转让唯一标识键

响应为包含转让中每个合同信息的分页列表（状态 200）：

响应体

STATUS

200

Response Body

{
    "data": [
        {
            "assignment_item_key": "439b1257-82ac-4741-a416-a4428a9a7327",
            "control_number": "0001",
            "credit_operation_key": "d7f2ba40-30ea-4462-890c-6a99a7d85659",
            "issuer_name": "João Santos",
            "issuer_document_number": "12345678912",
            "issue_amount": 50000,
            "disbursed_amount": 45000,
            "disbursement_date": "2023-01-01",
            "number_of_installments": 12,
            "contract_number": "XXX182938",
            "present_amount": 48000,
            "status": "settled",
            "endorsement_url": "https://example.com/endorsement.pdf",
            "purchaser_document_number": "1234567890001"
        }
    ],
    "pagination": {
        "page": 1,
        "page_size": 10
    }
}

9. 技术规范与枚举值

费用对象

字段	类型	描述
amount	float	费用金额（百分比或绝对值，取决于 amount_type 字段提供的值）
amount_type	enum	费用值单位
fee_amount	float	操作中收取费用的绝对值
fee_type	string	操作中收取的费用类型
type	string	操作中收取费用的来源

分期付款对象

字段	类型	描述
calendar_days	integer	分期付款之间的自然日天数
due_date	string	以自然日计的分期付款到期日
due_principal	float	分期付款到期日前未偿还的本金余额
has_interest	boolean	true - 如为 true，该分期付款适用利息
installment_number	integer	分期付款编号
prefixed_amount	float	该分期付款支付的固定利息金额
principal_amortization_amount	float	该分期付款支付的本金金额
tax_amount	float	分期付款的基础 IOF 金额
amount	float	分期付款总金额
due_interest	float	分期付款到期日前未偿还的利息
period	float	分期付款期间
period_workdays	float	以工作日计的分期付款期间
period_to_disbursement	float	距放款的期间
period_workdays_to_disbursement	float	距放款的工作日数
calendar_days_to_disbursement	integer	距放款的自然日天数
workdays	integer	分期付款之间的工作日数
workdays_to_disbursement	integer	距放款的工作日数

利率对象

字段	描述
annual_rate	以小数表示的年固定/浮动利率
daily_rate	以小数表示的日固定/浮动利率
interest_base	利息基准枚举值 - 利息计算基准
monthly_rate	以小数表示的月固定/浮动利率

税务配置对象

字段	描述
base_rate	基础 IOF 利率值
additional_rate	附加 IOF 利率值

枚举值

人员类型枚举值

枚举值	描述
legal	法人
natural	自然人

账户类型枚举值

枚举值	描述
checking_account	活期账户

金额类型枚举值

枚举值	描述
absolute	绝对值
percentage	百分比值

利息类型枚举值

枚举值	描述
pre_price_days	价格摊销法（等额分期），以日为单位计算固定利率利息
pre_price	价格摊销法（等额分期），以 30 天为周期计算固定利率利息

信贷操作类型枚举值

枚举值	描述
ccb	银行信用票据

利息基准枚举值

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

费用类型枚举值

每种费用类型必须事先由 QI Tech 启用和配置

枚举值	描述
spread	包含在信贷操作收购价值中的溢价
spread_ted_fee	TED 转账费的溢价

来源类型枚举值

每种费用类型必须事先由 QI Tech 启用和配置

枚举值	描述
internal	内部费用
external	外部费用

概述​

1. 文件查询​

请求体上传​

路径参数​

2. 文件上传​

请求体上传​

API 调用示例​

3. 债务模拟​

请求债务模拟​

请求体字段详情​

债务模拟响应​

响应体字段详情​

4. 自然人债务发行​

请求​

请求体字段详情​

借款人对象​

地址对象​

电话对象​

放款银行账户对象​

附加数据对象​

响应​

5. Webhooks​

签名 webhook​

放款 webhook​

取消 webhook​

6. 取消​

放款前取消债务​

请求体​

路径参数​

响应体​

放款后七天内取消债务​

请求体​

请求体字段详情​

响应体​

7. 债务查询​

路径参数​

响应​

8. 转让查询​

转让确认 Webhook​

请求体​

参数​

响应​

请求体​

参数​

响应体​

9. 技术规范与枚举值​

费用对象​

分期付款对象​

利率对象​

税务配置对象​

枚举值​

人员类型枚举值​

账户类型枚举值​

金额类型枚举值​

利息类型枚举值​

信贷操作类型枚举值​

利息基准枚举值​

费用类型枚举值​

来源类型枚举值​

概述

1. 文件查询

请求体上传

路径参数

2. 文件上传

请求体上传

API 调用示例

3. 债务模拟

请求债务模拟

请求体字段详情

债务模拟响应

响应体字段详情

4. 自然人债务发行

请求

请求体字段详情

借款人对象

地址对象

电话对象

放款银行账户对象

附加数据对象

响应

5. Webhooks

签名 webhook

放款 webhook

取消 webhook

6. 取消

放款前取消债务

请求体

路径参数

响应体

放款后七天内取消债务

请求体

请求体字段详情

响应体

7. 债务查询

路径参数

响应

8. 转让查询

转让确认 Webhook

请求体

参数

响应

请求体

参数

响应体

9. 技术规范与枚举值

费用对象

分期付款对象

利率对象

税务配置对象

枚举值

人员类型枚举值

账户类型枚举值

金额类型枚举值

利息类型枚举值

信贷操作类型枚举值

利息基准枚举值

费用类型枚举值

来源类型枚举值