Reaproveitamento e captura de documentos

Nesta seção, você encontrará as particularidades de criar um processo que tenha o Reaproveitamento e captura de documentos como capacidade

Introdução

Nesta seção, você encontrará a documentação detalhada sobre o funcionamento dos endpoints relacionados à capacidade Reaproveitamento e captura de documentos. 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.

Trata-se de uma capacidade síncrona que exige o consumo de dois endpoints, detalhados nesta documentação, para sua utilização completa.

As capacidades da plataforma Unico IDCloud via by Client são gerenciadas por meio de API Keys - utilizadas como um parâmetro no header das requisições -, que definem o escopo de acesso. Como pré-requisito, é necessário possuir uma API Key configurada excluvisamente para a capacidade Reaproveitamento e captura de documentos, garantindo acesso dedicado e seguro ao recurso.

Fale com o responsável do seu projeto para obter a API Key com esta configuração.

Antes de começar

Suas requisições de API são autenticadas utilizando um access-token. Qualquer requisição que não inclua um access-token válido retornará um erro.

Você pode ver mais sobre como gerar um access-token aqui.

Endpoints:

UAT: https://api.id.uat.unico.app;
Produção: https://api.id.unico.app.

Consulta de documento para ser reaproveitado

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

Payload inválido.

application/json

403

Falta o parâmetro APIKEY no header da requisição.

application/json

404

Quando o processo não é encontrado.

application/json

500

Erro inesperado (Erro interno ou problema de parâmetro).

application/json

get

GET /documents/v1 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"
    }
  ]
}

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": [{}]
}

Criação do Processo

Criar Processo

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

Respostas

200

Informações do processo obtidas com sucesso.

application/json

post

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

200

Informações do processo obtidas com sucesso.

{
  "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;
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:

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

Type: RG
Content: Registro Geral
- string numero;
- string cpfNumero;
- string nomeCivil;
- array <string> filiacao;
- datetime dataNascimento;
- datetime dataEmissao;
- string naturalidade;
- string orgaoEmissor;
- string ufEmissor;

"content": {
    "numero": "4815162342",
    "cpfNumero": "54858809080",
    "nomeCivil": "Daniel Coelho Da Costa",
    "filiacao": [
        "Rosa Coelho Da Costa",
        "Edivaldo Da Costa",
    ],
    "dataNascimento": "1980-12-19T03:00:00Z",
    "dataEmissao": "2012-12-21T02:00:00Z",
    "naturalidade": "Sao Paulo SP",
    "orgaoEmissor": "Secretaria Da Segurança Pública (SSP)",
    "ufEmissor": "UF_SP"
}

Type: CIN
Content: Carteira de Identidade Nacional
- string cpfNumero;
- string nomeCivil;
- array <string> filiacao;
- datetime dataNascimento;
- datetime dataEmissao;
- datetime dataExpiracao;
- string orgaoEmissor;
- string naturalidade;
- string nacionalidade;
- string localEmissao;

"content": {
    "cpfNumero": "54858809080",
    "nomeCivil": "Vitor Ra",
    "filiacao": [
        "Danilo Luis Renan Ramos",
        "Giovanna Vitoria",
    ],
    "dataNascimento": "1980-12-19T03:00:00Z",
    "dataEmissao": "2024-03-02T00:00:00Z",
    "dataExpiracao": "2034-03-02T00:00:00Z",
    "orgaoEmissor": "Detran/Rj",
    "naturalidade": "Rio De Janeiro RJ",
    "nacionalidade": "BRA",
    "localEmissao": "Rio De Janeiro RJ",

}

Type: PASSAPORTE
Content: Passaporte brasileiro
- string numero;
- string nome;
- string sobrenome;
- string paisEmissor;
- string nacionalidade;
- string naturalidade;
- array <string> filiacao;
- datetime dataNascimento;
- datetime dataEmissao;
- datetime dataExpiracao;
- string autoridade.

"content": {
    "numero": "AA011906",
    "nome": "CHANCHÃO AMARELO",
    "sobrenome": "PASSAREDO",
    "paisEmissor": "BRA",
    "nacionalidade": "BRASILEIRO(A)",
    "naturalidade": "<null>",
    "filiacao": [
         "Monasimpson",
         "Monasimpson"
    ],
    "dataNascimento": "1920-06-01T00:00:00Z",
    "dataEmissao": "2000-01-01T00:00:00Z",
    "dataExpiracao": "2010-01-01T00:00:00Z",
    "autoridade": "SR/DPF/DF"
}

Type: UNKNOWN
Content: Documento desconhecido. Significa que não foi possível detectar o tipo daquele documento.

content {
}

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;
Para mais informações sobre os erros possíveis para este endpoint, consulte a seção Erros.

Dúvidas?

Não encontrou algo ou ainda precisa de ajuda? Se já é um cliente ou parceiro, pode entrar em contato através da Central de Ajuda.

AnteriorProva de vida + Validação 1:1 + Alerta de comportamento PróximoCenários de response

Atualizado há 1 mês

Isto foi útil?

Introdução

Antes de começar

Consulta de documento para ser reaproveitado

Consultar documento para ser reaproveitado

Criação do Processo

Criar Processo

Dúvidas?​

Dúvidas?