单张 Boleto 发行（标准）

重要

要注册 bolePix，必须在将要注册 Boleto 的账户中存在有效的随机 Pix 密钥。

在标准 Boleto 注册流程中，若请求成功，响应将返回状态为 accepted 的 Boleto（Boleto 已被 QI Tech 接受）。Nuclea/CIP 确认或拒绝后，Boleto 将转为 registered 或 rejected 状态。

注意！

由于这是异步注册，当 Boleto 状态从 accepted 变更为 registered 或 rejected 时，申请方将通过 Webhook 收到通知。

Request

ENDPOINT

/account/ACCOUNT_KEY/requester_profile/REQUESTER_PROFILE_KEY/bank_slip

MÉTODO

POST

路径参数

字段	类型	描述	字符数
`account_key`	uuidv4	账户唯一标识密钥，格式为 uuid v4	36
`requester_profile_key`	uuidv4	钱包唯一标识密钥，格式为 uuid v4	36

Request Body

{
  "request_control_key": "0d496b4d-01f6-48cd-8ec9-9ead1e43f156",
  "our_number": 123456789,
  "document_number": "DOC4561237",
  "amount": 5000.00,
  "expiration": "2025-01-01",
  "bank_teller_instructions": "Confirm payment",
  "protest_data": {"days_to_protest": 7},
  "bankruptcy_protest_data": {"days_to_bankruptcy_protest": 14},
  "max_payment_days": 45,
  "fine_data": {"fine_type": "absolute", "fine_amount": 100.00, "days_to_fine": 10},
  "interest_data": {
    "interest_type": "workdays_daily_amount",
    "interest_amount": 10.00,
    "days_to_interest": 2,
  },
  "financial_instrument_type": "digital_commercial_invoice",
  "write_off_data": {"days_to_write_off": 365},
  "rebate_amount": 200.00,
  "discounts_data": [
    {
      "discount_amount": 50.00,
      "discount_number": 1,
      "discount_type": "absolute",
      "discount_limit_date": "2024-12-01",
    }
  ],
  "payer_data": {
    "name": "Global Tech",
    "contact": {
      "email": "finance@globaltech.com",
      "phone": {"country_code": "055", "area_code": "11", "number": "987654321"},
    },
    "address": {
      "street": "101 High St.",
      "neighborhood": "Tech Park",
      "number": "202",
      "postal_code": "01001000",
      "city": "Innovation City",
      "state": "SP",
      "complement": "Building A",
    },
    "document_number": "12345678000195",
    "person_type": "legal",
  },
  "guarantor_data": {
    "name": "Jane Doe",
    "contact": {
      "email": "jane.doe@qitech.com.br",
      "phone": {"country_code": "055", "area_code": "11", "number": "999999999"},
    },
    "address": {
      "street": "202 Elm St.",
      "neighborhood": "Quiet Neighborhood",
      "number": "303",
      "postal_code": "01001000",
      "city": "Peaceful Town",
      "state": "RJ",
      "complement": "House 1",
    },
    "document_number": "23456789012",
    "person_type": "natural",
  },
  "pix_key": "4d25d8fc-0074-42bb-b0a4-dd12b1cd0e98",
  "notification": {
    "document_number": "12345678000195",
    "name": "Global Tech",
    "email": "finance@globaltech.com",
    "phone": {"country_code": "055", "area_code": "11", "number": "987654321"},
    "send_2_way": true,
    "send_before_due_date": false,
    "send_after_due_date": false,
    "send_on_protest": false
  },
  "split_payment_data": {
    "beneficiary_settlement_percentage": 70,
    "split_payment_rules": [
      {
        "percentage": 20,
        "document_number": "12345678901",
        "account_owner_name": "John Smith",
        "account_number": "1234567",
        "account_digit": "8"
      },
      {
        "percentage": 10,
        "document_number": "10987654321",
        "account_owner_name": "Mary Johnson",
        "account_number": "7654321",
        "account_digit": "0"
      }
    ]
  }
}

请求体

