通过密钥查询 Boleto

通过密钥查询 Boleto 可返回该 Boleto 的详细信息，例如与该 Boleto 相关的所有指令。

Request

ENDPOINT

/account/ACCOUNT_KEY/requester_profile/REQUESTER_PROFILE_KEY/bank_slip/BANK_SLIP_KEY

MÉTODO

GET

路径参数

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

Response

STATUS

200

Response Body

{
  "bank_slip_key": "4c2fa514-a44d-40f2-8d57-c0caf1b9165a",
  "request_control_key": "0dcb3182-4d7e-4526-8f92-c15cdbc51bad",
  "our_number": 26652176735,
  "document_number": "DOC4561237",
  "amount": "5000.00",
  "rebate_amount": "0.00",
  "expiration": "2024-07-12",
  "barcode": "32994978900005000000001546128483498231955340",
  "digitable_line": "32990001524612848349582319553408497890000500000",
  "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.0,
    "days_to_fine": 10
  },
  "interest_data": {
    "interest_type": "workdays_daily_amount",
    "interest_amount": 10.0,
    "days_to_interest": 2
  },
  "discounts_data": [
    {
      "discount_type": "absolute",
      "discount_amount": 50.0,
      "discount_number": 1,
      "discount_limit_date": "2024-07-12"
    }
  ],
  "payer_data": {
    "name": "Global Tech",
    "address": {
      "city": "Innovation City",
      "state": "SP",
      "number": "202",
      "street": "101 High St.",
      "complement": "Building A",
      "postal_code": "57099999",
      "neighborhood": "Tech Park"
    },
    "person_type": "legal",
    "document_number": "12345678000195"
  },
  "guarantor_data": {
    "name": "Jane Doe",
    "address": {
      "city": "Peaceful Town",
      "state": "RJ",
      "number": "303",
      "street": "202 Elm St.",
      "complement": "House 1",
      "postal_code": "57099999",
      "neighborhood": "Quiet Neighborhood"
    },
    "person_type": "natural",
    "document_number": "23456789012"
  },
  "qr_code_data": {
    "qr_code_key": "58bd3558-f214-4e83-9c88-1ac4c93db214",
    "pix_key": "f9b05a58-9dcf-49cb-bc7f-99c5b3f1fdcb",
    "receiver_conciliation_id": "a3861b53f5414b0ba6c9f800d7374474",
    "url": "00020126890014br.gov.bcb.pix2567qrcode-h.dev.qitech.app/bacen/cobv/a3861b53f5414b0ba6c9f800d73744745204000053039865802BR5922BeatrizCoutodeCarvalho6012SAOJOSEDORIO61081501410062070503***6304ED95",
    "image": "<base64 encoded QR code image>"
  },
  "payment_notice_data": {
    "payment_method": "account_debit",
    "payment_origin": "internet",
    "payment_notice_date": "2024-07-01"
  },
  "payment_data": {
    "paid_amount": 850.0,
    "paid_rebate_amount": 200.0,
    "paid_discount_amount": 0.0,
    "paid_fine_amount": 0.0,
    "paid_interest_amount": 50.0,
    "payment_method": "account_debit",
    "payment_origin": "internet",
    "payment_credit_date": "2024-07-02",
    "payment_date": "2024-07-01",
    "payment_bank": {
      "code": "341",
      "ispb": 60701190,
      "name": "ITAU UNIBANCO S.A."
    },
    "payment_branch": "0216"
  },
  "bank_slip_status": "registered",
  "occurrences": [
    {
      "request_control_key": "0dcb3182-4d7e-4526-8f92-c15cdbc51bad",
      "occurrence_key": "ec67408c-a149-418a-b89b-b9c9d3b6c403",
      "occurrence_type": "registration",
      "occurrence_status": "confirmed",
      "created_at": "2024-06-23T09:15:32Z"
    },
    {
      "request_control_key": "9618c632-7f4d-490b-8817-2bb72ec1e84a",
      "occurrence_key": "70d3e632-644d-499f-baac-f65f21fb8574",
      "occurrence_type": "rebate",
      "occurrence_status": "confirmed",
      "created_at": "2024-06-26T12:36:04Z"
    },
    {
      "request_control_key": "c2b2ba59-9c37-488d-823d-2c3bfc1e9108",
      "occurrence_key": "dbdd513c-e918-4d17-b194-b5ae3d979988",
      "occurrence_type": "cancel_rebate",
      "occurrence_status": "confirmed",
      "created_at": "2024-06-26T12:53:47Z"
    }
  ]
}

