Documentos e Assinatura

Esta seção detalha o fluxo de geração de documentos e o processo de assinatura eletrônica, seja via fluxo externo ou via Qi Sign.

Obs

Caso o cliente esteja integrado no fluxo de assinatura do QISign, os itens dessa secção são opcionais.

1. Webhook de Geração de Documentos

Após a criação da operação, os documentos (payroll_card_term e withdrawal_operation_term) são gerados assincronamente. A API envia um webhook para cada documento notificando a mudança de status do documento.

Atenção

Caso o cliente não utilize o QISign, o cliente deve implementar o tratamento deste webhook para capturar as URLs dos documentos e direcionar o beneficiário para a assinatura através da certificadora externa escolhida.

WEBHOOK TYPE

laas.payroll_card_reservation.attached_document.status_change

Estrutura Geral do Webhook

Campo	Tipo	Descrição
key	string	Chave do documento
status	string	Novo status do documento
webhook_type	string	`laas.payroll_card_reservation.attached_document.status_change`
event_datetime	string	Data e hora do evento
data	object	Objeto contendo dados relevantes para a mudança de status

Cenários

A. Documento Gerado (generated)

Ocorre quando os documentos são gerados.

Retorna os dados do documento.

Exemplo de Payload

{
    "key": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "status": "generated",
    "webhook_type": "laas.payroll_card_reservation.attached_document.status_change",
    "event_datetime": "2025-01-15T14:30:00Z",
    "data": {
        "payroll_card_reservation_key": "910e8de5-16af-4bc5-8ee1-4a0652ca0cbf",
        "document_key": "332017f4-a0d6-463a-8557-e925a9485251",
        "document_type": "payroll_card_term",
        "document_url": "https://storage.googleapis.com/example_document.pdf",
    }
}

Próximo Passo

Após receber os webhooks com status generated, o cliente deve apresentar os documentos ao usuário final para coleta da assinatura.

B. Assinatura Pendente (pending_signature)

Ocorre quando todos os documentos foram gerados e estão prontos para serem assinados.

Retorna os dados do documento.

Exemplo de Payload

{
    "key": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "status": "pending_signature",
    "webhook_type": "laas.payroll_card_reservation.attached_document.status_change",
    "event_datetime": "2025-01-15T14:30:00Z",
    "data": {
        "payroll_card_reservation_key": "910e8de5-16af-4bc5-8ee1-4a0652ca0cbf",
        "document_key": "332017f4-a0d6-463a-8557-e925a9485251",
        "document_type": "payroll_card_term",
        "document_url": "https://storage.googleapis.com/example_document.pdf",
    }
}

Próximo Passo

Após receber os webhooks com status generated, o cliente deve apresentar os documentos ao usuário final para coleta da assinatura.

2. Assinatura externa de documentos

Este endpoint é utilizado quando a coleta da assinatura e biometria é feita pela interface do cliente (Client Side) ou parceiro externo. O cliente deve enviar os documentos assinados e os dados biométricos para validação.

Atenção

Esta etapa só deve ser chamada se o fluxo de assinatura não for o Qi Sign. Se estiver utilizando Qi Sign, a confirmação será automática.

Antes de enviar

Realize o upload dos 5 documentos obrigatórios (selfie, frentes/verso do RG, contrato de cartão e contrato de saque) utilizando o endpoint de Upload de Documentos para obter as document_keys.

Request

POST

/payroll_card_reservation/social_security/{payroll_card_reservation_key}/signature

Request Body

{
  "documents": [
    { "document_type": "selfie", "document_key": "2c8f2b3d-8c7a-4e3b-9f6a-1234567890ab" },
    { "document_type": "document_identification", "document_key": "b1a2c3d4-e5f6-7890-abcd-ef0123456789" },
    { "document_type": "document_identification_back", "document_key": "0a1b2c3d-4e5f-6789-0abc-def123456789" },
    { "document_type": "payroll_card_term", "document_key": "9f8e7d6c-5b4a-3210-fedc-ba9876543210" }, 
    { "document_type": "withdrawal_operation_term", "document_key": "a05c74eb-542a-4820-8954-eef92ebb383f" }
  ],
  "ip_address": "192.168.1.100",
  "signature_datetime": "2025-01-15T14:30:00Z",
  "similarity_score": 0.95,
  "biometry_analysis_reference": "serpro"
}

Request Body Details

Campo	Tipo	Descrição	Obrigatório
documents	array	Lista dos 5 documentos exigidos	Sim
biometry_analysis_reference	string	Referência da análise biométrica	Sim
signature_datetime	string	Data e hora da assinatura (ISO 8601)	Sim
ip_address	string	Endereço IP de onde foi feita a assinatura	Sim
similarity_score	float	Score de similaridade biométrica	Sim

Enumeradores Biometry Analysis Reference