字段	类型	描述	字符数
`request_control_key` *	uuidv4	客户请求唯一标识密钥，格式为 uuid v4	36
`our_number`	integer	Boleto 在钱包中的唯一识别编号，可由客户提供，若未提供则由 QI Tech 自动生成	11
`document_number`	string	Boleto 识别编号，可为电子发票编号	10
`participant_control_number`	string	参与方控制号码	25
`amount` *	float	Boleto 基准金额	-
`expiration` *	string	到期日	10
`bank_teller_instructions`	string	给付款方的备注。最多接受 320 个字符，分布在最多 7 行中。每行最多 90 个字符，若超过则自动换行	320
`rebate_amount`	float	Boleto 减免金额，将在基准金额之上应用	-
`max_payment_days`	integer	Boleto 到期后可供支付的最大自然日数（最多 365 天）	-
`financial_instrument_type`	string	Boleto 类型	financial_instrument_type 枚举值
`partial_payment_data`	object	部分支付配置	partial_payment_data 对象
`write_off_data`	object	核销配置	write_off_data 对象
`protest_data`	object	抗议配置	protest_data 对象
`bankruptcy_protest_data`	object	破产抗议配置	bankruptcy_protest_data 对象
`fine_data`	object	罚款配置	fine_data 对象
`interest_data`	object	利息配置	interest_data 对象
`discounts_data`	object array	折扣配置	discount 对象
`payer_data` *	object	付款方数据	payer_data 对象
`guarantor_data`	object	担保人数据	guarantor_data 对象
`pix_key`	uuidv4	随机类型 Pix 密钥	36
`notification`	object	付款方通知配置	notification 对象
`split_payment_data`	object	Boleto 的信用分账（分账支付）配置	split_payment_data 对象

BolePix

若在请求中发送可选参数 pix_key，将生成 bolePix。bolePix 是一种付款与 Pix QR Code 绑定的 Boleto。付款方既可通过 Boleto 的可打印行付款，也可扫描关联的 Pix QR Code 付款。若通过 QR Code 付款，资金即时到账，而相关的银行回执和 Webhook 将与普通 Boleto 一样生成。

重要提示： 要注册 bolePix，必须在将要注册 Boleto 的账户中存在有效的随机 Pix 密钥。

钱包默认配置

若请求中未发送 max_payment_days、write_off_data、protest_data、bankruptcy_protest_data、fine_data、interest_data 和 pix_key 字段，且钱包中存在默认配置，则发行时将使用这些默认配置。

限制和约束

部分支付 Boleto： 不允许通过 Pix QR Code 付款。因此，不允许在注册时发送 pix_key，也不允许为钱包设置 bolePix 生成的默认配置。
信用卡 Boleto： 不需要也不允许发送减免、折扣、罚款和利息信息。此类 Boleto 即使在到期后也可部分支付，当前账单不产生利息、罚款、折扣或减免。可发送 amount = 0。

重要提示： credit_card 类型的 Boleto 必须支持部分支付，若未发送 financial_instrument_type 字段，默认值为 digital_commercial_invoice。

钱包建议

标准 Boleto 钱包： 保持罚款、利息和抗议的默认配置
部分支付 Boleto 钱包： 无 Pix 配置，并设置部分支付规则
信用卡 Boleto 钱包： 无罚款、利息、折扣或减免配置

创建专用钱包可确保每种类型 Boleto 的默认配置适当，并避免业务规则冲突。

状态机

部分支付 Boleto 的状态机有所不同。详情请参阅**简介**。

financial_instrument_type 枚举值

枚举值	描述
digital_commercial_invoice	DMI 商业发票指定复本
credit_card	信用卡
check	支票
digital_commercial	DM 商业复本
digital_service_invoice	服务复本
digital_service_invoice_indication	DSI 服务复本指定
digital_rural_invoice	DR 农村复本
bill_of_exchange	LC 汇票
commercial_credit_note	NCC 商业信贷票据
export_credit_note	NCE 出口信贷票据
industrial_credit_note	NCI 工业信贷票据
rural_credit_note	NCR 农村信贷票据
promissory_note	NP 本票
rural_promissory_note	NPR 农村本票
mercantile_triplicate	TM 商业三联单
service_triplicate	TS 服务三联单
insurance_note	NS 保险票据
receipt	RC 收据
printed_bank_slip	FAT 票据
debit_note	ND 借记票据
insurance_policy	AP 保险单
school_monthly_fee	ME 学费月付款
consortium_installment	PC 联合体分期付款
invoice	NF 发票
debt_document	DD 债务文件
rural_product_certificate	农村产品证书
warrant	权证
state_active_debt	州活跃债务
municipal_active_debt	市活跃债务
federal_active_debt	联邦活跃债务
condominium_charges	公寓费用
proposal_bank_slip	提案 Boleto
deposit_and_contribution_bank_slip	存款和认购 Boleto
others	其他