响应体参数

字段	类型	描述	字符数
`bank_slip_key` *	uuidv4	Boleto 唯一标识密钥，格式为 uuid v4	36
`request_control_key` *	uuidv4	客户请求唯一标识密钥，格式为 uuid v4	36
`our_number` *	integer	Boleto 在钱包中的唯一识别编号	11
`bank_slip_status` *	string	Boleto 状态	bank_slip_status 枚举值
`protest_status` *	string	Boleto 在公证处的抗议状态	protest_status 枚举值
`document_number` *	string	Boleto 识别编号	10
`amount` *	float	Boleto 基准金额	-
`expiration` *	string	到期日	10
`barcode` *	string	Boleto 条形码	44
`digitable_line` *	string	Boleto 可打印行	47
`bank_teller_instructions`	string	额外注册说明，将显示在 Boleto PDF 中	320
`rebate_amount`	float	Boleto 减免金额，将在基准金额之上应用	-
`max_payment_days` *	integer	Boleto 到期后可供支付的最大自然日数（最多 365 天）	-
`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 对象
`qr_code_data`	object	QR Code 数据	qr_code_data 对象
`payment_notice_data`	object 或 array	付款通知数据	payment_notice_data 对象或数组
`payment_data`	object 或 array	付款数据	payment_data 对象或数组
`occurrences`	object array	Boleto 相关指令	bank_slip_occurrence 对象

说明

amount 字段是 Boleto 的基准金额，即不含罚款（fine）、利息（interest）、减免（rebate）和折扣（discounts）。

bank_slip_status 枚举值

枚举值	描述
accepted	已接受并发送至 Nuclea/CIP 进行分析
rejected	被 Nuclea/CIP 拒绝注册
payment_notice	付款通知（Boleto 已付但付款尚未清算）
notary_office_payment_notice	公证处付款通知（Boleto 已付但付款尚未清算）
registered	Nuclea/CIP 已确认注册
payment_blocked	已锁定支付（处于抗议流程中）
paid	已支付
written_off	已核销

protest_status 枚举值

枚举值	描述
not_protested	Boleto 尚未启动抗议流程
protest_requested	已申请公证处抗议
notary_office_entry	Boleto 在公证处，处于三日期间
protest_cancel_requested	已申请撤销抗议
notary_office_exit	Boleto 已离开公证处
protested	Boleto 已被抗议
paid_at_notary_office	在公证处支付
judicially_suspended	抗议被司法暂停
protest_remove_requested	已申请移除抗议

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_type in ["absolute", "anticipation_calendar_days_daily_amount", "anticipation_workdays_daily_amount"]）

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

选项 2：百分比折扣（discount_type in ["percentage", "anticipation_calendar_days_daily_percentage", "anticipation_workdays_daily_percentage"]）

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

注意！

一张 Boleto 最多可有三个折扣，且所有折扣必须为同一类型，即具有相同的 discount_type。折扣编号必须从 1 开始，按递增顺序编号，最大到 3。即，若请求中发送两个折扣，必须分别编号为 1 和 2。

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

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

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 编码图片	-

payment_notice_data 对象或数组

注意！

对于未配置部分支付的 Boleto，payment_notice_data 字段将以对象形式返回。对于配置了部分支付的 Boleto，将以对象数组形式返回，因为可能存在多笔付款。此外，如果 Boleto 通过 QR Code 支付，该字段不会返回，因为清算在付款当日完成。

字段	类型	描述	字符数
`payment_method`	string	支付方式	payment_method 枚举值
`payment_origin`	string	支付来源	payment_origin 枚举值
`payment_notice_date`	string	付款通知日期	10

payment_data 对象或数组

注意！

对于未配置部分支付的 Boleto，payment_data 字段将以对象形式返回。对于配置了部分支付的 Boleto，将以对象数组形式返回，因为可能存在多笔付款。

字段	类型	描述	字符数
`paid_amount`	float	付款金额	-
`paid_rebate_amount`	float	已付减免金额	-
`paid_discount_amount`	float	已付折扣金额	-
`paid_fine_amount`	float	已付罚款金额	-
`paid_interest_amount`	float	已付利息金额	-
`payment_method`	string	支付方式	payment_method 枚举值
`payment_origin`	string	支付来源	payment_origin 枚举值
`payment_credit_date`	string	付款入账日期	10
`payment_bank`	object	Boleto 付款所在的银行。仅在 Boleto 付款后返回	payment_bank 对象
`payment_branch`	string	Boleto 付款所在的分行（agência）。仅在 Boleto 付款后返回	-

信息

字段 payment_bank 和 payment_branch 仅在 Boleto 已付款（即存在已确认的付款记录）时返回。在 Boleto 付款之前，响应中不会包含这些字段。

payment_bank 对象

字段	类型	描述	字符数
`code`	string	银行清算代码（3 位数）	3
`ispb`	integer	银行 ISPB	8
`name`	string	银行名称	-

payment_method 枚举值

枚举值	描述
cash	现金
account_debit	账户扣款
credit_card	信用卡
check	支票

payment_origin 枚举值

枚举值	描述
phisical_cashier	银行网点 - 传统柜台
taa	自动取款机
internet	互联网（网上/办公室银行）
corban	银行代理
call_center	电话客服中心
eletronic_file	电子文件
dda	DDA
digital_correspondent	数字银行代理
qr_code	Pix QR Code 支付

bank_slip_occurrence 对象

字段	类型	描述	字符数
`request_control_key` *	uuidv4	客户请求唯一标识密钥，格式为 uuid v4	36
`occurrence_key` *	uuidv4	Boleto 唯一标识密钥，格式为 uuid v4	36
`occurrence_type` *	string	事件类型	occurrence_type 枚举值
`occurrence_status` *	string	事件状态	occurrence_status 枚举值
`created_at` *	string	事件创建日期，ISO 格式（UTC - "YYYY-MM-DDTHH:MM:SSZ"）	20

occurrence_type 枚举值

枚举值	描述
registration	注册事件
write_off	核销申请事件
rebate	添加减免事件
cancel_rebate	取消减免事件
discount	修改折扣事件
fine	修改罚款事件
interest	修改利息事件
extension	延期事件
bank_slip_edit	修改 Boleto 其他数据事件
payment_notice	付款通知事件
payment	付款清算事件
protest_request	抗议申请事件

occurrence_status 枚举值

枚举值	描述
pending	已发送至 Nuclea/CIP 待分析
rejected	已拒绝
confirmed	已确认

错误响应

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	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.
404	BKS000013	Not Found	Requester profile not found	Carteira não encontrada
400	BKS000022	Bad Request	Requester profile is not opened.	Carteira não está aberta.
404	BKS000029	Not Found	Bank slip not found for the given key (`{bank_slip_key}`).	Boleto não encontrado para a chave fornecida (`{bank_slip_key}`).

Request​

路径参数​

Response​

响应体参数​

bank_slip_status 枚举值​

protest_status 枚举值​

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 枚举值​

qr_code_data 对象​

payment_notice_data 对象或数组​

payment_data 对象或数组​

payment_bank 对象​

payment_method 枚举值​

payment_origin 枚举值​

bank_slip_occurrence 对象​

occurrence_type 枚举值​

occurrence_status 枚举值​

错误响应​