Manual Consignado Privado - Averbação e Desembolso
Os webhooks da QI Tech não devem ser mapeados de forma estrita. Campos adicionais podem ser incluídos aos payloads dos webhooks retornados em nossas APIs.
Você pode consultar e reenviar webhooks seguindo as instruções detalhadas na documentação: Reenvio de Webhooks.
1. Confirmação da proposta
No fluxo ativo, é possível configurar o ambiente para que a operação siga para as etapas de averbação e desembolso logo após a finalização da formalização da dívida pelo tomador, caso contrário, será enviado um webhook informando que a operação está aguardando uma chamada de autorização para dar continuidade ao fluxo (esta configuração deve ser alinhada com o time de operações).
Averbação pendente de autorização
Webhook Body
{
"webhook_type": "laas.private_payroll.reservation_status_change",
"data": {
"reservation_status": "pending_requester_authorization"
},
"key": "<Debt Key>",
"event_datetime": "2025-04-09T20:00:20Z",
"status": "pending_requester_authorization"
}
Neste momento o parceiro pode tomar a decisão de seguir com o desembolso da opreração ou cancelar a proposta:
Autorizar Averbação
Para seguir com a averbação, deve ser realizada a chamada:
Request
Response
Response Body
{
"reservation_key": "<Debt Key>",
"document_number": "12345678901",
"registration_number": "99999999999-A",
"employer_document_number": "12345678901234",
"external_key": "abc123def456",
"contract_number": "2024001234",
"inclusion_date": "2024-03-18",
"disbursement_date": "2024-03-20",
"contract_data": {
"amount": 5000.00,
"installments": 12,
"interest_rate": 0.018
},
"reservation_data": {
"installment_value": 500.00,
"margin_value": 450.00
},
"reservation_status": "authorized"
}
Cancelar operação
Para não prosseguir com a averbação, é necessário cancelar a operação.
Se a operação foi originada no fluxo ativo, isto pode ser feito através do endpoint de cancelamento permanente, da mesma forma que é feito no item 5 - Desaverbação.
Se a operação foi originada via leilão, o cancelamento deverá ser feito através do endpoint de cancelamento da proposta, conforme documentação do Leilão.
O campo external_key é o UUID da operação de crédito, o mesmo que debt_key e credit_operation_key.
2 - Averbação
Sucesso na averbação
Em caso de sucesso na averbação o parceiro receberá o seguinte webhook:
Webhook Body
{
"webhook": {
"key": "<UUID>",
"data": {
"collateral_data": {},
"collateral_type": "private_payroll",
"collateral_constituted": true
},
"event_time": "2025-07-10 02:15:01",
"webhook_type": "credit_operation.collateral"
}
}
Falha na averbação
Caso haja uma falha na averbação, será enviado um webhook com a crítica da DATAPREV. Os possíveis motivos de falha na averbação podem ser consultados na tabela Motivo de falha na averbação. Dependendo do erro de averbação, a QI manterá a proposta em "teimosinha" fazendo novas tentativas de averbação até que a operação seja cancelada manualmente ou por esgotar as opções de desembolso.
Webhook Body
{
"key": "72926c65-35a5-4060-b5ec-af8661d8546a",
"data": {
"collateral_data": {
"status": "pending_reservation",
"last_response": {
"errors": [
{
"enumerator": "monthly_interest_rate_exceeds_active_proposal"
}
]
},
"last_response_event_datetime": "2025-10-10T19:45:39Z"
},
"collateral_type": "private_payroll",
"collateral_constituted": false
},
"event_time": "2025-10-10 00:07:21",
"webhook_type": "credit_operation.collateral"
}
3 - Desembolso
Após o sucesso na averbação, a operação seguirá automaticamente para o desembolso.
Sucesso no desembolso
Webhook Body
{
"key": "8351238-1272-46b2-292b-7161a05c5161",
"data": {
"installments": [
{
"due_date": "2026-04-28",
"total_amount": 180.75,
"installment_key": "6286548-015a-4f26-8fb5-0d23f34554e",
"pre_fixed_amount": 180.75,
"installment_number": 1,
"principal_amortization_amount": 0.0
},
{
"due_date": "2026-05-28",
"total_amount": 180.75,
"installment_key": "b3e719e6-24fc-4ddf-a8b8-ee9012342ba6",
"pre_fixed_amount": 180.75,
"installment_number": 2,
"principal_amortization_amount": 0.0
},
{
"due_date": "2026-06-28",
"total_amount": 180.75,
"installment_key": "3652fb45-4304-4f8e-84ff-1234307042cc",
"pre_fixed_amount": 180.75,
"installment_number": 3,
"principal_amortization_amount": 0.0
},
{
"due_date": "2026-07-28",
"total_amount": 180.75,
"installment_key": "7e2d4334-b963-4a77-1234-4e4fcb1986f8",
"pre_fixed_amount": 180.75,
"installment_number": 4,
"principal_amortization_amount": 0.0
},
{
"due_date": "2026-08-28",
"total_amount": 180.75,
"installment_key": "a1ab6f5b-321b-41a0-a608-0eb54a261014",
"pre_fixed_amount": 180.75,
"installment_number": 5,
"principal_amortization_amount": 0.0
},
{
"due_date": "2026-09-28",
"total_amount": 180.75,
"installment_key": "7d423192-10d4-45c6-8353-7c3be28ee368",
"pre_fixed_amount": 180.75,
"installment_number": 6,
"principal_amortization_amount": 0.0
}
],
"ted_receipt_list": [
{
"fee": 0,
"url": "[URL]",
"amount": 2444.15,
"origin": {
"name": "QI SOCIEDADE DE CRÉDITO DIRETO S.A.",
"type": "payment_account",
"branch": "0001",
"document": "32402502000135",
"bank_code": "329",
"account_key": "65463575-3456-4345-9787-146868523667",
"branch_digit": null,
"account_digit": "1",
"account_branch": "0001",
"account_number": "0000025",
"financial_institution_name": "QI SCD S.A."
},
"timestamp": "2026-01-29T20:03:44",
"description": "12431420 0134 71234489-3 99999999999 - Lucas Blau Mattos",
"destination": {
"name": "Lucas Blau Mattos",
"type": "checking_account",
"branch": "0001",
"purpose": "Crédito PIX em Conta",
"document": "99999999999",
"bank_ispb": "18236120",
"branch_digit": null,
"account_digit": "3",
"account_number": "71234489",
"financial_institution_name": "NU PAGAMENTOS - IP"
},
"end_to_end_id": "E32402502202601291954msTASDFEGS",
"transaction_key": "e89dc7af-165d-4534-b345-11345625d2c6",
"origin_transaction_key": "3415085f-1254-2153-a254-b1254215279e"
}
],
"requester_identifier_key": "1235cd2f-6345-4025-a334-a1435269fe11"
},
"status": "disbursed",
"webhook_type": "debt",
"event_datetime": "2026-01-29 20:03:45"
}
Falha no desembolso
TED
Em caso de falha no desembolso via TED
Webhook Body
{
"key": "<Debt Key>",
"status": "canceled",
"webhook_type": "debt",
"event_datetime": "2025-03-18 16:41:28",
"data": {
"ted_refusal": {
"transaction_key": "16faabfc-3876-437d-a4f6-aae17a1d68c9",
"description": "341 0000 000000-7 12345678900 - NOME DO EMPREGADO",
"origin": {
"account_key": "a1d2dea5-fa90-4676-a125-da355fdc3ed0",
"account_number": "00086",
"bank_code": "329",
"name": "ACCOUNT TRANSITORY",
"type": "payment_account",
"document": "32402502000135",
"branch_digit": null,
"account_digit": "8",
"branch": "0001"
},
"fee": 0,
"reason_enumerator": "agencia_conta_invalida",
"timestamp": "2022-11-07T14:36:05",
"amount": 483.6,
"reason": "Agência ou Conta Destinatária do Crédito Inválida",
"destination": {
"branch": "0000",
"account_number": "000000",
"name": "NOME DO EMPREGADO",
"purpose": "Crédito em Conta",
"type": "checking_account",
"branch_digit": null,
"document": "12345678900",
"bank_code": "341",
"account_digit": "7"
}
},
"cancel_reason": "ted_refusal"
}
}
PIX
Em caso de falha no desembolso via PIX
Webhook Body
{
"key": "<Debt Key>",
"status": "canceled",
"webhook_type": "debt",
"event_datetime": "2025-03-18 16:41:28",
"data": {
"cancel_reason": "pix_refusal",
"pix_refusal": {
"reason_enumerator": "invalid_document_number",
"reason": "CPF/CNPJ do usuário recebedor não é compatível com o titular da conta de destino."
}
}
}
Caso haja uma falha no desembolso, é crítico que haja uma atuação na proposta, pois a margem não é desaverbada automaticamente.
É necessário que o parceiro tome a decisão de entrar em contato com o tomador para pedir uma atualização dos dados bancários assim sendo possível reapresentar a o pagamento da dívida, ou que o parceiro realize a chamada de cancelamento permanente da dívida para desaverbar a margem consignável.
4 - Reapresentação de pagamento
Para retentar o desembolso da dívida, deve ser realizada a chamada a seguir atualizando tanto a data de desembolso quanto os dados bancários (caso a retentativa seja na mesma conta bancária, pode ser enviado somente o parâmetro de data de desembolso).
Os possíveis payloads de conta de desembolso constam no página de exemplos de payload de desembolso.
Request
Request
Request Body
{
"disbursement_date": "2025-03-19",
"disbursement_bank_accounts": [
{
"branch_number": "1232",
"account_digit": "4",
"account_number": "412412412",
"account_type": "checking_account",
"document_number": "<CPF DO TRABALHADOR>",
"bank_code": 184,
"ispb_number": "17298092",
"name": "<NOME DO TRABALHADOR>",
"percentage_receivable": 100
}
]
}
Response
Response Body
{
"disbursement_date": "2025-03-19",
"disbursement_accounts": [
{
"account_branch": "1232",
"account_digit": "4",
"account_number": "412412412",
"account_type": "checking_account",
"amount_receivable": null,
"created_at": "2022-05-24T14:51:46",
"digitable_line": null,
"disbursement_type": "ted",
"document_number": "37197645832",
"financial_institutions": {
"code_number": 184,
"ispb": 17298092,
"name": "BCO ITAÚ BBA S.A."
},
"financial_institutions_code_number": 184,
"is_pix_disbursement": false,
"ispb": "17298092",
"name": "Márcio e Catarina Gráfica Ltda",
"percentage_receivable": 50.0,
"pix_key": null,
"pix_transfer_key": null,
"pix_type": null,
"qr_code_key": null,
"retry_counter": 0,
"retry_vector": null,
"transaction_key": null,
"webhook_key": null
}
]
}
5 - Desaverbação
A desaverbação de um contrato é realizada através da rota de cancelamento permanente. Essa rota coloca um status final no contrato, o qual não é passível de retentativa e dispara a desaverbação da margem averbada.
Para realizar o cancelamento definitivo, deve ser utilizado o seguinte endpoint:
Request
Webhooks
Webhook Body
{
"key": "<Debt Key>",
"status": "canceled_permanently",
"webhook_type": "debt",
"event_datetime": "2025-03-18 16:41:28",
"data": {}
}
6 - Consulta de averbação
Para consultar os dados da averbação e os comprovantes de protocolo de averbação ou desaverbação, pode-se utilizar o endpoint:
É possível consultar os comprovantes de averbação, desaverbação e suspensão com este método. Os possíveis enumeradores para protocol_type estão disponíveis na tabela Tipos de protocolo
Response
Response Body
{
"data": [
{
"reservation_key": "310754e1-cef2-4b19-ba04-7b1c0b575276",
"document_number": "04142652117",
"registration_number": "SECAIXADEA00000000000000006258",
"employer_name": null,
"admission_date": null,
"employer_document_number": "04311093000126",
"external_key": "1d900fed-5ed2-4149-8702-f8dab595b590",
"contract_number": "179799466",
"inclusion_date": "2025-09-30",
"disbursement_date": "2025-02-06",
"contract_data": {
"iof": 227.64,
"periods": [
{
"amount": 338.22,
"due_date": "2025-04-20"
},
{
"amount": 338.22,
"due_date": "2025-05-20"
},
{
"amount": 338.22,
"due_date": "2025-06-20"
},
{
"amount": 338.22,
"due_date": "2025-07-20"
},
{
"amount": 338.22,
"due_date": "2025-08-20"
}
],
"total_amount": 6680.9,
"annual_cet_rate": 0.7176,
"contract_number": "179799466",
"disbursed_amount": 6090.9,
"monthly_cet_rate": 0.0461,
"disbursement_date": "2025-02-06",
"annual_interest_rate": 0.6163544955,
"disbursement_end_date": "2025-02-06",
"monthly_interest_rate": 0.0408
},
"reservation_type": "rollover",
"reservation_status": "reserved",
"protocols": {
"reservation": {
"receipt_url": "[URL]",
"receipt_data": {
"contract_number": "XXX0123456789",
"protocol_number": "21134056260",
"reservation_competence": "2026-03",
"installment_value": 468.6,
"protocol_type": "reservation",
"number_of_installments": 12,
"operation_datetime": "30/01/2026 20:21:22"
},
"protocol_key": "d32342f-369a-4e12-8634-4dfb494d3038"
},
"documents_inclusion": {
"receipt_data": {
"contract_number": "XXX0123456789",
"operation_datetime": "30/01/2026 20:21:29",
"number_of_installments": 12,
"protocol_number": "21134054053",
"installment_value": 468.6,
"protocol_type": "documents_inclusion"
},
"receipt_url": "[URL]",
"protocol_key": "ae018749-7982-4547-92aa-12455e8bafe7"
}
},
}
],
"pagination": {
"current_page": 1,
"next_page": 2,
"rows_per_page": 1
}
}
Anexos
Motivo de falha na averbação
| Enumerador | Descrição | Ação QI |
|---|---|---|
| monthly_interest_rate_exceeds_active_proposal | Há uma proposta ativa no app da CTPS do tomador enviada pela QI com taxa inferior à da tentativa de averbação | Teimosinha |
| margin_exceeded | Margem consignável excedida | Teimosinha |
| allowed_number_of_contracts_exceeded | Quantidade máxima de contratos excedida | Cancelamento da operação |
| employment_relationship_blocked | Vínculo bloqueado pelo tomador (é possível desbloquear pelo app da CTPS) | Cancelamento da operação |
Tipos de protocolo
| Enumerador | Descrição |
|---|---|
| reservation | Averbação |
| documents_inclusion | Envio de documentos (processo de enviar os documentos de formalização para DATAPREV) |
| suspension | Suspensão |
| deletion | Exclusão |