Reaproveitamento e captura de documentos

URL Base:

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

• Produção: https://api.id.unico.app.

Consultar documento para ser reaproveitado

get

Endpoint para buscar os documentos de um usuário para serem reaproveitados no by Client.

Parâmetros de consulta

codestringObrigatório

Valor do identificador do usuário (ex: Valor do CPF). Deve conter 11 caracteres e ser enviado sem pontos ou traços.

Example: 12345678909

typestringObrigatório

Tipo do documento (exemplo: BR_CPF).

Example: BR_CPF

Parâmetros de cabeçalho

AuthorizationstringObrigatório

Access-token válido.

APIKEYstringObrigatório

APIKEY válida com a capacidade reaproveitamento e captura de documentos habilitada.

Respostas

200

Informações do processo obtidas com sucesso.

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"
    }
  ]
}

• O uso do Reaproveitamento exige que haja um processo de Verificação de Identidade anterior e este deve obtido a resposta "SIM" OU um Score de risco igual ou maior que +50, do contrário será necessário capturar o documento do usuário.

• Caso encontre um documento para ser reaproveitado, no endpoint de criação do processo você irá informar o id deste documento no parâmetro document.documentId e não será necessário realizar a captura do documento e enviar o base64 no parâmetro document.files.

• Caso não encontre um documento para ser reaproveitado, a requisição ainda será bem-sucedida (200 OK), porém o response trará o seguinte conteúdo:

{
  "items": [{}]
}

Criar Processo de Documento

post

Endpoint para criar um novo processo de documentos no by Client.

Parâmetros de cabeçalho

AuthorizationstringObrigatório

Access-token válido.

APIKEYstringObrigatório

APIKEY válida com a capacidade reaproveitamento e captura de documentos habiitada.

Corpo

application/json

Respostas

200

Informações do processo obtidas com sucesso.

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"
    ]
  }
}

Pontos Importantes:

• Para utilizar a capacidade de Reaproveitamento e captura de documentos, deve-se utilizar a capacidade Verificação de Identidade anteriormente, pois é necessário utilizar o processId obtido da Verificação de Identidade no parâmetro document.authProcessId:

  • O processo precisar ser de uma biometria válida, ser utilizado em até 24h a partir de sua finalização;

  • É possível reutilizar uma autenticação biométrica realizada previamente pelo mesmo usuário em um prazo de até 24 horas. Dentro desse intervalo, a prova de autenticação do ID pode ser utilizada em diferentes processos de verificação de documentos (ex: RG e CNH), sem a necessidade de uma nova biometria.

• Caso não consigamos extrair algum campo do documento, ele não é listado no retorno da API;

• O link retornado em fileUrls é válido por 10 minutos, sendo necessário realizar uma requisição GET no processo para atualizá-lo e renovar sua validade;

• Os documentos retornados em fileUrls serão sempre do mesmo formato que foram capturados, podendo ser um PDF, uma imagem com o documento ou duas imagens com o documento (frente e verso);

• Ao utilizar a funcionalidade Reaproveitamento e Captura de Documentos, é obrigatório informar ao usuário, na interface, sobre o reaproveitamento, conforme previsto em contrato.

• Caso ocorra algum erro no processamento, o processo retornará um status = 5, como no exemplo abaixo:

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

Conteúdo retornado no document.content baseado no document.type:

CNH

• Type: CNH

• Content: Carteira Nacional de Habilitação

  • string numero;

  • string rgNumero;

  • string cpfNumero;

  • string nomeCivil;

  • array <string> filiacao;

  • datetime dataNascimento;

  • datetime dataHabilitacao;

  • datetime dataExpiracao;

  • string localEmissao;

  • string categoria;

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

RG

CIN

Passaporte (BR)

UNKNOWN

Dicas:

• Para implementar suas regras de negócio, sempre valide os status finais dos processos (3,5). Para validar a resposta das capacidades IDCloud, só considere o status = 3 para sua tomada de decisão.

Erros

400 Bad Request

code	message	Descrição
20900	O base64 informado não é válido.	O parâmetro base64 é inválido. Possíveis causas: Não é uma imagem ou é uma tentativa de injection.
20807	A imagem precisa estar no padrão HD ou possuir uma resolução superior a 640 x 480.	A resolução da imagem enviada é muito pequena.
20507	O parâmetro subject.code é inválido.	CPF fora do padrão ou inexistente.
20506	O base64 informado é muito grande. O tamanho máximo suportado é até 800kb.	A imagem é muito grande. A imagem pode ser comprimida para JPEG92 sem perda de qualidade.
20505	O base64 informado não é suportado. Os formatos aceitos são png, jpeg e webp.	Base64 inválido. Possíveis causas: não é uma imagem válida ou prefixo inválido.
20009	O parâmetro imagebase64 não foi informado.	Falta o parâmetro imagebase64, que contém a selfie da pessoa.
20006	O parâmetro subject.name não foi informado.	Falta o parâmetro subject.name, que contém o nome da pessoa.
20005	O parâmetro subject.code não foi informado.	Falta o parâmetro subject.code, que contém o cpf da pessoa.
20004	O parâmetro subject não foi informado.	Falta o parâmetro subject, que contém os dados da pessoa (cpf, nome).
20003	The request body is missing or invalid.	Payload nulo ou inválido.
20002	O parâmetro APIKey não foi informado.	Falta o parâmetro APIKEY no cabeçalho da requisição.
20001	O parâmetro authtoken não foi informado	Falta o parâmetro do token de integração no cabeçalho da requisição.
10508	The JWT with the captured face has already been used.	O .jwt só pode ser usado uma única vez.
10507	The JWT with the captured face is expired.	JWT expirado. O .jwt deve ser enviado em até 10 minutos.
10506	The bundle is invalid.	Bundle inválido. APIKEY usa um método de segurança e esta solicitação não atende aos requisitos de segurança (SDK).

403 Forbidden

500 Internal Server Error