Enumerador	Descrição
serpro	Utilizado quando o similarity_score for retornado através de consulta realizada na base de documentos com foto do Detran (Serviço prestado através da Serpro)
tse	Utilizado quando o similarity_score for retornado através de consulta realizada na base de documentos com foto do TSE
not_found	Deve ser informado quando a biometria facial não for localizada em nenhuma das bases governamentais anteriores (serpro ou tse). Neste caso o similarity_score deve ser null ou o grau de similaridade da selfie com o documento oficial com foto, retornado pelo parceiro.

Item de documents

Campo	Tipo	Descrição	Formatação	Obrigatório
document_type	string	Tipo do documento	Enum: "selfie", "document_identification", "document_identification_back", "payroll_card_term", "withdrawal_operation_term"	Sim
document_key	string	Chave única do documento	UUID v4	Sim

Observações sobre os tipos de documento:

selfie: Foto do beneficiário
document_identification: Frente do documento de identificação
document_identification_back: Verso do documento de identificação
payroll_card_term: Termos e condições do cartão assinado
withdrawal_operation_term: Termo da operação de saque assinado

QI Sign

A QI Tech oferece o serviço de assinatura que atende ao determinado pela IN 138. Com biometria facial e envio de documentos.

Para receber uma cotação consulte nosso time comercial:

comercial@qitech.com.br ou (11) 2339-4763

Response

STATUS

200 (OK)

Response Body

{
  "payroll_card_reservation_key": "d4e5f6g7-h8i9-0123-defg-456789012345",
  "payroll_card_reservation_status": "pending_onboarding",
  "attached_documents": [
    {
      "document_key": "0b6c9bb9-0bc1-4fd2-9aab-3ccf5c8bc69d",
      "document_type": "withdrawal_operation_term",
      "document_certifier": "electronic_client_side",
      "document_url": "https://storage.googleapis.com/live-doc-api/documents/withdrawal_operation_term.pdf",
      "document_status": "signed",
      "document_batch_key": "ccc42bc6-efbc-4e8f-a7da-fb6cb77e4146",
      "signature_url": "https://storage.googleapis.com/live-doc-api/documents/withdrawal_operation_term_signed.pdf",
    },
    {
      "document_key": "f974bb60-ff4c-4027-9d88-399470586691",
      "document_type": "payroll_card_term",
      "document_certifier": "electronic_client_side",
      "document_url": "https://storage.googleapis.com/live-doc-api/documents/payroll_card_term.pdf",
      "document_status": "signed",
      "document_batch_key": "ccc42bc6-efbc-4e8f-a7da-fb6cb77e4146",
      "signature_url": "https://storage.googleapis.com/live-doc-api/documents/payroll_card_term_signed.pdf",
    },
    {
      "document_key": "2c8f2b3d-8c7a-4e3b-9f6a-1234567890ab",
      "document_type": "selfie",
      "document_certifier": "electronic_client_side",
      "document_url": "https://storage.googleapis.com/live-doc-api/documents/selfie.pdf",
      "document_status": "generated"
    },
    {
      "document_key": "b1a2c3d4-e5f6-7890-abcd-ef0123456789",
      "document_type": "document_identification",
      "document_certifier": "electronic_client_side",
      "document_url": "https://storage.googleapis.com/live-doc-api/documents/document_identification.pdf",
      "document_status": "generated"
    },
    {
      "document_key": "0a1b2c3d-4e5f-6789-0abc-def123456789",
      "document_type": "document_identification_back",
      "document_certifier": "electronic_client_side",
      "document_url": "https://storage.googleapis.com/live-doc-api/documents/document_identification_back.pdf",
      "document_status": "generated"
    }
  ]
}

Response Body Details

Campo	Tipo	Descrição
payroll_card_reservation_key	string	Chave da reserva do cartão consignado
payroll_card_reservation_status	string	Status da reserva (pending_onboarding)
attached_documents	array	Lista de documentos e seus status

Informação

Após a confirmação da assinatura dos dois documentos, o status do cartão consignado será alterado para "pending_onboarding", indicando que a operação está aguardando o processo de onboarding do cartão.

Erros comuns

404 - Document Not Found

{
  "title": "Document Not Found",
  "description": "Document selfie not found",
  "translation": "Documento selfie não encontrado"
}

Explicação: Este erro ocorre quando a document_key informada no request não foi encontrada no sistema. Verifique se a document_key foi obtida corretamente através do endpoint de Upload de documentos

3. Confirmação de Assinatura

Independente do método de assinatura (Externa ou Qi Sign), quando o processo for concluído com sucesso, você receberá um webhook de mudança de status da reserva.

Consulte a seção Webhooks de Alteração de Status no Manual do Fluxo Principal para ver o exemplo de payload com status pending_onboarding.

Documentos e Assinatura

1. Webhook de Geração de Documentos​

Estrutura Geral do Webhook​

Cenários​

A. Documento Gerado (generated)​

B. Assinatura Pendente (pending_signature)​

2. Assinatura externa de documentos​

Request​

Enumeradores Biometry Analysis Reference​

Item de documents​

Response​

Erros comuns​

3. Confirmação de Assinatura​