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": "<credit_operation_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"
}
Em casos de falha na assinatura, o parceiro irá receber um webhook neste modelo.
{
"key": "e8e28023-fa00-4d12-a410-ede4157957ea",
"data": {
"cancel_reason": "Validação facial não alcançou a pontuação mínima permitida",
"cancel_reason_enumerator": "face_validation_score"
},
"status": "canceled",
"webhook_type": "laas.credit_operation.status_change",
"event_datetime": "2025-11-28 17:35:07"
}
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": "<credit_operation_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": "<credit_operation_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": "<credit_operation_key>",
"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
{
"webhook": {
"key": "b0e263d0-3f78-4d40-835d-225321cbc0db",
"data": {
"installments": [
{
"due_date": "2026-04-28",
"total_amount": 2723.11,
"installment_key": "05d3f492-bb09-4b2f-9d6a-a2d8890fcfe8",
"pre_fixed_amount": 2723.11,
"installment_number": 1,
"principal_amortization_amount": 0.0
},
{
"due_date": "2026-05-28",
"total_amount": 2723.11,
"installment_key": "2c90a77e-2aac-4b18-a092-6435615cc99b",
"pre_fixed_amount": 1974.82423911,
"installment_number": 2,
"principal_amortization_amount": 748.28576089
},
{
"due_date": "2026-06-28",
"total_amount": 2723.11,
"installment_key": "746b1034-c4cf-4388-8a80-9dcea92550c5",
"pre_fixed_amount": 1362.47207785,
"installment_number": 3,
"principal_amortization_amount": 1360.63792215
},
{
"due_date": "2026-07-28",
"total_amount": 2723.11,
"installment_key": "caffce5c-0b8b-419c-bb66-3419ad9d8cf0",
"pre_fixed_amount": 1223.14316953,
"installment_number": 4,
"principal_amortization_amount": 1499.96683047
},
{
"due_date": "2026-08-28",
"total_amount": 2723.11,
"installment_key": "63bf5117-7d44-4a7c-9ac8-a061f769b477",
"pre_fixed_amount": 1158.2555271,
"installment_number": 5,
"principal_amortization_amount": 1564.8544729
},
{
"due_date": "2026-09-28",
"total_amount": 2723.11,
"installment_key": "0c99c88e-b510-432d-ad8b-661a1bb2da1d",
"pre_fixed_amount": 1046.54167269,
"installment_number": 6,
"principal_amortization_amount": 1676.56832731
},
{
"due_date": "2026-10-28",
"total_amount": 2723.11,
"installment_key": "64240d5f-6413-4119-b527-636080a81fb2",
"pre_fixed_amount": 895.94579894,
"installment_number": 7,
"principal_amortization_amount": 1827.16420106
},
{
"due_date": "2026-11-28",
"total_amount": 2723.11,
"installment_key": "0e73e4f3-71f9-429d-8e9c-5ef41702db83",
"pre_fixed_amount": 796.41268475,
"installment_number": 8,
"principal_amortization_amount": 1926.69731525
},
{
"due_date": "2026-12-28",
"total_amount": 2723.11,
"installment_key": "1410ad56-890f-49b3-85e5-b8eb95b54910",
"pre_fixed_amount": 636.89650888,
"installment_number": 9,
"principal_amortization_amount": 2086.21349112
},
{
"due_date": "2027-01-28",
"total_amount": 2723.11,
"installment_key": "08364a82-e805-4446-91ec-df982815a676",
"pre_fixed_amount": 509.93381955,
"installment_number": 10,
"principal_amortization_amount": 2213.17618045
},
{
"due_date": "2027-02-28",
"total_amount": 2723.11,
"installment_key": "fdad3297-a729-4603-8d42-ed30604d93a3",
"pre_fixed_amount": 351.93673682,
"installment_number": 11,
"principal_amortization_amount": 2371.17326318
},
{
"due_date": "2027-03-28",
"total_amount": 2723.11,
"installment_key": "a3d78a2e-01e9-4c04-8cea-3106a52e5b54",
"pre_fixed_amount": 164.42776478,
"installment_number": 12,
"principal_amortization_amount": 2558.68223522
}
],
"disbursement_type": "pix",
"transaction_receipts": [
{
"fee": 0,
"url": {url},
"amount": 19316.77,
"origin": {
"name": "QI SOCIEDADE DE CRÉDITO DIRETO S.A.",
"type": "payment_account",
"branch": "0001",
"document": "32402502000135",
"bank_code": "329",
"account_key": "18bd2ed6-bca7-4cc8-806c-a45a8d9ae804",
"branch_digit": null,
"account_digit": "7",
"account_branch": "0001",
"account_number": "8022858",
"financial_institution_name": "QI SOCIEDADE DE CRÉDITO DIRETO S.A."
},
"timestamp": "2026-02-18T14:23:25",
"description": "60701190 5807 20467-1 24182533410 - Mock Person Name",
"destination": {
"name": "Mock Person Name",
"type": "checking_account",
"branch": "5807",
"purpose": "Crédito PIX em Conta",
"document": "12345678909",
"bank_ispb": "60701190",
"branch_digit": null,
"account_digit": "1",
"account_number": "20467",
"financial_institution_name": "ITAÚ UNIBANCO S.A."
},
"end_to_end_id": "E324025022026021814222AHLHi3btjz",
"transaction_key": "000531c1-ecb7-47f8-947f-51e467bd58b7",
"origin_transaction_key": "4600743f-13e3-47d2-a8c1-2a71c097409a"
}
],
"requester_identifier_key": "b0e263d0-3f78-4d40-835d-225321cbc0db"
},
"status": "opened",
"webhook_type": "laas.credit_operation.status_change",
"event_datetime": "2026-02-18 14:23:24"
}
}
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:
É 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
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": {
"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
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 |
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 |