Reuse and capture of documents

URL Base:

• UAT: https://api.id.uat.unico.app.

• Production: https://api.id.unico.app.

Get Reusable Documents

get

Endpoint to get a user's documents for reuse in by Client.

Query parameters

codestringRequired

User identifier value (e.g., CPF value).

Example: 12345678909

typestringRequired

Document type (e.g., BR_CPF).

Example: BR_CPF

Header parameters

AuthorizationstringRequired

Valid access-token.

APIKEYstringRequired

Valid APIKEY with the capabilitie Document Capture and Reuse enabled.

Responses

200

Process information retrieved successfully.

application/json

400

Bad Request.

application/json

403

Forbidden.

application/json

404

Not Found.

application/json

500

Internal Server Error.

application/json

get

/documents/v1

HTTPcURLJavaScriptPython

GET /documents/v1?code=text&type=text HTTP/1.1
Host: api.id.uat.unico.app
Authorization: text
APIKEY: text
Accept: */*

{
  "items": [
    {
      "documentType": "unico.moja.dictionary.br.rg.v2.Rg",
      "documentId": "2aaf6037-0153-415d-b9fe-cf7e8198408f"
    }
  ]
}

• The use of the Reuse feature requires a prior Identity Verification process, which must yield a "YES" response or a risk score equal to or greater than +50; otherwise, it will be necessary to capture the user's document.

• If you find a document to be reused, in the process creation endpoint you will enter the ID of this document in the document.documentId parameter and it will not be necessary to capture the document and send the base64 in the document.files parameter.

• If no document is found to be reused, the request will still succeed (200 OK), but the response will contain the following content:

{
  "items": [{}]
}

Create a Document Process

post

Endpoint to create a new Document process by Client.

Header parameters

AuthorizationstringRequired

Valid access token.

APIKEYstringRequired

Valid APIKEY with the capabilitie Document Capture and Reuse enabled.

Body

application/json

Responses

200

Process information successfully retrieved.

application/json

400

Bad Request.

application/json

403

Forbidden.

application/json

500

Internal Server Error.

application/json

post

/processes/v1

HTTPcURLJavaScriptPython

POST /processes/v1 HTTP/1.1
Host: api.id.uat.unico.app
Authorization: text
APIKEY: text
Content-Type: application/json
Accept: */*
Content-Length: 278

{
  "subject": {
    "code": "12345678909",
    "name": "Luke Skywalker",
    "email": "[email protected]",
    "phone": "551972557070"
  },
  "document": {
    "purpose": null,
    "authProcessId": "80371b2a-3ac7-432e-866d-57fe37896ac6",
    "documentId": "80371b2a-3ac7-432e-866d-57fe37896ac6",
    "files": [
      {
        "data": "/9j/4AAQSkZJR..."
      }
    ]
  }
}

{
  "id": "2b034568-dfaf-463f-94fb-18ed93c312e8",
  "status": 3,
  "document": {
    "id": "b97c3fd9-d95d-413f-bc0a-75eb87304421",
    "type": "unico.moja.dictionary.br.rg.v2.Rg",
    "cpfMatch": false,
    "faceMatch": false,
    "content": {
      "numero": "044589731564",
      "rgNumero": "123456789 SESP PR",
      "nomeCivil": "Homer Simpson",
      "filiacao": [
        "Monasimpson",
        "Monasimpson"
      ],
      "dataNascimento": "1990-05-12T00:00:00Z",
      "dataHabilitacao": "1997-11-18T00:00:00Z",
      "dataExpiracao": "2017-12-07T00:00:00Z",
      "dataEmissao": "2012-12-07T00:00:00Z",
      "localEmissao": "Curitiba PR",
      "categoria": "B",
      "renachNumero": "PR904987581"
    },
    "fileUrls": [
      "https://url-signer-1",
      "https://url-signer-2"
    ]
  }
}

Important:

• To use the Document Capture and Reuse capability, the Identity Verification capability must be used beforehand, as it is necessary to include the processId obtained from the Identity Verification in the document.authProcessId parameter:

  • The process must have valid biometrics, be used within 24 hours of completion and cannot be reused.

  • It is possible to reuse a biometric authentication previously performed by the same user within a period of up to 24 hours. Within this timeframe, the ID authentication proof can be used in different document verification processes (e.g., RG and CNH) without the need for a new biometric authentication.

• If we are unable to extract a field from the document, it is not listed in the API return.

• The link returned in fileUrls is valid for 10 minutes. A GET request must be made during the process to refresh the link and extend its validity.

• When using the Document Capture and Reuse feature, it is mandatory to inform the user, on the interface, about the reuse, as required by the contract.

• If an error occurs during processing, the process will return a status = 5, as shown in the example below:

•   {
    "id": "80371b2a-3ac7-432e-866d-57fe37896ac6",
    "status": 5
    }

Content returned in document.content based on document.type:

CNH

• Type: CNH

• Content: Brazilian National Driving License

  • String numero;

  • String rgNumero;

  • String cpfNumero;

  • String nomeCivil;

  • List string filiacao;

  • Datetime dataNascimento;

  • Datetime data_habilitacao;

  • Datetime data_expiracao;

  • Datetime data_emissao;

  • String local_emissao;

  • String categoria;

  • String renachNumero;

"content": {
    "numero": "044589731564",
    "rgNumero": "123456789 SESP PR",
    "nomeCivil": "Homer Simpson",
    "filiacao": [
        "Monasimpson",
        "Monasimpson"
    ],
    "dataNascimento": "1990-05-12T00:00:00Z",
    "dataHabilitacao": "1997-11-18T00:00:00Z",
    "dataExpiracao": "2017-12-07T00:00:00Z",
    "dataEmissao": "2012-12-07T00:00:00Z",
    "localEmissao": "Curitiba PR",
    "categoria": "B",
    "renachNumero": "PR904987581"
}

RG

CIN

Passport

UNKNOWN

Tips:

• To implement your business rules, always validate the final statuses of the processes (3, 5). To validate the response from the IDCloud capabilities, only consider status = 3 for your decision-making.

Errors

400 Bad Request

Code	Message	Description
20900	O base64 informado não é válido.	The base64 parameter is invalid. Possible causes: It's not an image or it's an injection attempt.
20807	A imagem precisa estar no padrão HD ou possuir uma resolução superior a 640 x 480.	The resolution of the uploaded image is too low.
20507	O parâmetro subject.code é inválido.	Non-standard or non-existent CPF.
20506	O base64 informado é muito grande. O tamanho máximo suportado é até 800kb.	When the e-mail address provided is not vThe image is too large. The image can be compressed to JPEG92 without loss of quality.
20505	O base64 informado não é suportado. Os formatos aceitos são png, jpeg e webp.	When the phone number entered is not validBase64 invalid. Possible causes: not a valid image or invalid prefix.
20009	O parâmetro imagebase64 não foi informado.	The imagebase64 parameter, which contains the person's selfie, is missing.
20006	O parâmetro subject.name não foi informado.	The subject.name parameter, which contains the person's name, is missing.
20005	O parâmetro subject.code não foi informado.	The subject.code parameter, which contains the person's cpf, is missing.
20004	O parâmetro subject não foi informado.	The subject parameter, which contains the person's data (cpf, name), is missing.
20003	The request body is missing or invalid.	Null or invalid payload.
20002	O parâmetro APIKey não foi informado.	The APIKEY parameter is missing from the request header.
20001	O parâmetro authtoken não foi informado	The integration token parameter is missing from the request header.
10508	The JWT with the captured face has already been used.	The jwt can only be used once.
10507	The JWT with the captured face is expired.	JWT expired. The .jwt must be sent within 10 minutes.
10506	The bundle is invalid.	Invalid bundle. APIKEY uses a security method and this request does not meet the security requirements (SDK).

403 Forbidden

500 Internal Server Error