By Certiface

Visão geral

O serviço de validação biométrica com prova de vida está disponível através de uma API REST chamada Certiface Token API. Essa API gera um token único por cliente, para cada processo que ele realizar. A imagem a seguir apresenta o fluxo de acesso ao serviço de validação biométrica com prova de vida:

Diagrama de sequência

Passos

O Certiface Token API possui 5 passos de execução:

1. Login/Autenticação
2. Geração do acesso à prova de vida - criação do Token
3. Prova de vida (realizada no dispositivo do cliente)
4. Notificação de conclusão (webhook)
5. Consulta do resultado

1) Método Login (Autenticação)

O login é o primeiro método que deverá ser acessado para gerar as credenciais JWT, que será utilizada para acessar os demais métodos desta API. Para realizar o acesso, deverá ser informado o login e a senha de acesso à integração e, em caso de sucesso, o serviço irá retornar as credenciais JWT.

Segue um exemplo de Request e Response ao método login:

Request

POST https://www.certiface.com.br/certifacetoken3d/login Content-Type: application/json Body:

{
	"login": "login",
	"password": "md5Password"
}

Nota: O endereço https://hml.certiface.com.br/certifacetoken/ 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/certifacetoken/.

Response

HTTP 200 OK

content-type: application/json authorization: Bearer eyJhbGciOiJIU.eyJzdWIiOiJ7XCJsb2dpb body: Bearer eyJhbGciOiJIU.eyJzdWIiOiJ7XCJsb2dpb

{
  "token": "yJhbGciOiJIU.eyJzdWIiOiJ7XCJsb2dpb..."
}

HTTP 400 BAD REQUEST

Requisição mal formada ou dados não foram informados corretamente

HTTP 401 UNAUTHORIZED

Não autorizado

HTTP 403 FORBIDDEN

Proibido – você não tem permissão para acessar

2. Criação do Token (geração de acesso à prova de vida)

Para acessar o serviço de prova de vida, um token único deverá ser criado, informando os dados do cliente e as credenciais JWT geradas no passo anterior. O Certiface irá gerar uma URL única, que deverá ser utilizada pelo cliente que solicitou o processo para realizar a validação biométrica com prova de vida.

Segue um exemplo de Request e Response ao método gentoken:

Request

POST https://www.certiface.com.br/certifacetoken3d/api/v2/protected/genToken Content-Type:application/json Authorization:(resultado gerado no método login) body:

{
  "documentType": 1,
  "documentNumber": "00000014141",
  "birthDate": "20/12/1960",
  "fullName": "Nome Sobrenome",
  "phone": "11977777777",
  "listPhone": ["11111111111", "22222222222", "33333333333"],
  "processType": "ALT"
}

Nota: A URL para o cliente realizar o processo pode ser enviado via SMS pela API para o telefone informado como padrão (por meio de configuração customizada)

Response

HTTP 200 OK

content-type: application/json body:

{
  "uuid": "e8ec1a0e-a6a4-43b8-b0a7-3e59b855cea8",
  "url": "http://www.certiface.com.br/certifacetoken/facecaptcha/token/e8ec1a0e-a6a4-43b8-b0a7-3e59b855cea8"
}

HTTP 400 BAD REQUEST

Requisição mal formada ou dados não foram informados corretamente

HTTP 401 UNAUTHORIZED

Não autorizado

HTTP 403 FORBIDDEN

Proibido – você não tem permissão para acessar

3. Prova de Vida

O seu cliente deve executar os passos solicitados pelo Certiface, para ser realizada a sua autenticação biométrica. Ao final do processo, o Certiface irá notificar a Empresa através de um método webhook descrito no próximo passo.

4. Notificação de conclusão (webhook)

O Certiface Token API notificará a conclusão da prova de vida assim que o seu cliente finalizar o processo. Esta notificação será enviada para um endpoint especificado pela Empresa através de método webhook configurável GET ou POST, conforme definido a seguir:

Nota: A empresa deve manter este endpoint ativo para que se possa receber a notificação de conclusão e notificar qualquer alteração no método de envio ou na forma de autenticação deste.

Exemplo GET

GET https://host/servername/*/TOKEN (definido pelo cliente)

Exemplo POST

POST https://host/servername/*/ (definido pelo cliente) Content-Type: application/json body:

{
  "token": "e8ec1a0e-a6a4-43b8-b0a7-3e59b855cea8"
}

