Documents and Signature

Navigation

Webhooks (previous)
Address Management (next)

This section details the document generation flow and the electronic signature process, either via external flow or via Qi Sign.

Note

If the client is integrated with the QISign signature flow, the items in this section are optional.

1. Documents Webhook

After creating the operation, documents (payroll_card_term, withdrawal_operation_term and payroll_card_consent_term) are generated asynchronously. The API sends a webhook for each document notifying the document status change.

Attention

If the client does not use QISign, the client must implement handling of this webhook to capture the document URLs and direct the beneficiary to sign through the chosen external certification provider.

Tracking via Webhook

To check the complete structure of the payloads, event scenarios and implement URL capture, consult the Documents Webhook (Generation and Validation) section in the Webhooks Manual.

2. External document signature

This endpoint is used when signature and biometrics collection is done by the client's interface (Client Side) or external partner. The client must send the signed documents and biometric data for validation.

Attention

This step should only be called if the signature flow is not Qi Sign. If using Qi Sign, confirmation will be automatic.

Before sending

Upload the 5 mandatory documents (selfie, front/back of ID, card contract and withdrawal contract) using the Document Upload endpoint to obtain the 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": "payroll_card_consent_term", "document_key": "d9b64eae-6e11-4b82-92f0-a0e1a3049eee" }, 
    { "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

Field	Type	Description	Required
documents	array	List of the 5 required documents	Yes
biometry_analysis_reference	string	Biometric analysis reference	Yes
signature_datetime	string	Signature date and time (ISO 8601)	Yes
ip_address	string	IP address from where the signature was made	Yes
similarity_score	float	Biometric similarity score	Yes

Biometry Analysis Reference Enumerators

Enumerator	Description
serpro	Used when the similarity_score is returned through a query performed on the Detran photo document database (Service provided through Serpro)
tse	Used when the similarity_score is returned through a query performed on the TSE photo document database
not_found	Should be informed when facial biometry is not found in any of the previous government databases (serpro or tse). In this case the similarity_score should be null or the degree of similarity of the selfie with the official photo document, returned by the partner.

documents Item

Field	Type	Description	Format	Required
document_type	string	Document type	Enum: "selfie", "document_identification", "document_identification_back", "payroll_card_term", "payroll_card_consent_term", "withdrawal_operation_term"	Yes
document_key	string	Unique document key	UUID v4	Yes

Notes about document types:

selfie: Beneficiary photo
document_identification: Front of identification document
document_identification_back: Back of identification document
payroll_card_term: Signed card terms and conditions
payroll_card_consent_term: Signed card contracting consent term
withdrawal_operation_term: Signed withdrawal operation term

QI Sign

QI Tech offers the signature service that meets the requirements determined by IN 138. With facial biometrics and document sending.

To receive a quote, contact our commercial team:

comercial@qitech.com.br or (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": "0133eda8-0e82-41d9-ae8d-7020f023b0f9",
      "document_type": "payroll_card_consent_term",
      "document_certifier": "electronic_client_side",
      "document_url": "https://storage.googleapis.com/live-doc-api/documents/payroll_card_consent_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_consent_term.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

Field	Type	Description
payroll_card_reservation_key	string	Payroll card reservation key
payroll_card_reservation_status	string	Reservation status (pending_onboarding)
attached_documents	array	List of documents and their status

Information

After confirming the signature of both documents, the payroll card status will change to "pending_onboarding", indicating that the operation is awaiting the card onboarding process.

Common Errors

404 - Document Not Found

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

Explanation: This error occurs when the document_key informed in the request was not found in the system. Check if the document_key was correctly obtained through the Document Upload endpoint

3. Signature Confirmation

Regardless of the signature method (External or Qi Sign), when the process is successfully completed, you will receive a webhook for reservation status change.

Consult the Status Change Webhooks section in the Main Flow Manual to see the payload example with status pending_onboarding.

1. Documents Webhook​

2. External document signature​

Request​

Biometry Analysis Reference Enumerators​

documents Item​

Response​

Common Errors​

3. Signature Confirmation​