Skip to main content

Webhook de cancelamento por regra de assinatura

A QI Tech envia este webhook quando uma regra de assinatura do QI Sign reprova a jornada do tomador. A dívida (CCB) é cancelada antes do desembolso. O webhook diz qual regra reprovou e traz o dossiê do signatário, para que você entenda a reprovação sem abrir um chamado.

Os motivos de cancelamento e quem decide cada um estão em Regras de negócio.

Atenção!

Os webhooks da QI Tech não devem ser mapeados de forma restrita. Campos adicionais podem ser incluídos nos payloads.

Os dois formatos​

O formato muda conforme o produto da dívida, e só um deles traz o dossiê:

Dívidawebhook_typeTraz signers e signed_contract_url
Consignado privado (originação leilão), previdência privada e cartão consignadolaas.credit_operation.status_changeSim
Demais dívidas emitidas pelo POST /debtdebtNão

No formato debt, data traz cancel_reason, cancel_reason_enumerator, reason_description e requester_identifier_key. Para ver as evidências de uma dívida nesse formato, fale com o time de suporte da QI Tech.

Corpo do webhook​

CampoTipoDescrição
keyuuidChave da dívida (CCB).
statusstringSempre canceled.
webhook_typestringlaas.credit_operation.status_change ou debt.
event_datetimestringData e hora do cancelamento, no formato AAAA-MM-DD HH:MM:SS.
dataobjectO motivo do cancelamento e o dossiê. Veja a tabela abaixo.

Atributos de data​

CampoTipoDescrição
cancel_reasonstringTexto do motivo. Para reprovação por regra de assinatura: Operação cancelada por regra de assinatura do solicitante.
cancel_reason_enumeratorstringCódigo do motivo. Para reprovação por regra de assinatura: rule_analysis_status.
reason_descriptionstringA regra de assinatura que reprovou. Veja Valores de reason_description.
operation_typestringO tipo da operação. Ex.: structured_operation. Só no formato laas.credit_operation.status_change.
signed_contract_urlstringO relatório da jornada em PDF, gerado pelo QI Sign. A CCB não foi assinada. Só no formato laas.credit_operation.status_change.
signersarrayO dossiê de cada signatário. Veja Dossiê do signatário. Só no formato laas.credit_operation.status_change.
requester_identifier_keystringO identificador que você enviou na emissão da dívida. Só no formato debt.

No cancelamento, o dossiê não traz ip_address, similarity_score, biometry_analysis_reference nem images.simplified_dossier. O IP do signatário está em device_data.ip.

As URLs expiram

As URLs de signed_contract_url e de signers[].images expiram cerca de 24 horas depois do envio do webhook. Baixe e guarde os arquivos ao receber o webhook.

Valores de reason_description​

reason_description é o nome da regra de assinatura configurada no QI Sign que reprovou a jornada. A lista depende das regras da sua integração. Valores frequentes:

reason_descriptionA regra reprovou porque
face_validationA validação facial do tomador não atingiu a pontuação mínima.
ocr_flagsA leitura do documento encontrou um indicador reprovado em document.ocr.
fraudulent_documentO documento de identificação foi considerado fraudulento.

Para conferir a reprovação, leia no dossiê o bloco da regra: biometry para face_validation, document.ocr[].document_data para ocr_flags e fraudulent_document.

Exemplo — dívida cancelada por regra de validação facial​

O tomador enviou um RG físico e a validação facial reprovou (face_validation.score 3). O dossiê traz os dados extras da jornada (document.ocr e liveness.flags). As URLs assinadas estão encurtadas.

