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",
"reservation_type": "new_credit"
},
"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_type": "laas.private_payroll.reservation_status_change",
"data": {
"reservation_status": "reserved",
"reservation_type": "new_credit",
"warranty" : {
"severance_pay_rate":null,
"severance_fine":5522.06,
"fgts_balance":10000
}
},
"key": "<credit_operation_key>",
"event_datetime": "2025-04-09T20:00:20Z",
"status": "reserved"
}
Falha na averbação
Caso haja uma falha na averbação, será enviado um webhook com a crítica da DATAPREV. 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. O webhook e a tabela completa de motivos de falha estão documentados em Averbação de Novos Empréstimos — Erros de Averbação.
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"
}
Existem duas rotinas automáticas de cancelamento permanente acionadas pela QI Tech:
- Esgotamento das opções de desembolso.
Todas as operações que não forem desembolsadas até a data final de desembolso serão caceladas permanentemente no dia seguinte á data final. Operações originadas via leilão possuem 10 opções de desembolso desde a data do envio da proposta.
- Operação averbada e não desembolsada depois de 5 dias.
Caso uma operação fique averbada e não desembolsada por 5 dias corridos, ocorrerá o cancelamento permantente.
Webhooks de cancelamento permanente
- Esgotamento das opções de desembolso
- Operação averbada e não desembolsada depois de 5 dias
{
"key": "d7ba5332-3675-12a6-9e07-8afd25ffcfd0",
"data": {
"cancel_reason": "Operação não desembolsada já passou da última data de desembolso",
"cancel_reason_enumerator": "expired_disbursement_date"
},
"status": "canceled_permanently",
"webhook_type": "laas.credit_operation.status_change",
"event_datetime": "2026-02-12 00:53:16"
}
{
"key": "d7ba5332-3675-12a6-9e07-8afd25ffcfd0",
"data": {
"cancel_reason": "Operação excedeu o prazo máximo em averbação sem desembolso",
"cancel_reason_enumerator": "exceeded_max_days_reserved_not_disbursed"
},
"status": "canceled_permanently",
"webhook_type": "laas.credit_operation.status_change",
"event_datetime": "2026-02-12 00:53:16"
}
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
A consulta dos dados da averbação e dos comprovantes de protocolo de averbação/desaverbação por external_key foi movida para Averbação de Novos Empréstimos — Consulta de Reservas.
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 |
| warranty_exceeded | Coberturas disponíveis excedidas | Teimosinha |
| invalid_cover_amount | Valor da cobertura não corresponde ao percentual do valor de emissão esperado | Teimosinha |
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 |