Prova de vida + Verificação de Identidade + Score de risco

Nesta seção, você encontrará as particularidades de criar um processo que tenha a Prova de vida + Verificação de Identidade + Score de risco como capacidades

---

Introdução

---

Nesta seção, você encontrará a documentação detalhada sobre o funcionamento dos endpoints relacionado às capacidades Prova de Vida + Verificação de Identidade + Score de risco, utilizadas em conjunto.

Trata-se de duas capacidades síncronas (Prova de vida + Verificação de Identidade) integradas com uma capacidade assíncrona (Score de risco). Ou seja, enquanto a maior parte dos processos retornará respostas síncronas, uma parte deles será orquestrada com o Score de risco e precisarão ser consultados posteriormente.

Para essa integração, será necessário consumir dois endpoints descritos nesta documentação, que também podem ser combinados com o uso de Webhooks.

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 com as capacidades Prova de Vida + Verificação de Identidade + Score de risco, 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.

---

Criação do Processo

---

Criar Processo

Endpoint para criar um novo processo de prova de vida + verificação de identidade + score de risco no by Client.

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

Header parameters

Body

application/json

subject*object

Informações do usuário.

useCase*string

Caso de uso da operação.

Example: "Onboarding"

subsidiaryIdstring

o ID da filial onde o processo será criado. Caso haja somente uma filial associada a conta de serviço, não há a necessidade de passar este parâmetro. Caso haja separação de processos por filial, você receberá os IDs das filiais do time Unico.

Example: "35d734c4-7fbb-4b2f-a1dc-7e1575514819"

imageBase64*string

Arquivo encrypted gerado pelo SDK ou base64 (caso não utilize a Prova de vida).

Example: "/9j/4AAQSkZJR..."

Response

200400500

Processo criado com sucesso (INCONCLUSIVO da Verificação de Identidade e derivado para o Score de risco).

Body

application/json

idstring

ID do processo.

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

statusenum

Status do processo. Valores possíveis: '1' - Em processamento (ocorre quando é derivado para o Score de risco); '3' - Concluído; '4' - Cancelado (ex.: timeout); - '5' - Erro.

Example: 1

1345

unicoIdobject

Informações sobre a verificação de identidade.

livenessenum

Resultado da prova de vida. Valores possíveis: '1' - Prova de vida aprovada; '2' - Prova de vida recusada.

Example: 1

12

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"
      },
      "useCase": "Onboarding",
      "imageBase64": "/9j/4AAQSkZJR..."
    }),
});
const data = await response.json();

Response

200400500

{
  "id": "80371b2a-3ac7-432e-866d-57fe37896ac6",
  "status": 1,
  "unicoId": {
    "result": "inconclusive"
  },
  "liveness": 1
}

Pontos Importantes:

• Caso a resposta da capacidade Verificação de Identidade seja unicoId = yes, este retorno já engloba a Prova de vida (ou seja, não receberá o parâmetro liveness no response);

• Para utilizar a capacidade Prova de vida, é indispensável o uso dos nossos SDKs:

  • É possível utilizar a capacidade de Verificação de Identidade sem a Prova de vida. Para este caso de uso o retorno de liveness sempre será liveness = 1. Neste cenário não há nenhuma validação da prova de vida, nem mesmo passiva.

• Caso a resposta da capacidade Verificação de Identidade seja unicoId = inconclusive, haverá a orquestração com a capacidade Score de risco, portanto será necessário Consultar o Resultado do Processo (endpoint descrito abaixo), visto que o retorno do Score de risco é assíncrono;

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

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

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:

  • Um percentual da sua operação terá uma resposta conclusiva da capacidade Verificação de Identidade (yes ou no), e para estes você pode tomar a decisão de aprovar ou não o cadastro, sem a necessidade Consultar o Resultado do Processo;

  • Para os casos que receber uma resposta inconclusiva da capacidade Verificação de Identidade (inconclusive), será necessário Consultar o Resultado do Processo.

Consulta do Resultado do Processo

---

Consultar Resultado do Processo

Endpoint para buscar o resultado de um processo de prova de vida + verificação de identidade + score de risco 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 (ocorre quando é derivado para o Score de risco); '2' - Divergência (ocorre quando o Score de risco encontrou uma divergência para esta face e ainda irá concluir a verificação) '3' - Concluído; '4' - Cancelado (ex.: timeout); - '5' - Erro.

Example: 3

12345

unicoIdobject

Informações sobre a verificação de identidade.

livenessenum

Resultado da prova de vida. Valores possíveis: '1' - Prova de vida aprovada; '2' - Prova de vida recusada.

Example: 1

12

scoreinteger

Resultado do score de risco.

Example: 50

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,
  "unicoId": {
    "result": "inconclusive"
  },
  "liveness": 1,
  "score": 50
}

No endpoint da v2 (/processes/v2/{id}), também devolvemos algumas informações adicionais do usuário, conforme exemplo abaixo:

"processAdditionalInfo": {
      "transactionId": "2ed76ac5-8fd7-4477-839d-92bedd7e9fd5",
      "personName": "Nome da pessoa",
      "personDocument": "Número do documento da pessoa",
      "personImage": "URL assinada da imagem da pessoa",
      "finishedAt": "2024-10-04T18:53:17.028228"
  }
}

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);

• Pode haver casos de drop na orquestração com a capacidade Score de risco. Neste cenário, o processo terá a combinação: {status = 3, unicoId = inconclusive, liveness = 1 e SEM score no response da API}. Entenda mais na seção Cenários de response;

• Caso consulte um processo que esteja no status = 2, implemente um polling até que obtenha um status = 3 ou implemente o Webhook da Unico para saber quando consultar o resultado.

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 melhorar a performance da sua operação, você pode utilizar nossos Webhooks e só consultar o resultado de processos que estiverem nos status finalizados;

• Para mais informações sobre os cenários que pode receber no response, consulte a seção Cenários de response;

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