跳到主要内容

Boleto Webhooks

注意！

QI Tech 的 Webhook 不应进行严格映射。 我们 API 返回的 Webhook 载荷中可能会新增额外字段。

重新发送 Webhook

您可以按照文档中的详细说明查询和重新发送 Webhook：重新发送 Webhook。

简介​

在系统内 Boleto 的整个生命周期中，将发送包含以下 Boleto 状态（bank_slip_status）的 Webhook：

枚举值描述
registeredBoleto 已登记并可供付款
rejectedBoleto 发行申请因验证错误被拒绝
payment_noticeBoleto 支付通知（已付款但尚未清算）
notary_office_payment_noticeBoleto 公证处支付通知（已付款但尚未清算）
paidBoleto 已付款并完成财务清算
written_offBoleto 已注销（不可再付款）且无财务清算
payment_blocked因抗议流程而被锁定支付

以下类型（occurrence_type）的事件被确认时，将发送 Webhook：

枚举值描述
registrationBoleto 登记
rebate票据基础金额折让
cancel_rebate取消现有折让
extension延长票据到期日期
write_offBoleto 注销
protest_write_off因公证处抗议注销 Boleto
payment_write_off因付款注销 Boleto
discount折扣变更
fine罚款变更
interest利息变更
protest_request公证处抗议申请
bankruptcy_protest_request公证处破产抗议申请
notary_office_entry票据进入公证处事件
protest_cancel_request撤销当前抗议申请
protest_remove_request票据抗议暂停
notary_office_exit票据离开公证处事件
payment_noticeBoleto 支付通知（已付款但尚未清算）
notary_office_payment_noticeBoleto 公证处支付通知（已付款但尚未清算）
payment通知 Boleto 已付款并注销
信息

我们 Webhook 的响应超时时间为 10 秒。

示例​

登记​

Webhook Body: 事件已接受
{
	"webhook_type": "baas.bank_slip.occurrence",
	"webhook_datetime": "2024-08-13T21:35:55.679Z",
	"data": {
		"bank_slip_key": "11b13b2c-4204-41b3-8596-2ee7ecbde38c",
		"bank_slip_status": "registered",
		"occurrence_key": "9077cc0b-5bbd-4432-888e-6bf6384c250a",
		"occurrence_type": "registration",
		"occurrence_status": "confirmed"
	}
}
Webhook Body: 事件被拒绝
{
	"webhook_type": "baas.bank_slip.occurrence",
	"webhook_datetime": "2024-08-13T21:35:55.679Z",
	"data": {
		"bank_slip_key": "ae783ed7-b892-4e48-8480-b045e3b492f5",
		"bank_slip_status": "rejected",
		"occurrence_key": "db04719d-4370-4f3f-82b7-d72d3db2f39e",
		"occurrence_type": "registration",
		"occurrence_status": "rejected"
	}
}

折让/取消折让​

Webhook Body: 折让
{
	"webhook_type": "baas.bank_slip.occurrence",
	"webhook_datetime": "2024-08-13T21:35:55.679Z",
	"data": {
		"bank_slip_key": "11b13b2c-4204-41b3-8596-2ee7ecbde38c",
		"bank_slip_status": "registered",
		"occurrence_key": "db04719d-4370-4f3f-82b7-d72d3db2f39e",
		"occurrence_type": "rebate",
		"occurrence_status": "confirmed"
	}
}
Webhook Body: 取消折让
{
	"webhook_type": "baas.bank_slip.occurrence",
	"webhook_datetime": "2024-08-13T21:35:55.679Z",
	"data": {
		"bank_slip_key": "11b13b2c-4204-41b3-8596-2ee7ecbde38c",
		"bank_slip_status": "registered",
		"occurrence_key": "db04719d-4370-4f3f-82b7-d72d3db2f39e",
		"occurrence_type": "cancel_rebate",
		"occurrence_status": "confirmed"
	}
}

延期​

Webhook Body
{
	"webhook_type": "baas.bank_slip.occurrence",
	"webhook_datetime": "2024-08-13T21:35:55.679Z",
	"data": {
		"bank_slip_key": "11b13b2c-4204-41b3-8596-2ee7ecbde38c",
		"bank_slip_status": "registered",
		"occurrence_key": "db04719d-4370-4f3f-82b7-d72d3db2f39e",
		"occurrence_type": "extension",
		"occurrence_status": "confirmed"
	}
}

折扣​

