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 - Autorização de averbação
Esta etapa é opcional no fluxo ativo, a integração pode ser configurada para que as operações sigam para as próximas etapas assim que for finalizada a formalização, caso contrário, será enviado um webhook informando que a operação está aguardando uma chamada de autorização para dar continuidade ao fluxo.
Webhooks
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"
}
Em caso de sucesso na autorização da reserva, ela passará automaticamente para a etapa de averbação.
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"
}
Cancelamento da operação
Para não prosseguir com a averbação, é necessário cancelar a operação.
Se a operação foi originada diretamente pelo parceiro, isto pode ser feito através do endpoint de cancelamento permanente, da mesma forma que é feito no item 8 - 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 reserva que foi criada no item 4 - Criação da reserva.
O mesmo que debt_key e credit_operation_key.
2 - Consulta ao SCR
Em até 120 dias após o lançamento do Consignado do Trabalhador, é obrigatório realizar uma consulta ao SCR. Nela, recebemos informações sobre o histórico de créditos do trabalhador, nos atentando especialmente para a quantidade de contratos ativos de Crédito Pessoal e/ou Crédito Consignado.
A consulta ao SCR é feita automaticamente pelo sistema após a autorização da averbação.
Webhooks
Webhook Body
{
"key": "<Debt Key>",
"status": "approved",
"webhook_type": "laas.private_payroll.credit_analysis",
"event_datetime": "2025-04-04 17:47:32",
"data": {
"scr_data": [
{
"reference_date": "2025-02",
"operation_items": [
{
"modality": "02",
"modality_description": "Empréstimos",
"submodality": "12",
"submodality_description": "Microcrédito",
"domain": "310",
"domain_group": "Créditos baixados como prejuízo",
"domain_description": "Créditos baixados como prejuízo até 12 meses",
"value": 96277,
"linked_to_foreign_currency": false
},
{
"modality": "02",
"modality_description": "Empréstimos",
"submodality": "18",
"submodality_description": "Cartão de crédito - não migrado",
"domain": "310",
"domain_group": "Créditos baixados como prejuízo",
"domain_description": "Créditos baixados como prejuízo até 12 meses",
"value": 310812,
"linked_to_foreign_currency": false
},
{
"modality": "02",
"modality_description": "Empréstimos",
"submodality": "03",
"submodality_description": "Crédito pessoal - sem consignação em folha de pagamento",
"domain": "310",
"domain_group": "Créditos baixados como prejuízo",
"domain_description": "Créditos baixados como prejuízo até 12 meses",
"value": 102523,
"linked_to_foreign_currency": false
},
{
"modality": "02",
"modality_description": "Empréstimos",
"submodality": "03",
"submodality_description": "Crédito pessoal - sem consignação em folha de pagamento",
"domain": "140",
"domain_group": "Créditos a vencer",
"domain_description": "Créditos a vencer de 91 a 180 dias",
"value": 34623,
"linked_to_foreign_currency": false
},
{
"modality": "02",
"modality_description": "Empréstimos",
"submodality": "03",
"submodality_description": "Crédito pessoal - sem consignação em folha de pagamento",
"domain": "165",
"domain_group": "Créditos a vencer",
"domain_description": "Créditos a vencer de 721 a 1080 dias",
"value": 8913,
"linked_to_foreign_currency": false
},
{
"modality": "02",
"modality_description": "Empréstimos",
"submodality": "03",
"submodality_description": "Crédito pessoal - sem consignação em folha de pagamento",
"domain": "170",
"domain_group": "Créditos a vencer",
"domain_description": "Créditos a vencer de 1081 a 1440 dias",
"value": 4110,
"linked_to_foreign_currency": false
},
{
"modality": "02",
"modality_description": "Empréstimos",
"submodality": "03",
"submodality_description": "Crédito pessoal - sem consignação em folha de pagamento",
"domain": "180",
"domain_group": "Créditos a vencer",
"domain_description": "Créditos a vencer de 1801 a 5400 dias",
"value": 1095,
"linked_to_foreign_currency": false
},
{
"modality": "02",
"modality_description": "Empréstimos",
"submodality": "03",
"submodality_description": "Crédito pessoal - sem consignação em folha de pagamento",
"domain": "160",
"domain_group": "Créditos a vencer",
"domain_description": "Créditos a vencer de 361 a 720 dias",
"value": 18059,
"linked_to_foreign_currency": false
},
{
"modality": "02",
"modality_description": "Empréstimos",
"submodality": "03",
"submodality_description": "Crédito pessoal - sem consignação em folha de pagamento",
"domain": "175",
"domain_group": "Créditos a vencer",
"domain_description": "Créditos a vencer de 1441 a 1800 dias",
"value": 1753,
"linked_to_foreign_currency": false
},
{
"modality": "02",
"modality_description": "Empréstimos",
"submodality": "18",
"submodality_description": "Cartão de crédito - não migrado",
"domain": "270",
"domain_group": "Créditos vencidos",
"domain_description": "Créditos vencidos de 301 a 360 dias",
"value": 42950,
"linked_to_foreign_currency": false
}
],
"indirect_risk": 0,
"assumed_coobligation": 0.0,
"receive_coobligation": 0.0,
"financial_institution_count": 4,
"percentage_of_processed_documents": 61.13,
"percentage_of_processed_volume": 95.45,
"start_relationship_date": "2023-04-12",
"operation_count": 10,
"subjudice_operations_count": 0,
"subjudice_operations_value": 0,
"disagreement_operations_count": 0,
"disagreement_operations_value": 0,
"source": "CACHE"
}
]
}
}
Webhook Body
{
"key": "<Debt Key>",
"data": {
"cancel_reason": "Análise de crédito reprovada",
"cancel_reason_enumerator": "private_payroll.credit_analysis_reproved"
},
"status": "canceled",
"webhook_type": "laas.credit_operation.status_change",
"event_datetime": "2025-04-09 21:22:56"
}
Simulando cenários de sucesso e falha na consulta ao SCR em Sandbox:
A simulação de cenários é baseada no primeiro dígito do CPF informado na operação.
- Para os demais CPFs, será retornado uma resposta assíncrona de sucesso.
| Início do cpf | Enumerador | Descrição | Ação |
|---|---|---|---|
| 5 | private_payroll.credit_analysis_reproved | Credit analysis reproved | cancel |
3 - Averbação
Webhooks
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 por margem exedida
Se uma reserva com categoria de nova matrícula receber margem excedida na tentativa de averbação, o status do pedido de averbação ficará como "aguardando ação do parceiro", e será enviado um webhook no seguinte formato para informar o ocorrido:
Webhook Body
{
"key": "<Debt Key>",
"status": "pending_requester_action",
"webhook_type": "private_payroll_margin_exceeded_for_new_registration",
"event_datetime": "2025-03-18 16:41:28",
"data": {
"enumerator": "margin_exceeded_for_new_registration",
"description": "The margin for this reservation has been exceeded. Reservation Amount: 551.18",
}
}
4 - 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:
Webhooks
Webhook Body
{
"key": "<Debt Key>",
"status": "canceled_permanently",
"webhook_type": "debt",
"event_datetime": "2025-03-18 16:41:28",
"data": {}
}
5 - 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."
}
}
}
6 - Reapresentação de Pagamento
Altera a data de desembolso sem afetar os valores financeiros da operação.
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
}
]
}