split_payment_data 对象

用于配置 Boleto 的信用分账（分账支付），将结算金额在 Boleto 受益人和最多 10 个额外账户之间分配。目标账户必须为开通状态并已在 QI Tech 注册，且各项百分比之和（受益人 + 规则）必须正好等于 100。

字段	类型	描述	字符数
`beneficiary_settlement_percentage` *	float	分配给 Boleto 受益人的结算金额百分比，取值范围 0 至 100	-
`beneficiary_max_amount`	float	受益人在结算时可获得的最大金额。当付款金额超过此限额时，超出部分将全部分配给 `split_payment_rules` 数组中的第一条规则。取值大于 0 且不大于 Boleto 金额	-
`split_payment_rules` *	object array	分账规则列表。最少 1 条，最多 10 条	split_payment_rule 对象

split_payment_rule 对象

字段	类型	描述	字符数
`percentage` *	float	分配给该账户的结算金额百分比，取值范围 0 至 100。当此规则专门用于接收 `beneficiary_max_amount` 之上的超出部分时，请使用 `0`	-
`document_number` *	string	目标账户持有人的 CPF/CNPJ	11 或 14
`account_owner_name` *	string	目标账户持有人姓名	100
`account_number` *	string	目标账户号	20
`account_digit` *	string	目标账户校验位	2

注意！

beneficiary_settlement_percentage 与 split_payment_rules 中各项百分比之和必须正好等于 100。
document_number 在各规则之间必须唯一，且不得与受益人相同。
分账适用于 Boleto 的所有结算流程（SILOC、STR、公证处和 Pix QR Code）。
提供 beneficiary_max_amount 时，必须大于 0 且不大于 Boleto 金额。当任一规则的 percentage = 0 时，此字段必填。
每张 Boleto 仅允许一条规则的 percentage = 0（即超出部分的接收方）。
发行后，只要 Boleto 处于 registered 状态且尚未支付，可通过信用分账更新接口更新规则。

用例：将利息/滞纳金导向单独账户

若希望受益人始终收到 Boleto 面值，并由不同账户接收逾期付款产生的利息/滞纳金，请配置 beneficiary_settlement_percentage = 100 + beneficiary_max_amount = <面值> + 一条 percentage = 0 的规则，指向超出部分的接收账户。完整说明请参见 信用分账更新。

partial_payment_data 对象

字段	类型	描述	字符数
`partial_payment_minimum_type` *	string	部分支付最小金额类型	partial_payment_type 枚举值
`partial_payment_minimum_percentage`	float	允许的最小部分支付百分比	-
`partial_payment_minimum_amount`	float	允许的最小部分支付金额	-
`partial_payment_maximum_type`	string	部分支付最大金额类型	partial_payment_type 枚举值
`partial_payment_maximum_percentage`	float	允许的最大部分支付百分比	-
`partial_payment_maximum_amount`	float	允许的最大部分支付金额	-
`partial_payment_quantity` *	integer	允许的部分支付次数	-

注意！

根据 partial_payment_minimum_type 和 partial_payment_maximum_type 字段发送的值，需要相应发送对应的金额或百分比字段。

partial_payment_type 枚举值

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

write_off_data 对象

字段	类型	描述	字符数
`days_to_write_off` *	integer	Boleto 到期后自动核销的天数	-

protest_data 对象

字段	类型	描述	字符数
`days_to_protest` *	integer	Boleto 到期后自动抗议的天数	-

bankruptcy_protest_data 对象

字段	类型	描述	字符数
`days_to_bankruptcy_protest` *	integer	Boleto 到期后自动破产抗议的天数	-

