单张 Boleto 发行（即时）

重要

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

对于即时注册单张 Boleto，创建请求的响应（同步响应）将直接返回已注册（或被拒绝）的 Boleto。Nuclea/CIP 对 Boleto 注册的确认/拒绝时间已包含在此端点的响应时间内。

Request

ENDPOINT

/account/ACCOUNT_KEY/requester_profile/REQUESTER_PROFILE_KEY/bank_slip/instant

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": "06797774-e050-419e-a91a-c64c919b52c7",
  "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
  }
}

请求体参数

字段	类型	描述	字符数
`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

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 字段，且钱包中存在默认配置（即 requester_profile 的 configuration_data 中分别有 max_payment_days、write_off_settings、protest_settings、bankruptcy_protest_settings、fine_settings、interest_settings 和 qr_code_settings），则发行时将使用这些默认配置。

限制和约束

部分支付 Boleto： 不允许通过 Pix QR Code 付款。因此，不允许在注册时发送 pix_key，也不允许为钱包设置 bolePix 生成的默认配置。
信用卡 Boleto： 不需要也不允许发送减免、折扣、罚款和利息信息。这是因为市场惯例中，许多金融机构不接受包含这些信息的信用卡 Boleto 付款。钱包也不能将这些配置设为默认值。因此，此类 Boleto 即使在到期后也可部分支付，当前账单不产生利息、罚款、折扣或减免。若要应用这些值，需要在下一账单中包含，可通过 Boleto 的金额编辑事件或发行包含这些值的新 Boleto 来实现。此类 Boleto 可发送 amount = 0。

重要提示： credit_card 类型的 Boleto 必须支持部分支付，因此需要提供 partial_payment_data 信息或在钱包中设置此默认配置。若未发送 financial_instrument_type 字段，默认值为 digital_commercial_invoice。

钱包建议

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

创建专用钱包可确保每种类型 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	其他

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_minimum_amount 或 partial_payment_minimum_percentage，以及 partial_payment_maximum_amount 或 partial_payment_maximum_percentage。

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=calendar_days_daily_amount 或 interest_type=workdays_daily_amount）

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

选项 2：百分比利息（interest_type=calendar_days_monthly_percentage）

字段	类型	描述	字符数
`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 最多可有三个折扣，且所有折扣必须为同一类型，即具有相同的 discount_type。折扣编号必须从 1 开始，按递增顺序编号，最大到 3。

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

201

Response Body: 已注册 Boleto

{
  "request_control_key": "6e290347-330d-4b3a-8ebb-2ac217ad6eb3",
  "bank_slip_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
  "bank_slip_status": "registered",
  "our_number": 92580722204,
  "barcode": "32998995900000892812147469258072220406456140",
  "digitable_line": "32992147466925807222704064561402899590000089281",
  "qr_code_data": {
    "qr_code_key": "bc5cb30c-8f98-4273-b405-3546da1d8d7a",
    "pix_key": "06797774-e050-419e-a91a-c64c919b52c7",
    "receiver_conciliation_id": "01GVGV9NXBCY287Z6CJ4S0ENW9",
    "url": "00020126830014br.gov.bcb.pix2561qrcode.qitech.app/bacen/cobv/58fd5103a8e64bbbab2fd49b0bd580145204000053039865802BR5925GONNFUNDODEINVESTIMENTOEM6012RiodeJaneiro6107226401262070503***6304EA0D",
    "image": "<base64 encoded QR code image>"
  }
}

STATUS

202

Response Body: 待注册 Boleto

{
  "request_control_key": "f14e9bac-94ed-4eb1-87b4-7fd7b7a2d280",
  "bank_slip_key": "e8599844-5cad-40b4-8716-cb4770d415b4",
  "bank_slip_status": "accepted"
}

说明

若返回 HTTP Status 202 且 bank_slip_status 值为 accepted，则不应重试发行。

此发行将异步处理。需要通过查询 Boleto 来验证状态，或等待接收Webhook 页面中描述的确认 Webhook。

响应体参数

字段	类型	描述	字符数
`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 已接受但尚未注册
registered	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	BKS000023	Bad Request	The amount must be greater than zero.	O valor deve ser maior que zero.
400	BKS000024	Bad Request	Error while registering bank slip.	Erro ao registrar boleto.
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 枚举值​

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 对象​

错误响应​

Request

路径参数

请求体参数

financial_instrument_type 枚举值

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 对象

错误响应