Webhooks
Ao longo do ciclo de vida do boleto, o sistema envia webhooks para notificar o parceiro integrador sobre mudanças de status. Todos os eventos utilizam o tipo bankslip_collection.bankslip_status_change.
Configuração de webhooks
Para receber webhooks, é necessário ter uma URL de callback configurada junto à QI Tech. Entre em contato com integracao@qitech.com.br para configurar.
Estrutura do webhook
Todos os webhooks de boleto seguem a mesma estrutura base:
| Campo | Tipo | Descrição |
|---|---|---|
webhook_type | string | Tipo do webhook. Sempre bankslip_collection.bankslip_status_change. |
webhook_datetime | string | Data e hora do evento no formato ISO 8601. |
data | object | Dados do evento. Veja tabela abaixo. |
Atributos de data
| Campo | Tipo | Descrição |
|---|---|---|
bankslip_key | string (UUID) | Identificador único do boleto. |
bankslip_configuration_key | string (UUID) | Identificador da configuração do boleto. |
bankslip_profile_key | string (UUID) | Identificador do perfil do boleto. |
status | string | Status atual do boleto. |
fund_class | object | Dados da classe do fundo associada ao boleto. |
external_participant_control_number | string | Número de controle externo do participante. |
participant_control_number | string | Número de controle interno do participante. |
face_value | float | Valor de face do boleto. |
due_date | string | Data de vencimento no formato YYYY-MM-DD. |
borrower | object | Dados do sacado (devedor). |
assignor | object | Dados do cedente. |
settlement_instructions | array | Lista de instruções de liquidação vinculadas ao boleto. |
our_number | integer | (Opcional) Nosso número atribuído pelo banco emissor. |
our_number_digit | string | (Opcional) Dígito verificador do nosso número. |
order_number | string | (Opcional) Número do pedido. |
digitable_line | string | (Opcional) Linha digitável do boleto. Presente quando disponível após o registro. |
barcode | string | (Opcional) Código de barras do boleto. Presente quando disponível após o registro. |
Atributos de fund_class
| Campo | Tipo | Descrição |
|---|---|---|
document_number | string | CNPJ da classe do fundo. |
fund_class_key | string (UUID) | Identificador da classe do fundo. |
name | string | Nome da classe do fundo. |
Atributos de settlement_instructions
| Campo | Tipo | Descrição |
|---|---|---|
asset_key | string (UUID) | Identificador do ativo associado. |
asset_type | string | Tipo do ativo (ex: duplicata_mercantil, duplicata_servicos, ccb). |
issue_date | string | Data de emissão do ativo no formato YYYY-MM-DD. |
maturity_date | string | Data de vencimento do ativo no formato YYYY-MM-DD. |
face_value | float | Valor de face do ativo. |
status | string | Status da instrução de liquidação. |
external_id | string | (Opcional) Identificador externo do ativo. |
installment_number | integer | (Opcional) Número da parcela, quando aplicável (ex: CCBs parceladas). |
order_number | string | (Opcional) Número do pedido da instrução. |
Eventos por status
Registro do Boleto
STATUS
pending_registrationEnviado quando um boleto é criado e submetido ao banco emissor para registro. O boleto aguarda a confirmação da instituição bancária. Dependendo do banco, os campos digitable_line, barcode e our_number podem estar presentes quando o banco os retorna imediatamente no ato do registro. Para outros bancos, esses campos são preenchidos somente após a confirmação via arquivo de retorno.
Webhook Body
{
"webhook_type": "bankslip_collection.bankslip_status_change",
"webhook_datetime": "2026-04-15T12:55:35Z",
"data": {
"bankslip_key": "7a26c259-1b1f-4d73-9a5b-48230022b8f2",
"bankslip_configuration_key": "b6b4ff70-917c-4003-bc4d-ebc4ccdd606c",
"bankslip_profile_key": "5666937c-944a-44c6-98e6-3591f99fe4ff",
"status": "pending_registration",
"fund_class": {
"document_number": "17.645.194/0001-85",
"fund_class_key": "d81118d0-527b-45b0-8c60-76e9d3ab3aa3",
"name": "Nome da Classe do Fundo"
},
"external_participant_control_number": "XO0QYVBF1JU9LFBBKGT7XYQV9",
"participant_control_number": "XO0QYVBF1JU9LFBBKGT7XYQV9",
"face_value": 629.33,
"due_date": "2026-09-17",
"borrower": {
"document_number": "631.430.668-06",
"name": "Nome do Sacado",
"person_type": "natural_person",
"address": {
"postal_code": "05425-020"
}
},
"assignor": {
"name": "Nome do Cedente",
"document_number": "37.341.966/0001-00",
"person_type": "legal_person"
},
"settlement_instructions": [
{
"asset_key": "22fc5c95-3622-48ad-b26a-99f8d0499e69",
"external_id": "758638e4-6fe6-4b69-8799-30728ca16a22",
"asset_type": "duplicata_mercantil",
"issue_date": "2025-01-17",
"maturity_date": "2026-09-17",
"face_value": 629.33,
"status": "pending_bankslip_payment"
}
],
"our_number": 10507,
"our_number_digit": "0"
}
}
Boleto Registrado
STATUS
registeredEnviado quando o banco emissor confirma o registro do boleto. A partir deste momento, o boleto está apto para pagamento pelo sacado. Neste webhook, os campos digitable_line, barcode, our_number e our_number_digit estarão presentes.
Webhook Body
{
"webhook_type": "bankslip_collection.bankslip_status_change",
"webhook_datetime": "2026-04-15T13:10:22Z",
"data": {
"bankslip_key": "7a26c259-1b1f-4d73-9a5b-48230022b8f2",
"bankslip_configuration_key": "b6b4ff70-917c-4003-bc4d-ebc4ccdd606c",
"bankslip_profile_key": "5666937c-944a-44c6-98e6-3591f99fe4ff",
"status": "registered",
"fund_class": {
"document_number": "17.645.194/0001-85",
"fund_class_key": "d81118d0-527b-45b0-8c60-76e9d3ab3aa3",
"name": "Nome da Classe do Fundo"
},
"external_participant_control_number": "XO0QYVBF1JU9LFBBKGT7XYQV9",
"participant_control_number": "XO0QYVBF1JU9LFBBKGT7XYQV9",
"face_value": 629.33,
"due_date": "2026-09-17",
"borrower": {
"document_number": "631.430.668-06",
"name": "Nome do Sacado",
"person_type": "natural_person",
"address": {
"postal_code": "05425-020"
}
},
"assignor": {
"name": "Nome do Cedente",
"document_number": "37.341.966/0001-00",
"person_type": "legal_person"
},
"settlement_instructions": [
{
"asset_key": "22fc5c95-3622-48ad-b26a-99f8d0499e69",
"external_id": "758638e4-6fe6-4b69-8799-30728ca16a22",
"asset_type": "duplicata_mercantil",
"issue_date": "2025-01-17",
"maturity_date": "2026-09-17",
"face_value": 629.33,
"status": "pending_bankslip_payment"
}
],
"our_number": 10507,
"our_number_digit": "0",
"digitable_line": "03399.87654 32100.012345 67890.123456 1 00000000062933",
"barcode": "03391000000000629333987654321000123456789012345"
}
}
Boleto Rejeitado
STATUS
rejectedEnviado quando o banco emissor rejeita o registro do boleto. O boleto não estará disponível para pagamento e não avançará no fluxo. As instruções de liquidação vinculadas também são marcadas como rejected.
Webhook Body
{
"webhook_type": "bankslip_collection.bankslip_status_change",
"webhook_datetime": "2026-04-15T13:10:22Z",
"data": {
"bankslip_key": "7a26c259-1b1f-4d73-9a5b-48230022b8f2",
"bankslip_configuration_key": "b6b4ff70-917c-4003-bc4d-ebc4ccdd606c",
"bankslip_profile_key": "5666937c-944a-44c6-98e6-3591f99fe4ff",
"status": "rejected",
"fund_class": {
"document_number": "17.645.194/0001-85",
"fund_class_key": "d81118d0-527b-45b0-8c60-76e9d3ab3aa3",
"name": "Nome da Classe do Fundo"
},
"external_participant_control_number": "XO0QYVBF1JU9LFBBKGT7XYQV9",
"participant_control_number": "XO0QYVBF1JU9LFBBKGT7XYQV9",
"face_value": 629.33,
"due_date": "2026-09-17",
"borrower": {
"document_number": "631.430.668-06",
"name": "Nome do Sacado",
"person_type": "natural_person",
"address": {
"postal_code": "05425-020"
}
},
"assignor": {
"name": "Nome do Cedente",
"document_number": "37.341.966/0001-00",
"person_type": "legal_person"
},
"settlement_instructions": [
{
"asset_key": "22fc5c95-3622-48ad-b26a-99f8d0499e69",
"external_id": "758638e4-6fe6-4b69-8799-30728ca16a22",
"asset_type": "duplicata_mercantil",
"issue_date": "2025-01-17",
"maturity_date": "2026-09-17",
"face_value": 629.33,
"status": "rejected"
}
],
"our_number": 10507,
"our_number_digit": "0"
}
}
Boleto Baixado
STATUS
written_offEnviado quando o boleto é baixado na instituição emissora. Isso pode ocorrer por solicitação de cancelamento.
Webhook Body
{
"webhook_type": "bankslip_collection.bankslip_status_change",
"webhook_datetime": "2026-04-15T14:30:00Z",
"data": {
"bankslip_key": "7a26c259-1b1f-4d73-9a5b-48230022b8f2",
"bankslip_configuration_key": "b6b4ff70-917c-4003-bc4d-ebc4ccdd606c",
"bankslip_profile_key": "5666937c-944a-44c6-98e6-3591f99fe4ff",
"status": "written_off",
"fund_class": {
"document_number": "17.645.194/0001-85",
"fund_class_key": "d81118d0-527b-45b0-8c60-76e9d3ab3aa3",
"name": "Nome da Classe do Fundo"
},
"external_participant_control_number": "XO0QYVBF1JU9LFBBKGT7XYQV9",
"participant_control_number": "XO0QYVBF1JU9LFBBKGT7XYQV9",
"face_value": 629.33,
"due_date": "2026-09-17",
"borrower": {
"document_number": "631.430.668-06",
"name": "Nome do Sacado",
"person_type": "natural_person",
"address": {
"postal_code": "05425-020"
}
},
"assignor": {
"name": "Nome do Cedente",
"document_number": "37.341.966/0001-00",
"person_type": "legal_person"
},
"settlement_instructions": [
{
"asset_key": "22fc5c95-3622-48ad-b26a-99f8d0499e69",
"external_id": "758638e4-6fe6-4b69-8799-30728ca16a22",
"asset_type": "duplicata_mercantil",
"issue_date": "2025-01-17",
"maturity_date": "2026-09-17",
"face_value": 629.33,
"status": "written_off"
}
],
"our_number": 10507,
"our_number_digit": "0",
"digitable_line": "03399.87654 32100.012345 67890.123456 1 00000000062933",
"barcode": "03391000000000629333987654321000123456789012345"
}
}