Utilizando a API

De posse do Token de Acesso, faça a requisição a um dos serviços.

1. Fazendo uma requisição para a criação do PIN biométrico

Fluxo de Criação do PIN Biométrico

curl -X POST --header "Authorization: Bearer 06aef429-a981-3ec5-a1f8-71d38d86481e" "https://gateway.apiserpro.serpro.gov.br/biovalid-trial/v1/token?cpf=11111111111"

Retorno esperado: RBPR6YFE3

O PIN também pode ser criado usando um dos tipos de KBA (Knowledge-Based Authentication), sendo o do tipo Datavalid ou um próprio. O KBA está disponível atualmente apenas para os clientes que utilizam o App Biovalid.

Quando o KBA do tipo Datavalid for utilizado, os campos são fixos com base na CNH, sendo:

categoria
numero de registro
data de validade

Para utilizar este tipo de KBA, basta informar o parâmetro kba_datavalid na URL durante a criação do PIN, conforme exemplo abaixo.

curl -X POST --header "Authorization: Bearer 06aef429-a981-3ec5-a1f8-71d38d86481e" "https://gateway.apiserpro.serpro.gov.br/biovalid-trial/v1/token?cpf=11111111111&kba_datavalid=true"

Para utilizar um KBA próprio, basta informar as perguntas no corpo da requisição, conforme exemplo abaixo.

curl -X POST \
  --url 'https://gateway.apiserpro.serpro.gov.br/biovalid-trial/v1/token?cpf=11111111111' \
  --header 'Content-Type: application/json' \
  --header 'Authorization': 'Bearer 06aef429-a981-3ec5-a1f8-71d38d86481e' \
  --data '[ 
  { "pergunta": "Qual sua data de aniversário?", "resposta": "22/06/1983", "tipo": "DATE" }, 
  { "pergunta": "Você tem filhos?", "resposta": "true", "tipo": "BOOLEAN" }, 
  { "pergunta": "Qual o nome da sua mãe?", "resposta": "Marcia", "tipo": "TEXT" } 
]'

Os tipos das perguntas podem ser:

DATE no formato dd/MM/yyyy
BOOLEAN no formato true ou false
TEXT pode ser um texto livre
NUMERIC do tipo número inteiro

Não é possível usar os dois tipos de KBA's ao mesmo tempo. Caso seja informado os dois KBA's na criação do PIN, o KBA Datavalid será o utilizado.

Caso seja necessário, é possível definir um tempo de uso para o PIN em minutos. Ou seja, o usuário só pode enviar a foto em até X minutos após a criação do PIN. Para definir o tempo de uso, adicionar o parâmetros expira_em na URL, conforme exemplo abaixo de 5 minutos.

curl -X POST --header "Authorization: Bearer 06aef429-a981-3ec5-a1f8-71d38d86481e" "https://gateway.apiserpro.serpro.gov.br/biovalid-trial/v1/token?cpf=11111111111&expira_em=5"

2. Envio da foto

Existem duas formas de envio da foto capturada para o Biovalid: através do App Biovalid ou através do App do cliente utilizando a API de validação Biovalid.

App Biovalid

Fluxo de Biométrico

Utilizando o App Biovalid, não é necessária nenhuma ação por parte do cliente para envio da foto capturada, uma vez que a utilização do aplicativo é feita pelo usuário final. O cliente só deve recuperar o resultado.

App do Cliente utilizando a API de validação Biovalid

Além do fluxo pelo App Biovalid, há a possibilidade da captura da foto pelo cliente e envia-la diretamente a API do Biovalid.

Fluxo de Biométrico

Para fazer a chamada à API de validação, o cliente deve fazer um HTTP POST conforme exemplo do ambiente de demonstração, passando o CPF, o Pin biométrico (gerado no passo 1) e a foto capturada.

curl --request POST \
  --url https://d-biodata.estaleiro.serpro.gov.br/liveness/v2 \
  --header 'Content-Type: application/json' \
  --header 'x-cpf: <cpf>' \
  --header 'x-pin: <pin>' \
  --data '{
    "selfie": "base64 da foto"
}'

