Onboarding

URL Base:

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

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

Abaixo você encontrará o endpoint para Onboarding no by Cilent com todas as capacidades habilitadas, mas também é possível utilizar as capacidades isoladamente (exceto score de similaridade da Serpro e Score de risco, que dependem do uso da Verificação de Identidade).

Entenda com o responsável pelo seu projeto quais capacidades habilitar para sua operação.

Criar Processo de Onboarding

post

Endpoint para criar um novo processo de Onboarding no by Client

Parâmetros de cabeçalho

AuthorizationstringObrigatório

Access-token válido.

APIKEYstringObrigatório

APIKEY válida com as capacidades para uso do Onboarding.

Corpo

application/json

useCasestringOpcional

Caso de uso da operação.

Example: Onboarding

subsidiaryIdstringOpcional

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

imageBase64stringObrigatório

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

Example: /9j/4AAQSkZJR...

Respostas

200

Processo criado com sucesso.

application/json

idstringOpcional

ID do processo.

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

statusinteger · enumOpcional

Status do processo. Valores possíveis: '1' - Em processamento (ocorre somente quando a resposta da Verificação de Identidade é inconclusiva e há orquestração com o Score de Risco); '3' - Concluído (ocorre quando a resposta da Verificação de Identidade é conclusiva - 'yes' ou 'no'); - '5' - Erro (ocorre quando há algum erro no processamento).

Example: 1Valores possíveis:

livenessinteger · enumOpcional

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

Example: 1Valores possíveis:

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: 253

{
  "subject": {
    "code": "12345678909",
    "name": "Luke Skywalker",
    "gender": "M",
    "birthDate": "2000-05-20",
    "email": "[email protected]",
    "phone": "551972557070"
  },
  "useCase": "Onboarding",
  "subsidiaryId": "35d734c4-7fbb-4b2f-a1dc-7e1575514819",
  "imageBase64": "/9j/4AAQSkZJR..."
}

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

Pontos Importantes:

• 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 = yes/no, este retorno já engloba a Prova de vida (ou seja, não receberá o parâmetro liveness no response) e não há a necessidade de realizar a requisição para Buscar o resultado do processo;

• Caso a resposta da capacidades Verificação de Identidade seja inconclusive, haverá a orquestração com a capacidade Score de risco;

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

Consultar Resultado do Processo

get

Endpoint para buscar o resultado de um processo de Onboarding no by Client (específico para quando há orquestração com o Score de risco)

Parâmetros de rota

processIdstringObrigatório

ID do processo.

Parâmetros de cabeçalho

AuthorizationstringObrigatório

Access-token válido.

APIKEYstringObrigatório

APIKEY válida com as capacidades para uso do Onboarding.

Respostas

200

Informações do processo obtidas com sucesso.

application/json

idstringOpcional

ID do processo.

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

statusinteger · enumOpcional

Status do processo. Valores possíveis: '1' - Em processamento; '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: 3Valores possíveis:

scoreintegerOpcional

Resultado do score de risco.

Example: 90

livenessinteger · enumOpcional

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

Example: 1Valores possíveis:

400

Bad Request.

application/json

403

Forbidden.

application/json

404

Not Found.

application/json

410

Gone.

application/json

500

Internal Server Error.

application/json

get

/processes/v1/{processId}

HTTPcURLJavaScriptPython

GET /processes/v1/{processId} HTTP/1.1
Host: api.id.uat.unico.app
Authorization: text
APIKEY: text
Accept: */*

{
  "id": "2b034568-dfaf-463f-94fb-18ed93c312e8",
  "status": 3,
  "unicoId": {
    "result": "inconclusive"
  },
  "identityFraudsters": {
    "result": "inconclusive"
  },
  "score": 90,
  "government": {
    "serpro": 50
  },
  "liveness": 1
}

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, identityFraudsters = inconclusive/yes 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.

Erros

400 Bad Request

code	message	Descrição
20023	O parâmetro processId não foi informado.	Falta o parâmetro id do processo.
20002	O parâmetro APIKey não foi informado.	Falta o parâmetro APIKEY no header da requisição.
20001	O parâmetro authtoken não foi informado.	QFalta o parâmetro do token de integração no header da requisição.

404 Not Found

403 Forbidden

410 Gone

500 Internal Server Error