{
"key": "2d7b9e4f-6a1c-4f3e-8b5d-0c9a7e2f1b64",
"status": "canceled",
"webhook_type": "laas.credit_operation.status_change",
"event_datetime": "2026-11-18 10:40:48",
"data": {
"cancel_reason": "Operação cancelada por regra de assinatura do solicitante",
"cancel_reason_enumerator": "rule_analysis_status",
"reason_description": "face_validation",
"operation_type": "structured_operation",
"signed_contract_url": "https://qisign-dossiers-bucket-production.s3.amazonaws.com/6c1e8a3f-2b9d-4e7a-a5c0-3f8d1b6e9c27.pdf?AWSAccessKeyId=...&Signature=...&Expires=1795085248",
"signers": [
{
"id": "e8a2c4f6-9b1d-4e3a-b7c5-2d0f6a8e1c39",
"signer_data": {
"id": "e8a2c4f6-9b1d-4e3a-b7c5-2d0f6a8e1c39",
"name": "MARIA SOUZA",
"email": "maria.souza@exemplo.com",
"phone": {
"number": "999999999",
"area_code": "11",
"international_dial_code": "55"
},
"address": {
"uf": "SP",
"city": "São Paulo",
"number": "100",
"street": "Rua Exemplo",
"postal_code": "01000-000",
"neighborhood": "Centro"
},
"pix_key": "+5511999999999",
"birthdate": "1992-12-22",
"document_number": "123.456.789-09",
"document_submission_method": "email",
"authentication_submission_method": "whatsapp"
},
"images": {
"face_image_url": "https://qisign-face-images-bucket-production.s3.amazonaws.com/5a9c1e7b-3d4f-4b2a-9e8c-7f1d0b6a2c53.jpeg?AWSAccessKeyId=...&Signature=...&Expires=1795085248",
"document_front_url": "https://qisign-personal-documents-bucket-production.s3.amazonaws.com/9d3f7b1e-5c2a-4e8d-a6b4-1e0c8f2d7a95.jpeg?AWSAccessKeyId=...&Signature=...&Expires=1795085248",
"document_back_url": "https://qisign-personal-documents-bucket-production.s3.amazonaws.com/1b6e4a8c-7f2d-4c9b-8a3e-5d0f9c1b4e72.jpeg?AWSAccessKeyId=...&Signature=...&Expires=1795085248",
"document_front_template": "rg_front",
"document_back_template": "rg_back"
},
"biometry": {
"face_validation": {
"score": 3,
"provider": "qitech",
"available": true,
"recommendation": "reprove"
},
"fraud_base_flag": false,
"face_validation_score": 3,
"face_validation_available": true
},
"document": {
"template": "rg_front",
"face_match_score": 100,
"ocr": [
{
"file_type": "jpeg",
"template_type": "rg_front",
"document_data": {
"name": "MARIA SOUZA",
"is_copy": false,
"birthdate": "1992-12-22",
"cpf_number": "123.456.789-09",
"has_disability": false,
"place_of_birth": "SAO PAULO-SP",
"expiration_date": "2035-06-24",
"found_state_text": true,
"found_footer_text": true,
"found_header_text": true,
"is_child_document": false,
"all_edges_detected": true,
"cpf_signer_mismatch": false,
"has_physical_damage": false,
"face_tampering_detected": false,
"screen_display_detected": false,
"text_tampering_detected": false,
"found_illeterate_person_text": false,
"has_missing_document_section": false,
"has_textual_legibility_issues": false
}
},
{
"file_type": "jpeg",
"template_type": "rg_back",
"document_data": {
"is_copy": false,
"father_name": "JOSE SOUZA",
"mother_name": "ANA SOUZA",
"issuance_date": "2025-06-24",
"has_disability": false,
"found_side_text": true,
"has_missing_data": false,
"found_footer_text": true,
"all_edges_detected": true,
"has_physical_damage": false,
"screen_display_detected": false,
"text_tampering_detected": false,
"has_missing_document_section": false,
"has_textual_legibility_issues": false
}
}
]
},
"liveness": {
"result": "live",
"flags": {
"multiple_people": false,
"total_execution_time": 29.954
}
},
"device_data": {
"ip": "203.0.113.25",
"model": "iPhone",
"user_agent": "Mozilla/5.0 (iPhone; CPU iPhone OS 18_7 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/18.7 Mobile/15E148 Safari/604.1",
"coordinates": [-46.6333, -23.5505]
},
"locations": [],
"link_first_clicked_at": "2026-11-18T00:09:19Z",
"signed_at": "2026-11-18T10:39:58Z"
}
]
}
}

Erros​

Este webhook não devolve erro ao originador. A sua URL deve responder com um status 2xx em até 5 segundos. O comportamento de entrega e o reenvio estão em Configurando webhooks e Reenvio de notificações.