Para saber quais são os requisitos da foto a ser enviada acesse aqui

Mensagens e códigos de retorno para a API de Validação

Exceções lançadas pelo Biovalid em caso de erros durante o processo de validação.

Código	Mensagem	HTTP
1	pin expirado	422
2	pin já validado	422
3	pin não encontrado	422
5	parâmetros de entrada inválidos	422
6	foto não encontrada	422
7	foto não reconhecida como real	422
8	usuário não possui cnh cadastrada na base do denatran	422
9	usuário não possui foto cadastrada na base de dados de cnh do denatran	422
-	autorização para envio de foto expirada	401
-	push token inválido	403
-	erro ao validar autorização	500
-	erro interno do servidor	500

Todas as exceções com o código HTTP 422 são encapsuladas dentro de um json conforme exemplo.

{
  "codigo": <numero>,
  "mensagem": "descrição da exceção"
}

3. Pegar o resultado da validação biométrica.

Após a realização da prova de vida com a validação facial pelo usuário é necessário chamar a API para pegar o resultado conforme abaixo.

curl -X GET --header "Authorization: Bearer 06aef429-a981-3ec5-a1f8-71d38d86481e" "https://gateway.apiserpro.serpro.gov.br/biovalid-trial/v1/token?cpf=11111111111&token=RBPR6YFE3"

Retorno:

Quando o retorno for com sucesso é esperado é um JWT codificado em base64. Ao decodifica-lo, será possível ver o PIN, CPF e o resultado da biometria.

Exemplo decodificado.

{
  "iss": "biodata",
  "iat": 1592319844,
  "exp": 1592321644,
  "aud": "Demonstração",
  "sub": "11111111111",
  "filiacao": {},
  "cnh": {
    "categoria": true,
    "numero_registro": false,
    "data_validade": false
  },
  "documento": {},
  "endereco": {},
  "cpf_disponivel": true,
  "biometria_face": {
        "disponivel": true,
      "probabilidade": "Altíssima probabilidade",
      "similaridade": 0.970771181293467
  },
  "token": "RBPR6YFE3",
  "data_prova_de_vida": "dd/MM/yyyy HH:mm:ss",
  "kba_cliente_valido": true
}

Outra opção é configurar uma URL de Callback.

Exemplo em Java para validação do JWT

Existem bibliotecas que auxiliam a validação do JWT nos mais diversos tipos de linguagem de programação, como Java, Javascript e Go. Abaixo, exemplo de código Java "puro" para validar o JWT emitido.

BigInteger modulus = new BigInteger(1, Base64.getDecoder().decode("AMsOCt+hq2CyFx....qzRwzN"));
BigInteger exponent = new BigInteger(1, Base64.getDecoder().decode("AQAB"));
RSAPublicKey pubKey = (RSAPublicKey) KeyFactory.getInstance("RSA").generatePublic(new RSAPublicKeySpec(modulus, exponent));
Jws<Claims> claimsJws = Jwts.parser()
        .setSigningKey(pubKey)
        .parseClaimsJws("eyJhbGciOiJSUzUx...");

A chave pública pode ser obtida aqui. As chaves estão no padrão JWKS.

Quando for utilizado o KBA definido pelo cliente, o campo kba_cliente_valido informa se o usuário informou as respostas corretamente (true) ou não informou corretamente (false). Já quando a opção foi utilziar o KBA do Datavalid, os campos dentro de CNH devem ser conferidos, sendo para as respostas corretas (true) e as incorretas (false).

EXCEÇÕES

Se por algum motivo o usuário ainda não fez a biometria, o retorno esperado é:

{ "codigo": "5", "mensagem": "Sem informações de biometria." }

Se o usuário já fez a biometria mas sem a possibilidade de validação por parte do Biovalid, o retorno esperado é:

{ "codigo": "12", "mensagem": "Usuário não possui CNH ou Foto na base do DENATRAN para validação biométrica." }

422 Requisição inválida - Parâmetros de entrada inválido.

401 Não Autorizado - Token de Autorização inválido.

404 Não Encontrado - Resultado não encontrado.

500 Erro Interno Servidor - Erro interno do servidor.