Manual Consignado Privado - Acompanhamento da Operação de crédito
1. Formalização
Após vencer o leilão interno, o parceiro deve aguardar o recebimento do webhook de formalização, indicando que o tomador finalizou o fluxo de assinatura do QI Sign.
{
"key": "<Debt Key>",
"status": "signed",
"signers": [
{
"id": "3271efd3-89ba-43aa-b032-af9a459e6096",
"images": {
"face_image_url": "https://qisign-face-images-bucket-sandbox.s3.amazonaws.com/fad7f924-d210-4ec4-9565-a57662a0a65a.jpeg",
"document_back_url": "https://qisign-personal-documents-bucket-sandbox.s3.amazonaws.com/8c7b68ba-07ad-4188-82ae-679833b2843b.jpeg",
"document_front_url": "https://qisign-personal-documents-bucket-sandbox.s3.amazonaws.com/f63cd291-5668-4926-be5d-9290aeda3f6e.jpeg",
"document_back_template": "cnh_back",
"document_front_template": "cnh_front"
},
"biometry": {
"face_validation": {
"score": 80,
"provider": "qitech",
"available": true
},
"fraud_base_flag": false
},
"document": {
"template": "cnh_front",
"face_match_score": 100
},
"liveness": {
"result": "live"
},
"signed_at": "2025-04-09T19:59:39Z",
"ip_address": "182.224.219.198",
"signer_data": {
"name": "Nome Trabalhador",
"email": "exemplo@qitech.com.br",
"phone": {
"number": "829549234",
"area_code": "11",
"international_dial_code": "55"
},
"address": {
"uf": "SP",
"city": "Sao Paulo",
"number": "123",
"street": "Rua tal do sal",
"complement": "Ap 23",
"postal_code": "00000-000",
"neighborhood": "Pinheiros"
},
"pix_key": "pix03@pix03.com",
"birthdate": "1996-03-13",
"document_number": "504.856.400-66",
"document_submission_method": "email",
"authentication_submission_method": "sms"
}
}
],
"webhook_type": "laas.credit_operation.status_change",
"event_datetime": "2025-04-09 20:00:19",
"signed_contract_url": "https://storage.googleapis.com/sandbox-doc-api/documents/9b55450e-fca5-44f2-9118-5851ed4bd92e/RESTAURANTEBEBBER-TRABALHADOR_SICQ-CCB-0000195364-2230409195718_signed.pdf"
}
2. Confirmação da proposta
Um segundo webhook é enviado informando que a operação está aguardando a chamada de autorização de averbaçã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 via leilão, isto pode ser feito através do endpoint de cancelamento permanente, da mesma forma que é feito no item 6 - Desaverbação.
Se a operação foi originada no fluxo ativo, o cancelamento deverá ser feito através do endpoint de que consta neste manual.
O campo external_key é o UUID da operação de crédito, o mesmo que debt_key e credit_operation_key.
3 - 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"
}
4 - Desembolso
Após o sucesso na averbação, a operação seguirá automaticamente para o desembolso.
Sucesso no desembolso
Webhook Body
Falha no desembolso
Webhook Body
{
"key": "<UUID>",
"data": {
"cancel_reason": "A conta de destino encontra-se bloqueada.",
"cancel_reason_enumerator": "blocked_account"
},
"status": "canceled",
"webhook_type": "laas.credit_operation.status_change",
"event_datetime": "2025-10-12 09:54:46"
}
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.
5 - Reapresentação da 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. Para essa API, foi alterado o nome do payload de disbursement_bank_accounts para disbursement_account.
Para reapresentar uma dívida deve-se realizar uma requisição utilizando a auction_proposal_key.
/private_payroll_auction/auction_proposal/{auction_proposal_key}/change_disbursement_datePATCH{
"disbursement_date": "2025-12-12",
"disbursement_account": {
"document_number": "31233261000185",
"name": "Jorge Augusto Salgado Salhani",
"pix_key": "2f205c99-3161-4120-badd-854039d12de6",
"pix_transfer_type": "key"
}
}
6 - Desavebação
Para cancelar permanentemente a operação e desaverbar a margem, deve ser realizada a chamada:
Request
/private_payroll_auction/auction_proposal/{auction_proposal_key}/cancelPATCHResponse
Response Body: Proposta cancelada
{
"auction_proposal_key": "814e7ed3-4080-4cae-a853-8e12812817ea",
"status": "cancelled"
}
Em caso de sucesso na alteração será retornado status 200.
Caso haja algum erro no formato do payload enviado para a alteração será retornado um erro de schema invalido
7 - 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:
Request
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": {
"protocol_key": "1d900fed-5ed2-4149-8702-f8dab595b590",
"receipt_url": "https://storage.googleapis.com/live-doc-api/documents/2515c951-748e7c573069/Comprovantedeoperacao.pdf",
"receipt_data": {
"protocol_type": "reservation",
"contract_number": "1234567890ABC",
"protocol_number": "01239048475",
"installment_value": 338.22,
"operation_datetime": "16/01/2026 22:45:30",
"number_of_installments": 5,
"reservation_competence": "2026-02"
}
}
}
],
"pagination": {
"current_page": 1,
"next_page": 2,
"rows_per_page": 1
}
}
Anexos
Detalhamento reapresentação de desembolso
| Campo | Tipo | Descrição |
|---|---|---|
disbursement_date | string | Nova data de desembolso no formato YYYY-MM-DD, não obrigatória |
disbursement_account | dict | dados da conta de desembolso, não obrigatório |
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 |