Certiface REST API

Sumário

• Introdução
• Visão geral
• Ambientes
• Método Autenticação
• Método Certiface
  • Request
  • Response
    • Retorno por codID
    • Retorno por classe de risco
    • Tratamento de erros
  • Casos de uso e retornos esperados
  • Exemplos de teste em homologação

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.

Ambientes

É bom saber!
Os endereços de homologação devem ser utilizados apenas para o desenvolvimento e homologação da integração. Para produção, substitua hml.certiface.com.br por www.certiface.com.br.

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

Homologação

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

Produção

POST https://www.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

Site de apoio

Response

Retorno 200 OK
content-type: application/json

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

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

Homologação

POST https://hml.certiface.com.br/CertiFaceWS/rs/certiface

Produção

POST https://www.certiface.com.br/CertiFaceWS/rs/certiface

Content-Type: multipart/form-data

Headers

Atenção especial ao header Authorization:

• É composto por 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 (campo expires).
• O hash de autorização deve ser gerado com o algoritmo SHA256, a partir do tipo do método (POST) + URL + data_e_hora_de_expiração como texto base, e o token retornado no método Autenticação como chave.

Body

Exemplo da chamada:

POST /CertiFaceWS/rs/certiface HTTP/1.1
Host: hml.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

O formato do retorno depende da sua integração. Identifique-o pelos campos que você recebe na resposta:

Retorno por codID

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
  }
}

Tabela "certifaceID"

Tabela de códigos e recomendações

A tabela abaixo apresenta os códigos de retorno da API, suas respectivas descrições e a recomendação de ação, considerando também o campo conhecido quando aplicável.

Retorno por Classe de risco

Se a integração utiliza Classe de risco, expanda o item abaixo para ver o detalhamento do retorno.

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

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

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

Tratamento de erros

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"

Casos de uso e retornos esperados

Esta seção apresenta exemplos de retorno da API para os principais cenários de validação facial. Cada exemplo mostra a resposta completa e explica o que ela significa, para que você saiba como tratá-la na sua integração.

Para a ação recomendada em cada combinação de codigo e conhecido, consulte a Tabela de Recomendação.

Retornos esperados por código

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

{
  "certifaceID": {
    "codigo": 202,
    "aprovado": false,
    "conhecido": false,
    "protocolo": "00000000",
    "score_biometrico": 0.0
  }
}

{
  "certifaceID": {
    "codigo": 203,
    "aprovado": true,
    "conhecido": true,
    "protocolo": "00000000",
    "score_biometrico": 100.0
  }
}

{
  "certifaceID": {
    "protocolo": "202602568659",
    "codigo": 203,
    "aprovado": true,
    "conhecido": false,
    "score_biometrico": 89.8
  }
}

{
  "certifaceID": {
    "codigo": 204,
    "aprovado": false,
    "conhecido": true,
    "protocolo": "00000000",
    "score_biometrico": -72.30
  }
}

{
  "certifaceID": {
    "codigo": 204,
    "aprovado": false,
    "conhecido": false,
    "protocolo": "00000000",
    "score_biometrico": -42.78
  }
}

{
  "certifaceID": {
    "codigo": 212,
    "aprovado": false,
    "conhecido": false,
    "protocolo": "00000000",
    "score_biometrico": 0.0
  }
}

{
  "certifaceID": {
    "codigo": 401,
    "aprovado": false,
    "conhecido": false,
    "protocolo": "00000000",
    "score_biometrico": 0.0
  }
}

Exemplos de teste em homologação

201: Cadastro com sucesso

Use um CPF e uma foto aleatórios:

• Foto: This Person Does Not Exist
• CPF: Gerador de CPF – 4Devs

202: Cadastro com pendência

Utilize os dados abaixo, pois essa face já está cadastrada para outro CPF.

• CPF: Gerador de CPF – 4Devs

• Imagem:

  

203: Certificação positiva (conhecido = true)

Utilize os dados abaixo, pois essa face e esse CPF já estão cadastrados com conhecido = true.

• CPF: 34386679081

• Imagem:

  

203: Certificação positiva (conhecido = false)

Repita a mesma requisição realizada no teste do 201: Cadastro com sucesso, com o mesmo CPF e a mesma imagem. Como o cadastro já existe, será gerada uma certificação positiva com o campo conhecido definido como false.

204: Certificação negativa (conhecido = true)

Utilize os dados abaixo, pois esse CPF já está cadastrado com conhecido = true.

• CPF: 34386679081

• Imagem:

  

204: Certificação negativa (conhecido = false)

Utilize o mesmo CPF do teste do 201: Cadastro com sucesso, com uma imagem diferente da usada naquele cadastro.

• CPF: o mesmo utilizado no cadastro com sucesso

• Imagem:

  

212: Cadastro com risco

Utilize os dados abaixo, pois essa face já está restrita na base de homologação.

• CPF: aleatório, gerado em Gerador de CPF – 4Devs

• Imagem:

  

401: Falha de assessment

Utilize os dados abaixo:

• CPF: aleatório, gerado em Gerador de CPF – 4Devs

• Imagem: um quadrado preto (imagem sem face)