Nota: O endpoint para o qual o webhook será enviado (quando for um HTTP POST) pode ter autenticação por OAuth2 configurada, sendo necessário que o Cliente envie um ID, Secret e endpoint de autenticação para isto

Exemplo de endpoint de autenticação OAuth:

POST https://host/servername/*/auth (definido pelo cliente) Content-Type: application/x-www-form-urlencoded body:

grant_type=client_credentials
client_id=[gerado pelo Cliente]
client_secret=[gerado pelo Cliente]

Exemplo de retorno esperado:

Content-Type: application/json

{
  "access_token":"MTQ0NjJkZmQ5OTM2NDE1ZTZjNGZmZjI3",
  "token_type":"Bearer",
  "expires_in":3600,
  "refresh_token":"IwOGYzYTlmM2YxOTQ5MGE3YmNmMDFkNTVk",
  "scope":"create"
}

Nota: O access_token obtido no método de autenticação acima será enviado no header Authorization.

5. Consulta ao resultado

O resultado da prova de vida deverá ser consultado conforme o exemplo a seguir:

Request

GET https://www.certiface.com.br/certifacetoken3d/api/v2/protected/token/ Authorization: (resultado gerado no método login)

Response

HTTP 200 OK

content-type: application/json body:

{
  "token": "54070abe-e6d9-4a05-80f6-dbab76812c7e",
  "documentType": 1,
  "documentNumber": "08136822824",
  "birthDate": "01/01/2001",
  "fullName": "Nome Sobrenome",
  "phone": "11111111111",
  "createDate": "2018-07-24 13:11:35",  
  "expirationDate": "2018-07-24 13:11:35",
  "status": true,
  "result": true,
  "listPhone": ["0000000000", "11111111111", "22222222222"],
  "processType": "resgate",
  "results": [
    {
      "protocol": "201800009979",
      "dateTime": "2018-07-24 19:11:35",
      "cause": "PROVA DE VIDA",
      "valid": false,
      "userAgent": "Mozilla/5.0 Chrome/67.0.3396.87 Mobile",
      "arrived": "QRCode",
      "result": 300.1,
      "geolocation": {
        "accuracy": 65.0,
        "latitude": -23.550783331791404,
        "longitude": -47.47902840915128,
        "altitude": 628.3499755859375,
        "altitudeAccuracy": 16.209877014160156
      }
    },
    {
      "image": "Imagem base64",
      "protocol": 201800009980,
      "dateTime": "2018-07-24 19:12:20",
      "cause": "SUCESSO",
      "valid": true,
      "userAgent": "Mozilla/5.0 Chrome/67.0.3396.87 Mobile",
      "arrived": "QRCode",
      "result": 1.2,
      "geolocation": {
        "accuracy": 65.0,
        "latitude": -23.550783331791404,
        "longitude": -47.47902840915128,
        "altitude": 628.3499755859375,
        "altitudeAccuracy": 16.209877014160156
      }
    }
  ]
}

Detalhamento do array de objetos Results

Detalhamento dos resultados do campo “cause”:

	SUCESSO: Quando o usuário realiza os desafios corretamente e realiza Cadastro ou certificação Positiva.
	FACE NÃO ENCONTRADA: Quando o sistema não encontra face na imagem frontal.
	QUALIDADE IMAGEM: Quando a imagem frontal não tem qualidade para certificação ou cadastro.
	BIOMETRIA: Existe algum problema com o cadastro (Semelhantes) ou certificação (Baixa similaridade)
	PROVA DE VIDA: Quando o usuário não realiza os desafios corretamente.
	DADOS INVÁLIDOS: Quando o nome, documento, nascimento são inválidos.
	TIMEOUT: Quando a prova de vida expira o tempo máximo de utilização (parametrizável)
	QUANTIDADE: Quando o cliente não realiza os desafios corretamente em 3 tentativas.
	CANCELADO: Quando o cliente cancela a prova de vida.

Detalhamento dos resultados do campo “result”:

	1.1: Cadastro com sucesso.
	1.2: Certificação positiva.
	200.1: Cadastro com alertas.
	200.2: Certificação negativa.
  300.1: Prova de vida inválida.
  300.2: Prova de vida bloqueada.

Detalhamento do objeto Geolocation

HTTP 400 BAD REQUEST

Requisição mal formada ou dados não foram informados corretamente

HTTP 401 UNAUTHORIZED

Não autorizado

HTTP 403 FORBIDDEN

Proibido – você não tem permissão para acessar

HTTP 404 NOT FOUND

Token não encontrado ou URL mal formada