跳到主要内容

Webhooks de acompanhamento do QI Sign

Enquanto o tomador está na jornada de assinatura do QI Sign, a QI Tech pode enviar webhooks que mostram onde ele está: quando abre o link, quando conclui uma etapa e quando abandona a jornada. Use-os para retomar o contato com um tomador que parou no meio da jornada.

WEBHOOK_TYPE
document.signer.status_change

Estes webhooks não mudam o status da dívida. O resultado da formalização chega no webhook de assinatura ou no webhook de cancelamento.

Habilitação

Os webhooks de acompanhamento são opcionais. Para recebê-los, peça ao time de suporte da QI Tech a habilitação do evento document.signer.status_change na sua integração. A URL é a mesma dos demais webhooks; veja Configurando webhooks.

Atenção!

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

Quando ele chega​

data.typeQuando é enviado
signer_link_clickedO tomador abriu o link e iniciou a jornada.
signer_step_completedO tomador concluiu uma etapa que envia webhook. Hoje é a etapa enrich_personal_data, com os dados que ele informou.
signer_step_abandonedO tomador abandonou a jornada. next_signer_signature_step diz em que etapa ele parou.

Etapas da jornada​

Os campos completed_signer_signature_step e next_signer_signature_step usam os nomes das etapas. A ordem e as etapas presentes dependem da configuração da sua jornada.

EtapaO que o tomador faz
resume_operationLê o resumo da operação (valores, parcelas, taxas).
device_scanLibera o acesso ao dispositivo (câmera e localização).
face_recognitionTira a selfie com prova de vida.
personal_documentEnvia o documento de identificação.
enrich_personal_dataInforma ou confirma dados pessoais (e-mail, telefone, endereço, chave Pix).

Quando o tomador abandona antes de concluir a primeira etapa, completed_signer_signature_step não vem no webhook.

Corpo do webhook​

CampoTipoDescrição
keyuuidChave do envelope de assinatura no QI Sign. Não é a chave da dívida: use data.credit_operation_key.
statusstringStatus do signatário na assinatura. Sempre on_signature.
webhook_typestringSempre document.signer.status_change.
event_datetimestringData e hora do evento, no formato AAAA-MM-DDTHH:MM:SS.
dataobjectO signatário e o evento. Veja a tabela abaixo.

Atributos de data​

CampoTipoDescrição
iduuidChave do signatário no QI Sign.
typestringO evento: signer_link_clicked, signer_step_completed ou signer_step_abandoned.
namestringNome do signatário.
emailstringE-mail do signatário. Pode ser null.
statusstringStatus do signatário na assinatura. Sempre on_signature.
document_numberstringCPF do signatário, com máscara.
credit_operation_keyuuidChave da dívida (CCB). Use este campo para ligar o evento à dívida.
completed_signer_signature_stepstringÚltima etapa concluída. Presente em signer_step_completed e em signer_step_abandoned.
next_signer_signature_stepstringEtapa em que o tomador parou. Presente só em signer_step_abandoned.
enrich_personal_dataobjectDados informados na etapa enrich_personal_data. Presente em signer_step_completed dessa etapa.
phoneobjectTelefone do signatário. Presente em signer_step_abandoned.
addressobjectEndereço do signatário. Presente em signer_step_abandoned quando o tomador já o informou.
pix_keystringChave Pix do signatário. Presente em signer_step_abandoned quando o tomador já a informou.

Atributos de enrich_personal_data​

CampoTipoDescrição
emailstringE-mail do signatário.
phoneobjectTelefone. Veja Atributos de phone.
addressobjectEndereço. Veja Atributos de address.
pix_keystringChave Pix do signatário.

Atributos de phone​

CampoTipoDescrição
numberstringNúmero do telefone, sem DDD.
area_codestringDDD.
international_dial_codestringCódigo do país. Ex.: 55.

Atributos de address​

CampoTipoDescrição
ufstringSigla do estado.
citystringCidade.
streetstringLogradouro.
numberstringNúmero.
complementstringComplemento. Pode não vir.
neighborhoodstringBairro.
postal_codestringCEP, com máscara.

Exemplos​

{
"key": "e299f7c2-03fa-4ea9-a2bc-e1a4e44440ac",
"data": {
"id": "d1c37283-8ac0-4aaf-9ffe-0f0071d401b9",
"name": "JOAO DA SILVA",
"type": "signer_link_clicked",
"email": null,
"status": "on_signature",
"document_number": "969.698.790-03",
"credit_operation_key": "5ae2c008-44c1-4435-bbfa-094a4b11d962"
},
"status": "on_signature",
"webhook_type": "document.signer.status_change",
"event_datetime": "2026-10-02T16:25:02"
}

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.