fine_data 对象

选项 1：绝对值罚款（fine_type=absolute）

字段	类型	描述	字符数
`fine_type` *	string	罚款类型	fine_type 枚举值
`fine_amount` *	float	罚款绝对值	-
`days_to_fine` *	integer	到期后开始收取罚款的天数	-

选项 2：百分比罚款（fine_type=percentage）

字段	类型	描述	字符数
`fine_type` *	string	罚款类型	fine_type 枚举值
`fine_percentage` *	integer	罚款百分比，1 至 100	-
`days_to_fine` *	integer	到期后开始收取罚款的天数	-

fine_type 枚举值

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

interest_data 对象

选项 1：绝对值利息

字段	类型	描述	字符数
`interest_type` *	string	利息类型	interest_type 枚举值
`interest_amount` *	float	每单位时间（工作日或自然日）收取的利息金额	-
`days_to_interest` *	integer	到期后开始收取利息的天数	-

选项 2：百分比利息

字段	类型	描述	字符数
`interest_type` *	string	利息类型	interest_type 枚举值
`interest_percentage` *	integer	每单位时间（工作日或自然日）收取的利息百分比	-
`days_to_interest` *	integer	到期后开始收取利息的天数	-

interest_type 枚举值

枚举值	描述
calendar_days_daily_amount	按自然日计算的每日金额
workdays_daily_amount	按工作日计算的每日金额
calendar_days_monthly_percentage	按自然日计算的月利率百分比

discount 对象

选项 1：绝对值折扣

字段	类型	描述	字符数
`discount_amount` *	float	每单位时间的绝对折扣金额	-
`discount_number` *	integer	折扣编号	-
`discount_type` *	string	折扣类型（绝对值）	discount_type 枚举值
`discount_limit_date` *	string	折扣截止日期	10

选项 2：百分比折扣

字段	类型	描述	字符数
`discount_percentage` *	float	每单位时间的折扣百分比	-
`discount_number` *	integer	折扣编号	-
`discount_type` *	string	折扣类型（百分比）	discount_type 枚举值
`discount_limit_date` *	string	折扣截止日期	10

注意！

一张 Boleto 最多可有三个折扣，且所有折扣必须为同一类型，折扣编号必须从 1 开始按递增顺序编号。

discount_type 枚举值

枚举值	描述
absolute	固定金额
anticipation_calendar_days_daily_amount	按自然日计算的提前还款每日折扣金额
anticipation_workdays_daily_amount	按工作日计算的提前还款每日折扣金额
percentage	固定百分比
anticipation_calendar_days_daily_percentage	按自然日计算的提前还款月折扣百分比
anticipation_workdays_daily_percentage	按工作日计算的提前还款年折扣百分比

payer_data 和 guarantor_data 对象

字段	类型	描述	字符数
`name` *	string	全名	100
`document_number` *	string	证件号码（CPF/CNPJ）	11 或 14
`person_type` *	string	人员类型	person_type 枚举值
`contact`	object	联系信息	contact 对象
`address`	object	地址	address 对象

person_type 枚举值

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

contact 对象

字段	类型	描述	字符数
`email`	string	联系邮箱	320
`phone`	object	联系电话	phone 对象

phone 对象

字段	类型	描述	字符数
`country_code` *	string	国际区号（DDI）	3
`area_code` *	string	地区区号（DDD）	2
`number` *	string	电话号码	9

address 对象

字段	类型	描述	字符数
`street` *	string	街道	500
`number` *	string	门牌号	6
`complement`	string	补充	500
`neighborhood` *	string	社区	100
`postal_code` *	string	邮编	8
`city` *	string	城市	100
`state` *	string	州（UF）	state 枚举值

state 枚举值

枚举值	描述
AC	Acre
AL	Alagoas
AM	Amazonas
AP	Amapá
BA	Bahia
CE	Ceará
DF	Distrito Federal
ES	Espírito Santo
GO	Goiás
MA	Maranhão
MG	Minas Gerais
MS	Mato Grosso do Sul
MT	Mato Grosso
PA	Pará
PB	Paraíba
PE	Pernambuco
PI	Piauí
PR	Paraná
RJ	Rio de Janeiro
RN	Rio Grande do Norte
RO	Rondônia
RR	Roraima
RS	Rio Grande do Sul
SC	Santa Catarina
SE	Sergipe
SP	São Paulo
TO	Tocantins
EX	其他