Webhook Body
{
	"webhook_type": "baas.bank_slip.occurrence",
	"webhook_datetime": "2024-08-13T21:35:55.679Z",
	"data": {
		"bank_slip_key": "a8df1c2e-77ff-49ea-9e7a-8fd536a6e357",
		"bank_slip_status": "registered",
		"occurrence_key": "db04719d-4370-4f3f-82b7-d72d3db2f39e",
		"occurrence_type": "discount",
		"occurrence_status": "confirmed"
	}
}

利息​

Webhook Body
{
	"webhook_type": "baas.bank_slip.occurrence",
	"webhook_datetime": "2024-08-13T21:35:55.679Z",
	"data": {
		"bank_slip_key": "69f3f345-07c5-4c80-a8dd-51054afdad01",
		"bank_slip_status": "registered",
		"occurrence_key": "8550e47a-7554-455c-bdd8-cf0c048a277c",
		"occurrence_type": "interest",
		"occurrence_status": "confirmed"
	}
}

罚款​

Webhook Body
{
	"webhook_type": "baas.bank_slip.occurrence",
	"webhook_datetime": "2024-08-13T21:35:55.679Z",
	"data": {
		"bank_slip_key": "97e6edab-b793-4eb6-a1a7-0a27e1d5c73e",
		"bank_slip_status": "registered",
		"occurrence_key": "47b06bdb-c006-47a7-81f2-7aac7fff823b",
		"occurrence_type": "fine",
		"occurrence_status": "confirmed"
	}
}

注销​

occurrence_reason 字段为可选字段，当银行提供注销原因时才会出现。它包含金融机构提供的原因代码和原因名称。

Webhook Body: 无原因
{
	"webhook_type": "baas.bank_slip.occurrence",
	"webhook_datetime": "2024-08-13T21:35:55.679Z",
	"data": {
		"bank_slip_key": "45c21054-57fd-4d28-8d5a-0cdc5cb29670",
		"bank_slip_status": "written_off",
		"occurrence_key": "0b92bd47-fae5-46c0-8c40-e5aebc9ecd28",
		"occurrence_type": "write_off",
		"occurrence_status": "confirmed"
	}
}
Webhook Body: 含原因
{
	"webhook_type": "baas.bank_slip.occurrence",
	"webhook_datetime": "2026-05-04T21:12:07.877Z",
	"data": {
		"bank_slip_key": "25add0b0-cb2d-4be4-8f22-4305a4dd9793",
		"bank_slip_status": "written_off",
		"occurrence_key": "ca71f446-be05-47cc-b470-234e4806344c",
		"occurrence_type": "write_off",
		"occurrence_status": "confirmed",
		"occurrence_reason": {
			"bank_reason_code": "16",
			"bank_reason_name": "Título Baixado pelo Banco por decurso de Prazo"
		}
	}
}

因抗议注销​

Webhook Body
{
	"webhook_type": "baas.bank_slip.occurrence",
	"webhook_datetime": "2024-10-25T18:05:01.395Z",
	"data": {
		"bank_slip_key": "7182639f-dea5-46c6-99c6-af0d94d772cb",
		"bank_slip_status": "written_off",
		"occurrence_key": "93380917-beee-4f3e-af01-6c24e140d53d",
		"occurrence_type": "protest_write_off",
		"occurrence_status": "confirmed"
	}
}

因付款注销​

Webhook Body
{
	"webhook_type": "baas.bank_slip.occurrence",
	"webhook_datetime": "2024-10-18T18:02:15.152Z",
	"data": {
		"bank_slip_key": "40d6a1bc-cfed-4444-a901-e02ecc169ce5",
		"bank_slip_status": "written_off",
		"occurrence_key": "78221daa-945f-485b-b39c-97ef0e251afe",
		"occurrence_type": "payment_write_off",
		"occurrence_status": "confirmed"
	}
}

抗议申请​

Webhook Body
{
	"webhook_type": "baas.bank_slip.occurrence",
	"webhook_datetime": "2024-10-16T20:54:13.013Z",
	"data": {
		"bank_slip_key": "f03c5fec-b31c-402a-b832-80da8a493653",
		"bank_slip_status": "payment_blocked",
		"occurrence_key": "304958f6-cdf2-4fb1-b8f3-5482030bf0eb",
		"occurrence_type": "protest_request",
		"occurrence_status": "confirmed"
	}
}

破产抗议申请​

Webhook Body
{
	"webhook_type": "baas.bank_slip.occurrence",
	"webhook_datetime": "2024-10-16T20:54:13.013Z",
	"data": {
		"bank_slip_key": "21aeefb4-4fa1-4e32-b2bb-32a7486128f0",
		"bank_slip_status": "payment_blocked",
		"occurrence_key": "11a7e9e8-4667-471b-bc3f-2f65f77e22e9",
		"occurrence_type": "bankruptcy_protest_request",
		"occurrence_status": "confirmed"
	}
}

