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 assíncrona que exige o consumo de três 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/processes/v1;

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

---

Consulta de documento para ser reaproveitado

---

Consultar documento para ser reaproveitado

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

GEThttps://api.id.uat.unico.app/documents/v1/client/v1/process

Query parameters

Header parameters

Response

200400403404500

Informações do processo obtidas com sucesso.

Body

application/json

itemsarray of object

Informações do documento que pode ser reaproveitado.

Request

JavaScriptCurlPython

const response = await fetch('https://api.id.uat.unico.app/documents/v1/client/v1/process?code=text&type=text', {
    method: 'GET',
    headers: {
      "Authorization": "text",
      "APIKEY": "text"
    },
});
const data = await response.json();

Response

200400403404500

{
  "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.

Criação do Processo

---

Criar Processo

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

POSThttps://api.id.uat.unico.app/processes/v1/

Header parameters

Body

application/json

subject*object

Informações do usuário.

document*object

Informações sobre o documento que será capturado.

Response

200400500

Processo de documento criado com sucesso.

Body

application/json

idstring

ID do processo.

Example: "80371b2a-3ac7-432e-866d-57fe37896ac6"

statusenum

Status do processo. Valores possíveis: '1': Em processamento; '3' - Concluído; '4' - Cancelado (ex.: timeout); - '5' - Erro.

Example: 1

1345

documentobject

Informações do documento.

Request

JavaScriptCurlPython

const response = await fetch('https://api.id.uat.unico.app/processes/v1/', {
    method: 'POST',
    headers: {
      "Authorization": "text",
      "APIKEY": "text",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "subject": {
        "code": "12345678909",
        "name": "Luke Skywalker"
      },
      "document": {
        "purpose": null,
        "authProcessId": "80371b2a-3ac7-432e-866d-57fe37896ac6",
        "documentId": "80371b2a-3ac7-432e-866d-57fe37896ac6",
        "files": [
          {}
        ]
      }
    }),
});
const data = await response.json();

Response

200400500

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

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 e não pode ser reutilizado.

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

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

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

Consulta do Resultado do Processo

---

Consultar Resultado do Processo

Endpoint para buscar o resultado de um processo de reaproveitamento e captura de documentos no by Client.

GEThttps://api.id.uat.unico.app/processes/v1/{processId}

Path parameters

processId*string

ID do processo.

Header parameters

Response

200400403404410500

Informações do processo obtidas com sucesso.

Body

application/json

idstring

ID do processo.

Example: "2b034568-dfaf-463f-94fb-18ed93c312e8"

statusenum

Status do processo. Valores possíveis: '1' - Em processamento; '3' - Concluído; '4' - Cancelado (ex.: timeout); - '5' - Erro.

Example: 3

1345

documentobject

Informações do documento.

Request

JavaScriptCurlPython

const response = await fetch('https://api.id.uat.unico.app/processes/v1/{processId}', {
    method: 'GET',
    headers: {
      "Authorization": "text",
      "APIKEY": "text"
    },
});
const data = await response.json();

Response

200400403404410500

{
  "id": "2b034568-dfaf-463f-94fb-18ed93c312e8",
  "status": 3,
  "document": {
    "id": "b97c3fd9-d95d-413f-bc0a-75eb87304421",
    "type": "CNH",
    "cpfMatch": 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"
    ]
  }
}

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 {
}

Atenção:

• Quando a requisição GET for para um processo com status = 5 (erro), o status code de retorno é 410 (Gone) ao invés de 200 (Success);

• Como não há drop na requisição de criação do processo, os erros de processamento do documento serão retornados no response do endpoint de consulta. É neste momento que você deve interpretar os retornos e se necessário, direcionar o seu usuário para um fluxo de retentativas.

Dicas:

• Para implementar suas regras de negócio, sempre valide os status finais dos processos (3,4,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.