notification 对象

字段	类型	描述	字符数
`document_number` *	string	接收通知者的证件号码（CPF/CNPJ）	11 或 14
`name` *	string	接收通知者姓名	100
`email`	string	通知发送邮箱	320
`phone`	object	通知发送联系电话	phone 对象
`send_2_way` *	boolean	发送副本	-
`send_before_due_date` *	boolean	在到期日前向付款方发送通知	-
`send_after_due_date` *	boolean	Boleto 到期时向付款方发送通知	-
`send_on_protest` *	boolean	进入抗议流程时发送通知	-

Response

STATUS

202

Response Body

{
  "request_control_key": "0d496b4d-01f6-48cd-8ec9-9ead1e43f156",
  "bank_slip_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
  "bank_slip_status": "accepted",
  "our_number": 67215548222,
  "barcode": "32995995900000892811606496721554822228569790",
  "digitable_line": "32991606429672155482022285697904599590000089281",
  "qr_code_data": {
    "qr_code_key": "a92b180a-4aa5-47c2-8a71-4e7bbb074410",
    "pix_key": "4d25d8fc-0074-42bb-b0a4-dd12b1cd0e98",
    "receiver_conciliation_id": "01GVGV9NXBCY287Z6CJ4S0ENW9",
    "url": "00020126830014br.gov.bcb.pix2561qrcode.qitech.app/bacen/cobv/58fd5103a8e64bbbab2fd49b0bd580145204000053039865802BR5925GONNFUNDODEINVESTIMENTOEM6012RiodeJaneiro6107226401262070503***6304EA0D",
    "image": "<base64 encoded QR code image>"
  }
}

响应体参数

字段	类型	描述	字符数
`request_control_key` *	uuidv4	客户请求唯一标识密钥，格式为 uuid v4	36
`bank_slip_key` *	uuidv4	Boleto 唯一标识密钥，格式为 uuid v4	36
`bank_slip_status` *	string	Boleto 状态	bank_slip_status 枚举值
`our_number` *	integer	Boleto 在钱包中的唯一识别编号	11
`barcode` *	string	Boleto 条形码	44
`digitable_line` *	string	Boleto 可打印行	47
`qr_code_data`	object	QR Code 数据	qr_code_data 对象
`created_at` *	string	事件创建日期，ISO 格式（UTC - "YYYY-MM-DDTHH:MM:SSZ"）	20

bank_slip_status 枚举值

枚举值	描述
accepted	Boleto 已接受但尚未注册

qr_code_data 对象

字段	类型	描述	字符数
`qr_code_key`	uuidv4	QR Code 唯一标识密钥	36
`pix_key`	uuidv4	与 QR Code 关联的 PIX 密钥	36
`receiver_conciliation_id`	uuidv4	QR Code 对账标识符	36
`url`	string	QR Code 的 URL（Pix 复制粘贴）	-
`image`	string	QR Code URL 的 base64 编码图片	-

错误响应

STATUS

4xx

Response Body: 错误

{
  "title": "titulo",
  "description": "description in English",
  "translation": "descrição em portugues",
  "code": "codigo",
  "extra_fields": {}
}

