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

HTTPcURLJavaScriptPython

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

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": "[e-mail]",
    "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": "CNH",
    "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:

CNH

• Type: CNH

• Content: Carteira Nacional de Habilitação

  • 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

• Type: RG

• Content: Registro Geral

  • String numero;

  • String orgao_emissor;

  • String uf_emissor;

  • String cpfNumero;

  • String carteira_profissionalNumero;

  • String certificado_militarNumero;

  • String cnsNumero;

  • String nis_pis_pasepNumero;

  • String ctpsNumero;

  • String ctps_serie;

  • String ctps_uf;

  • String titulo_eleitorNumero;

  • String nomeCivil;

  • String nome_social;

  • List string filiacao;

  • Datetime dataNascimento;

  • String naturalidade;

  • Datetime data_emissao;

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

CIN

• Type: CIN

• Content: Carteira de Identidade Nacional

  • string rgNumero;

  • string cpfNumero;

  • string nomeCivil;

  • string nome_social;

  • List string filiacao;

  • Datetime dataNascimento;

  • Datetime data_expiracao;

  • Datetime data_emissao;

  • string orgao_emissor;

  • string local_emissao;

  • string naturalidade;

  • string nacionalidade;

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

Passaporte (BR)

• Type: PASSAPORTE

• Content: Passaporte brasileiro

  • string numero;

  • string nome;

  • string sobrenome;

  • string pais_emissor;

  • string nacionalidade;

  • string naturalidade;

  • Datetime data_nascimento;

  • Datetime data_emissao;

  • Datetime data_expiracao;

  • string autoridade.

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

UNKNOWN

• 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.