Manual Consignado Privado - Averbação e Desembolso
- Formalização Externa (anterior)
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 |