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. Averbação
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 cancelar a operação, deve ser realizada a chamada:
Request
/private_payroll_auction/auction_proposal/{auction_proposal_key}/cancel
PATCH
Response
Response Body: Proposta cancelada
{
"auction_proposal_key": "814e7ed3-4080-4cae-a853-8e12812817ea",
"status": "cancelled"
}
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 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. Desembolso
Após o sucesso na averbação, a operação seguirá para o desembolso, no caso de sucesso será enviado um webhook:
Webhook Body
{
"key": "<UUID>",
"data": {
"installments": [
{
"due_date": "2025-12-28",
"total_amount": 315.02,
"installment_key": "<UUID>",
"pre_fixed_amount": 212.35873015,
"installment_number": 1,
"principal_amortization_amount": 102.66126985
},
{
"due_date": "2026-01-28",
"total_amount": 315.02,
"installment_key": "<UUID>",
"pre_fixed_amount": 76.17371273,
"installment_number": 2,
"principal_amortization_amount": 238.84628727
},
{
"due_date": "2026-02-28",
"total_amount": 315.02,
"installment_key": "<UUID>",
"pre_fixed_amount": 59.12264515,
"installment_number": 3,
"principal_amortization_amount": 255.89735485
},
{
"due_date": "2026-03-28",
"total_amount": 315.02,
"installment_key": "<UUID>",
"pre_fixed_amount": 36.77641144,
"installment_number": 4,
"principal_amortization_amount": 278.24358856
},
{
"due_date": "2026-04-28",
"total_amount": 315.02,
"installment_key": "<UUID>",
"pre_fixed_amount": 20.98850053,
"installment_number": 5,
"principal_amortization_amount": 294.03149947
}
],
"disbursement_type": "pix",
"transaction_receipts": [
{
"fee": 0,
"url": "<URL>",
"amount": 1151.15,
"origin": {
"name": "QI SOCIEDADE DE CRÉDITO DIRETO S.A.",
"type": "payment_account",
"branch": "0001",
"document": "32402502000135",
"bank_code": "329",
"account_key": "<UUID>",
"branch_digit": null,
"account_digit": "1",
"account_branch": "0001",
"account_number": "1234567",
"financial_institution_name": "QI SCD S.A."
},
"timestamp": "2025-10-14T13:26:52",
"description": "1234567 - Roberto Alves",
"destination": {
"name": "Roberto Alves",
"type": "checking_account",
"branch": "0001",
"purpose": "Crédito PIX em Conta",
"document": "12345678911",
"bank_ispb": "12121212",
"branch_digit": null,
"account_digit": "2",
"account_number": "123456",
"financial_institution_name": "BANCO"
},
"end_to_end_id": "<EEID>",
"transaction_key": "<UUID>",
"origin_transaction_key": "<UUID>"
}
],
"requester_identifier_key": "<UUID>"
},
"status": "opened",
"webhook_type": "laas.credit_operation.status_change",
"event_datetime": "2025-10-14 13:26:52"
}
No caso de falha no desembolso, será enviado um webhook de cancelamento da operação:
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"
}
Nesta situação, o parceiro deve tomar a decisão de reapresentar o pagamento com novos dados bancários, ou cancelar a proposta para desaverbar a margem averbada:
Caso não haja a intenção de cancelar a operação, é crítico que seja comandada a desaverbação da margem. Se não houver uma reapresentação do pagamento, a QI comandará a desaverbação automaticamente depois de 7 dias.
5. Reapresentação da dívida
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_date
PATCH
As informações sobre os formatos de disbursement_account permitidos são os mesmos que estão na documentação em API Reference - Lending-as-a-Service - Dívidas - Emissão de dívida - Exemplo de payloads de desembolso. Para essa API, foi alterado o nome do payload de disbursement_bank_accounts para disbursement_account. Além disso, há a possibilidade de alterar a data de desembolso, basta passar o campo disbursement_date com a nova data. Segue um exemplo abaixo:
{
"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"
}
}
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 |
Response
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