Webhooks de boletos

Atenção!

Os webhooks da QI Tech não devem ser mapeadas de forma restrita. Campos adicionais podem ser incluídos aos payloads dos webhooks retornados em nossas APIs.

Introdução

Ao longo do ciclo de vida dos boletos, dentro do nosso sistema, serão enviados webhooks com os seguintes status do boleto (bank_slip_status):

Enumerador	Tradução	Descrição
registered	registrado	Boleto registrado e disponível para pagamento
rejected	rejeitado	Solicitação de emissão de boleto rejeitada por erros de validação
payment_notice	aviso de pagamento	Aviso de pagamento do boleto (boleto pago mas pagamento ainda não liquidado)
paid	pago	Boleto pago e liquidado financeiramente
written_off	baixado	Boleto baixado (não pode mais ser pago) e sem liquidação financeira

E os webhooks são enviados sempre que são confirmadas ocorrências dos seguintes tipos (occurrence_type):

Enumerador	Tradução	Descrição
registration	registro	Registro do boleto
rebate	abatimento	Abatimento de parte do valor base do título
cancel_rebate	cancelamento de abatimento	Cancelamento de abatimento existente
extension	extensão	Extensão da data de expiração do título
write_off	baixa	Baixa do boleto
discount	desconto	Alteração dos descontos
fine	multa	Alteração da multa
interest	juros	Alterações dos juros
payment_notice	aviso de pagamento	Aviso de pagamento do boleto (boleto pago mas pagamento ainda não liquidado)
payment	pagamento	Notificação de que o boleto foi pago e baixado

Informação

O timeout para resposta de nosso webhooks é de 10 segundos.

Exemplos

---

Registro

Webhook Body

{
	"key": "f230860a-6d57-4ea1-a0e7-1f36367ed3fe",
	"webhook_type": "baas.bank_slip.occurrence",
	"event_datetime": "2024-06-15 16:12:12",
	"data": {
		"bank_slip_key": "11b13b2c-4204-41b3-8596-2ee7ecbde38c",
		"bank_slip_status": "registered",
		"occurrence_key": "db04719d-4370-4f3f-82b7-d72d3db2f39e",
		"occurrence_type": "registration",
		"occurrence_status": "confirmed"
	}
}

Atenção!

Caso a ocorrência seja rejeitada, o occurrence_status virá como rejected.

Abatimento/cancelamento de abatimento

Webhook Body: abatimento

{
	"key": "f1182ae9-29cc-4f11-94dd-c5c19bef88b9",
	"webhook_type": "baas.bank_slip.occurrence",
	"event_datetime": "2024-06-15 16:12:12",
	"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: cancelamento de abatimento

{
	"key": "e3e80c97-77cd-44fc-bb5f-c6ee28800daf",
	"webhook_type": "baas.bank_slip.occurrence",
	"event_datetime": "2024-06-15 16:12:12",
	"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"
	}
}

Prorrogação

Webhook Body

{
	"key": "7eaae077-da74-4915-9760-2cba2f2598c4",
	"webhook_type": "baas.bank_slip.occurrence",
	"event_datetime": "2024-06-15 16:12:12",
	"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"
	}
}

Desconto

Webhook Body

{
	"key": "5d3b3388-3eef-4164-895c-1bae6391d33f",
	"webhook_type": "baas.bank_slip.occurrence",
	"event_datetime": "2024-06-15 16:12:12",
	"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"
	}
}

Juros

Webhook Body

{
	"key": "85e10f06-a913-4e47-bd43-3a15cbf0f2e3",
	"webhook_type": "baas.bank_slip.occurrence",
	"event_datetime": "2024-06-15 16:12:12",
	"data": {
		"bank_slip_key": "69f3f345-07c5-4c80-a8dd-51054afdad01",
		"bank_slip_status": "registered",
		"occurrence_key": "db04719d-4370-4f3f-82b7-d72d3db2f39e",
		"occurrence_type": "interest",
		"occurrence_status": "confirmed"
	}
}

Multa

Webhook Body

{
	"key": "54deda15-49ab-403d-b36b-60836a000a24",
	"webhook_type": "baas.bank_slip.occurrence",
	"event_datetime": "2024-06-15 16:12:12",
	"data": {
		"bank_slip_key": "97e6edab-b793-4eb6-a1a7-0a27e1d5c73e",
		"bank_slip_status": "registered",
		"occurrence_key": "db04719d-4370-4f3f-82b7-d72d3db2f39e",
		"occurrence_type": "fine",
		"occurrence_status": "confirmed"
	}
}

Baixa

Webhook Body

{
	"key": "a3a7860d-17ff-4029-91d6-68b567cc92e3",
	"webhook_type": "baas.bank_slip.occurrence",
	"event_datetime": "2024-06-15 16:12:12",
	"data": {
		"bank_slip_key": "45c21054-57fd-4d28-8d5a-0cdc5cb29670",
		"bank_slip_status": "written_off",
		"occurrence_key": "db04719d-4370-4f3f-82b7-d72d3db2f39e",
		"occurrence_type": "write_off",
		"occurrence_status": "confirmed"
	}
}

Aviso de pagamento

Primeiro webhook: boleto foi pago, mas ainda não foi liquidado

Webhook Body

{
	"key": "f23fdacd-ed1c-4474-89ee-06971868175a",
	"webhook_type": "baas.bank_slip.payment_notice",
	"event_datetime": "2024-06-15 16:12:12",
	"data": {
		"bank_slip_key": "db04719d-4370-4f3f-82b7-d72d3db2f39e",
		"bank_slip_status": "payment_notice",
		"occurrence_key": "db04719d-4370-4f3f-82b7-d72d3db2f39e",
		"occurrence_type": "payment_notice",
		"occurrence_status": "confirmed"
	}
}

Pagamento

Webhook Body

{
	"key": "f23fdacd-ed1c-4474-89ee-06971868175a",
	"webhook_type": "baas.bank_slip.payment",
	"event_datetime": "2024-06-15 16:12:12",
	"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"
	}
}

Enumeradores payment_origin

Enumerador	Descrição
cash	Espécie
account_debit	Débito em conta
credit_card	Cartão de crédito
check	Cheque

Enumeradores payment_origin

Enumerador	Descrição
phisical_cashier	Agências - Postos tradicionais
taa	Terminal de Auto-atendimento
internet	Internet (home/office bank)
corban	Correspondente bancário
call_center	Central de atendimento (call center)
eletronic_file	Arquivo eletrônico
dda	DDA
digital_correspondent	Correspondente Digital
qr_code	Pagamento via Pix QR Code