Private Payroll Loan Manual - External Formalization
- Issuance and Formalization (previous)
- Registration and Disbursement (next)
The API is still in development phase, therefore, this manual is subject to changes.
In this section, you will find the necessary guidelines to use the formalization APIs for operations originated in the active flow without using QIsign, QI Tech's electronic signature solution.
This flow is intended for clients who choose to use an external electronic signature solution (such as DocuSign, Clicksign, among others) to formalize their contracts.
1 - Document submission
Sending complementary contract data is mandatory.
Documents must be sent through the document upload endpoint and must follow the following formatting:
| Validations | Values |
|---|---|
| Format | JPEG |
| Minimum size | 250 x 250 px |
After uploading the documents, the keys of the sent documents must be informed in the operation creation payload or afterwards, through the following endpoint:
Request Body
{
"document_identification": "2893fc74-88fd-4cc9-a5c6-8a63d9d00f41",
"document_identification_back": "e881ddf4-bc9a-48e0-9555-cac979f65431",
"selfie": "ca37979e-6f11-4465-bf3b-69cd8307549c"
}
The related_party_key is returned in the debt creation response within the borrower object
2 - Operation formalization
After inputting the documents, the operation can proceed to formalization.
In case of signature by the legal representative, in the field "data.contract.signers[i]" the legal representative's data will be returned, and the value of the object "data.contract.signers[i].signer_role" will be "issuer_legal_representative".
The signature payload must contain the mandatory fields related to the documents sent in item 1. The mandatory fields are the following: ip_address and signature_datetime.
Request
PAYLOAD EXAMPLES
Request Body - Signed PDF
{
"path-pdf-signed": "https://storage.googleapis.com/sandbox-doc-api-private/documents/8b740ca1-405d-4507-a7b3-e7de01c4e008/BENJAMINERAPHAELA-NOME_DEVEDOR-CCB-LCM3307596554-20250721184150_signed.pdf",
"type": "pdf-signature",
"biometry_analysis_reference": "serpro",
"similarity_score": "0.96",
"ip_address": "192.168.0.0",
"signature_datetime": "2025-07-22T14:30:12.729Z"
}
Request Body - Evidence-based Signature
{
"biometry_analysis_reference": "serpro",
"signature_datetime": "2025-07-21T10:38:23.382748Z",
"similarity_score": 0.98,
"ip_address": "179.104.42.245",
"type": "data-signature",
"signatures": [
{
"authenticity": {
"timestamp": "2025-07-21 10:38:23",
"ip_address": "179.104.42.245",
"session_id": "ddb1d063-4fdf-4330-af9c-3316e9142ff3"
},
"signer": {
"name": "Nome devedor",
"email": "naotem@gmail.com",
"phone": {
"country_code": "055",
"area_code": "84",
"number": "999538380"
},
"document_number": "11200770870"
},
"authentication_type": "opt-in"
}
]
}
The signature submission payload varies according to the partner's formalization process and must be aligned with QI Tech's integration team.
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 | Must be informed when facial biometry is not found in any of the previous government databases (serpro or tse). In this case the similarity_score must be null or the degree of similarity of the selfie with the official photo document, returned by the partner. |