Certiface REST API

Sumário

• Introdução
• Visão geral
• Método Autenticação
  • Gerar hash MD5 em Linux
  • Response
• Método Certiface
  • Headers
  • Body
  • Response

Introdução

A finalidade da API Certiface/Bureau de Faces é identificar biometricamente o cliente na base do Certiface, informando os dados: foto, CPF, nome e data de nascimento. Para isso, é necessário que seja feita a autenticação do operador que irá executar a validação e, em seguida, a identificação dele.

O Certiface REST API possui os seguintes métodos:

1. Autenticação
2. Certiface

Visão geral

Fluxo base para validação biométrica.

Método Autenticação

O objetivo do método é autenticar o usuário do sistema e obter o token que será utilizado como chave criptográfica para acessar a chamada biométrica (método Certiface).

A resposta retorna em JSON com o token e a data/hora de expiração.

⚠️

O token expira em 30 minutos.

Request

request: POST https://hml.certiface.com.br/CertiFaceWS/rs/operador/auth

content-Type: application/x-www-form-urlencoded

body:

login=login
senha=md5Password

Parâmetros

⚠️

Por segurança, não utilize encoders MD5 online.

Gerar hash MD5 em Linux

echo -n "suasenha" | md5sum
fb8da69afd458b1b3b4dec5194c564d6

Site de apoio

Response Retorno 200 OK content-type: application/json

body:

{ 
 "token": "WdCFs9ytXJC52RWV5jmynEIKVd0xpKH6JSi7HVeoMz8", 
 "expires": "01/01/2021 11:11:01"
}

Retorno 400 Requisição mal formada ou dados incorretos. Retorno 401 Não autorizado. Retorno 403 Sem permissão

É bom saber! O endereço https://hml.certiface.com.br/CertiFaceWS/rs/operador/auth deverá ser utilizado apenas para o desenvolvimento e homologação da integração. Para acessar o ambiente de produção, esse endereço deverá ser substituído por: https://www.certiface.com.br/CertiFaceWS/rs/operador/auth

Método Certiface O objetivo é validar biometricamente o cliente, podendo ocorrer o cadastro quando o cliente não estiver na base de dados do Certiface ou se a sua validação estiver nessa base. Além da validação biométrica, também estão disponíveis (sob demanda) validações em outras bases de dados. O retorno é composto pelo status da transação e o score de risco para melhor recomendar se o cliente será aprovado, revisado ou reprovado na transação corrente.

Request: POST https://hml.certiface.com.br/CertiFaceWS/rs/certiface Content-Type: multipart/form-data Authorization: login; UUTKyf8qcxvvHs6M_ueOmoEFwYxvXE4DAeULKeoHr3o; Date: 01/01/2021 11:01:19 01/01/2021 10:31:51

Body:

login: "login"
senha: "md5Password"
nascimento: "01/01/2001"
imagem: "/9j/4AAQSkZJRgABAg .....VDc4DGpaKuf/9k="

Headers

Atenção especial ao cabeçalho da requisição, header Authorization:

• Este header é composto do login do usuário, hash de autorização e data/hora de expiração (separados pelo caractere ";").
• A data e hora de expiração são retornados pelo método Autorização.
• O hash de autorização deve ser gerado utilizando o algoritmo SHA256 a partir do tipo do método (POST) + URL + data_e_hora_de_expiração como texto base e o token criptográfico gerado no método Autorização como chave.

Body:

Exemplo da chamada do método Certiface:

POST /CertiFaceWS/rs/certiface HTTP/1.1
Host: certiface.com.br
Authorization: usuario;5S9wfiTrbvFQfCgSLy7tMN_EUHzAiQAE9ENcMTvX9Y;11/06/2015 18:24:35
Date: 11/06/2015 17:55:13
Cache-Control: no-cache
Content-Type: multipart/form-data;
boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW
----WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="imagem"
/9j/4AAQSkZJRgABAQEBKwErAAD/2wBDAAMCAgMCAgMDAwMEAwMEBQgFBQQEBQoHBwYID……
----WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="cpf"
00000014141
----WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="nome"
NOME SOBRENOMES
----WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="nascimento"
01/01/1991
----WebKitFormBoundary7MA4YWxkTrZu0gW

Site de Apoio

Response

Retorno 200 OK Exemplo 1: Transação efetuada com sucesso (codigo = 200)

content-type: application/json

body:

{
 "certifaceID": {
 "protocolo": "209901234567",
 "codigo": 200,
 "score": 400
 }
}

Exemplo 2: Imagem recusada (codigo = 401)

content-type: application/json

body:

{
 "certifaceID": {
 "protocolo": "209901234567",
 "codigo": 401,
 "score": 0
 }
}

Exemplo 3: Erro interno (codigo = 501)

content-type: application/json

body:

{
 "certifaceID": {
 "protocolo": "209901234567",
 "codigo": 501,
 "score": 0
 }
}

Detalhamento da resposta: Tabela "certifaceID"

Tabela "certifaceID.codigo"

Retorno 200 OK - Erros de validação Observação: O formato do JSON de retorno para erros de validação é diferente.

Exemplo 4: Erro de validação de dados de entrada

content-type: application/json

body:

{
 "status": "ERR",
 "resultado": "ERR",
 "protocolo": "209901234567",
 "msg": "INVALID"
}

Exemplo 5: Erro de usuário menor de idade

NOTA: Retorno habilitado via config. TRATAMENTO_MENOR_IDADE, desabilitado por padrão.

content-type: application/json

body:

{
 "status": "ERR",
 "resultado": "BMI",
 "protocolo": "209901234567",
 "msg": "USER IS UNDER 13: [12]"
}

Tabela "certifaceErro"

Tabela "certifaceErro.status"

Tabela "certifaceErro.resultados"

Retorno 400 BAD REQUEST Requisição form-data mal formada. Retorno 401 UNAUTHORIZED Não autorizado (credencial de acesso não informada, inválida ou expirada).