Certiface REST API

Sumário

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

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

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.

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. Além da validação biométrica, também estão disponíveis (sob demanda) validações em outras bases de dados.

O retorno apresenta o status da transação e o resultado da validação biométrica, auxiliando na decisão de aprovar, revisar ou reprovar o cliente.

Request

POST https://comercial.certiface.com.br/CertiFaceWS/rs/certiface/consulta-aderencia

Content-Type: multipart/form-data

Headers

Exemplo:

Authorization: login;UUTKyf8qcxvvHs6M_ueOmoEFwYxvXE4DAeULKeoHr3o;
Date: 04/12/2025 17:01:19

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 retornadas pelo método Autenticaçã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 Autenticação como chave.

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

Body

Exemplo:

cpf: "00000014141"
nome: "Nome Completo"
nascimento: "01/01/2001"
imagem: "/9j/4AAQSkZJRgABAg.....VDc4DGpaKuf/9k="

Site de Apoio

Response

Retorno 200 OK

Exemplo 1: Transação efetuada com sucesso

content-type: application/json

body:

{
  "certifaceID": {
    "codigo": 201,
    "aprovado": true,
    "conhecido": false,
    "protocolo": "2026233477187",
    "score_biometrico": 0.0
  }
}

{
  "certifaceID": {
    "codigo": 201,
    "aprovado": true,
    "conhecido": false,
    "protocolo": "2026233477187",
    "score_biometrico": 0.0,
    "serpro": {
      "codigo": 200,
      "causa": "Validacao positiva",
      "score": 0.95203865
    }
  }
}

Retorno 201 OK

Exemplo 3: Cadastro com sucesso

content-type: application/json

body:

{
  "certifaceID": {
    "codigo": 201,
    "aprovado": true,
    "conhecido": false,
    "protocolo": "10260002605634"
  }
}

Retorno 401

Exemplo 4: Imagem recusada

Este retorno ocorre quando a imagem enviada não atende aos requisitos mínimos de qualidade ou formato exigidos para processamento.

Recomendações de qualidade de imagem:

• Resolução de pelo menos 640 x 480 px (VGA) ou 320 x 480 (quando vertical recortada)
• Tamanho até 1 MB
• Formato JPG/JPEG
• Sem redimensionamento (alargar ou reduzir)
• Sem edição ou outros elementos (imagem limpa, sem tarjas, textos, filtros)
• Qualidade/compressão mínima de 85% (sem artefatos ou perda excessiva de qualidade)
• O recorte deve respeitar as proporções da face e as dimensões mínimas exigidas para a imagem

content-type: application/json

body:

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

Retorno 501

Exemplo 5: Erro interno

content-type: application/json

body:

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

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 6: Erro de validação de dados de entrada

content-type: application/json

body:

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

Exemplo 7: Erro de usuário menor de idade

NOTA: Quando o bloqueio por idade estiver habilitado, conforme configuração definida pelo cliente, usuários menores de idade terão a solicitação bloqueada, retornando o erro abaixo. Por padrão, esse tratamento não está habilitado.

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"