HTTP 状态码 `status`	QI 代码 `code`	标题 `title`	英文描述 `description`	葡语描述 `translation`
400	QIT000001	Bad Request	Schema Error	Schema Inválido
404	BKS000004	Not Found	Pix key not found: `{pix_key}`	Chave pix não encontrada: `{pix_key}`
403	BKS000005	Forbidden	User is not allowed to do this action	Usuário não tem autorização para fazer essa ação
404	BKS000006	Not Found	The source account key was not found.	A chave da conta de origem não foi encontrada.
400	BKS000007	Bad Request	It was not possible to consult the source account at this time. Please try again in a few minutes.	Não foi possível consultar a conta de origem neste momento. Por favor, tente novamente em alguns minutos.
400	BKS000008	Bad Request	The source account is closed.	A conta de origem está fechada.
400	BKS000009	Bad Request	The source account is blocked.	A conta de origem está bloqueada.
403	BKS000010	Forbidden	The pix key owner does not match the account owner.	O proprietário da chave pix não corresponde ao proprietário da conta.
404	BKS000013	Not Found	Requester profile not found	Carteira não encontrada
409	BKS000014	Conflict	Request control key already sent or duplicated sent: `{request_control_key}`	Chave de controle da requisição já utilizada ou enviada duplicada: `{request_control_key}`
400	BKS000016	Bad Request	Expiration date must be greater than the current date and have a maximum of 3650 days from the current date.	A data de vencimento deve ser maior que a data atual e possuir no máximo 3650 dias corridos a partir da data atual.
409	BKS000017	Conflict	Our number already used or duplicated sent: `{our_number}`	Nosso número já utilizado ou enviado duplicado: `{our_number}`
400	BKS000018	Bad Request	The discount dates must be less than the expiration date and increasing.	A data dos descontos devem ser menores que a de expiração e crescentes.
400	BKS000019	Bad Request	Payer address is required for protest.	Endereço do pagador é obrigatório para protesto.
500	BKS000021	Internal Server Error	Error while trying to generate QR Code.	Erro ao tentar gerar QR Code de pagamento.
400	BKS000022	Bad Request	Requester profile is not opened.	Carteira não está aberta.
400	BKS000026	Bad Request	Guarantor address is required for protest.	Endereço do sacador é obrigatório para protesto.
404	BKS000028	Not Found	Notary office attended region not found for postal code: `{postal_code}`	Região de cartório não encontrada para o CEP: `{postal_code}`
400	BKS000043	Bad Request	Invalid discount numbering. Discounts must be numbered in ascending order and start on 1.	Numeração dos descontos inválida. Os descontos devem ser numerados em ordem crescente e começar em 1.
400	BKS000045	Bad Request	Rebate amount can not be equal or greater than the bank slip amount.	O valor do rebate não pode ser igual ou maior do que o valor do boleto.
400	BKS000047	Bad Request	It was not possible to consult the sent pix key at this time. Please try again in a few minutes.	Não foi possível consultar a chave pix enviada no momento. Por favor, tente novamente em alguns minutos.
400	BKS000125	Bad Request	Partial payment data is required for this bank slip species type.	Os dados de pagamento parcial são obrigatórios para o tipo de boleto fornecido.
400	BKS000128	Bad Request	QR code payment is not allowed for partial payment.	Pagamento via QR code não é permitido para pagamento parcial.
400	BKS000131	Bad Request	Rebate amount is not allowed for this bank slip species type.	O valor de abatimento não é permitido para o tipo de boleto fornecido.
400	BKS000132	Bad Request	Discount data is not allowed for this bank slip species type.	Os dados de desconto não são permitidos para o tipo de boleto fornecido.
400	BKS000133	Bad Request	Fine data is not allowed for this bank slip species type.	Os dados de multa não são permitidos para o tipo de boleto fornecido.
400	BKS000134	Bad Request	Interest data is not allowed for this bank slip species type.	Os dados de juros não são permitidos para o tipo de boleto fornecido.
400	BKS000136	Bad Request	Only credit card financial instrument type can have zero amount.	Apenas o tipo de instrumento financeiro cartão de crédito pode ter valor zero.

Request​

路径参数​

请求体​

financial_instrument_type 枚举值​

split_payment_data 对象​

split_payment_rule 对象​

partial_payment_data 对象​

partial_payment_type 枚举值​

write_off_data 对象​

protest_data 对象​

bankruptcy_protest_data 对象​

fine_data 对象​

fine_type 枚举值​

interest_data 对象​

interest_type 枚举值​

discount 对象​

discount_type 枚举值​

payer_data 和 guarantor_data 对象​

person_type 枚举值​

contact 对象​

phone 对象​

address 对象​

state 枚举值​

notification 对象​

Response​

响应体参数​

bank_slip_status 枚举值​

qr_code_data 对象​

错误响应​