进入公证处​

Webhook Body
{
	"webhook_type": "baas.bank_slip.occurrence",
	"webhook_datetime": "2024-10-17T18:00:48.341Z",
	"data": {
		"bank_slip_key": "5bc4c1d4-d51b-4b0b-b308-81850d04e523",
		"bank_slip_status": "payment_blocked",
		"occurrence_key": "159e6e3f-fce5-4362-829e-1595fc14d66c",
		"occurrence_type": "notary_office_entry",
		"occurrence_status": "confirmed"
	}
}

取消抗议​

Webhook Body
{
	"webhook_type": "baas.bank_slip.occurrence",
	"webhook_datetime": "2024-10-23T18:00:52.374Z",
	"data": {
		"bank_slip_key": "96d2a896-f2da-484c-8d40-20fabbde15ee",
		"bank_slip_status": "registered",
		"occurrence_key": "2505fedf-0061-478b-b45e-8420b755ebbb",
		"occurrence_type": "protest_cancel_request",
		"occurrence_status": "confirmed"
	}
}

暂停抗议​

Webhook Body
{
	"webhook_type": "baas.bank_slip.occurrence",
	"webhook_datetime": "2024-10-30T18:01:00.452Z",
	"data": {
		"bank_slip_key": "878d462e-be4e-40bd-b797-b831fef87f48",
		"bank_slip_status": "written_off",
		"occurrence_key": "cb08785d-0a4d-41f4-a64c-bafe730b175b",
		"occurrence_type": "protest_remove_request",
		"occurrence_status": "confirmed"
	}
}

离开公证处​

Webhook Body
{
	"webhook_type": "baas.bank_slip.occurrence",
	"webhook_datetime": "2024-11-01T18:01:01.949Z",
	"data": {
		"bank_slip_key": "79d07a3d-3953-4195-a2e2-bbbf10635f27",
		"bank_slip_status": "registered",
		"occurrence_key": "c703b04c-7334-40fe-bf8d-b43bd991dbab",
		"occurrence_type": "notary_office_exit",
		"occurrence_status": "confirmed"
	}
}

支付通知​

第一个 Webhook：Boleto 已付款，但尚未清算

Webhook Body
{
	"webhook_type": "baas.bank_slip.payment_notice",
	"webhook_datetime": "2024-08-13T21:35:55.679Z",
	"data": {
		"bank_slip_key": "db04719d-4370-4f3f-82b7-d72d3db2f39e",
		"bank_slip_status": "payment_notice",
		"occurrence_key": "d0341ad7-aa87-4dad-929b-38c8c9218f23",
		"occurrence_type": "payment_notice",
		"occurrence_status": "confirmed"
	}
}

公证处支付通知​

第一个 Webhook：Boleto 已在公证处付款，但尚未清算

Webhook Body
{
	"webhook_type": "baas.bank_slip.notary_office_payment_notice",
	"webhook_datetime": "2024-10-16T18:00:43.621Z",
	"data": {
		"bank_slip_key": "05f2b81b-b241-4e72-9b2c-7312257a0284",
		"bank_slip_status": "notary_office_payment_notice",
		"occurrence_key": "3ecab7b1-c991-4d91-8d71-08a34eec1d7d",
		"occurrence_type": "notary_office_payment_notice",
		"occurrence_status": "confirmed"
	}
}

付款​

Webhook Body
{
	"webhook_type": "baas.bank_slip.payment",
	"webhook_datetime": "2024-08-13T21:35:55.679Z",
	"data": {
		"bank_slip_key": "db04719d-4370-4f3f-82b7-d72d3db2f39e",
		"bank_slip_status": "paid",
		"occurrence_key": "db04719d-4370-4f3f-82b7-d72d3db2f39e",
		"occurrence_type": "payment",
		"occurrence_status": "confirmed",
		"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": "qr_code",
		"payment_credit_date": "2024-07-02",
		"payment_bank": {
			"code": "341",
			"ispb": 60701190,
			"name": "ITAU UNIBANCO S.A."
		},
		"payment_branch": "0216"
	}
}
信息

payment_bank 和 payment_branch 字段表示 Boleto 付款所在的银行和分行。它们仅在付款结算时收到该信息后才会填充；如果未识别出付款银行，payment_bank 将返回 null。

payment_origin 枚举值​

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

payment_origin 枚举值​

枚举值描述
phisical_cashier传统网点
taa自动取款机终端
internet网络银行（home/office banking）
corban银行代理
call_center客服中心
eletronic_file电子文件
ddaDDA
digital_correspondent数字代理
qr_codePix QR Code 支付