Certiface REST API

Sumário

• Introdução
• Visão geral
• Método Autenticação
  • Gerar hash MD5 em Linux
  • Request
  • Response
• Método Certiface
  • Request
  • 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

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

Request: POST https://hml.certiface.com.br/CertiFaceWS/rs/certiface/consulta-aderencia Content-Type: multipart/form-data Authorization: login;UUTKyf8qcxvvHs6M_ueOmoEFwYxvXE4DAeULKeoHr3o; Date: 04/12/2025 17:01:19

Body:

cpf: "00000014141"
nome: "Nome Completo"
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:

var verb = 'POST';
var pathCertiface = '/rs/certiface/consulta-aderencia';
var expires = '04/10/2025 14:15:35';
var login = 'login'
var token = 'WdCFs9ytXJC52RWV5jmynEIKVd0xpKH6JSi7HVeoMz8';
 
var textToSign = (verb + pathCertiface + expires);	// Concatena o texto
var hash = CryptoJS.HmacSHA256(textToSign, token);	// Gera hash SHA256
 
var hashInBase64Safe = hashInBase64.replace(/\+/g, '-').replace(/\//g, '_').replace(/\=+$/, '');	// Converte em base64 Safe
var signature = login + ';' + hashInBase64Safe + ';' + expires;	// Concatena a chave da assinatura
 
// Ex signature: login;dBCOXryPKKnsHid9d6JZpNP8W0946PL5ymOxypX88NU;04/10/2025 14:15:35

Response

Retorno 200 OK

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

Indica que o usuário com o CPF informado consta na base biométrica.

content-type: text/plain

body:

"certifaceID": {
  "protocolo": "2025123456700",
  "codigo": 203, 
  "aprovado": true,
  "conhecido": false,
  "score_biometrico": 92.3
}

Exemplo 2: Dados informados incorretamente ou requisição mal formada (Retorno = 400)

content-type: application/json

body:

{
    "status": "ERR",
    "resultado": "ERR",
    "protocolo": "202001138311",
    "msg": "INVALID CPF"
}

Exemplo 3: Imagem recusada (codigo = 401)

content-type: application/json

body:

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

Exemplo 4: 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).

Retorno 404 NOT FOUND Usuário não possui biometria registrada em nossa base.