Utilizando o Biovalid
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
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&qtd_tentativas=5"
Tambem é possível configurar a quantidade máxima de tentativas para passar no liveness no parâmtro qtd_tentativas. Caso não seja informado a quantidade de tentativas é ilimitada.
2. Envio da foto
Existem três formas de envio da foto capturada para o Biovalid: através do App Biovalid, App do cliente com BioConnect ou através do consumo do cliente da API de validação Biovalid.
App Biovalid
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 o BioConnect
Este componente destina-se para clientes que possuem aplicação e não querem desenvolver o processo de captura da foto. Atualmente está disponível para Android.
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.
Para fazer a chamada à API de validação, o cliente deve fazer um HTTP PUT conforme exemplo do ambiente de demonstração, passando o CPF, o Pin biométrico (gerado no passo 1), a informação do dispositivo utilizado para captura, a foto capturada e opcionalmente o gênero da pessoa para também ser validado.
curl --request PUT \
--url https://gateway.apiserpro.serpro.gov.br/biovalid-trial/v1/liveness \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer 06aef429-a981-3ec5-a1f8-71d38d86481e' \
--header 'x-cpf: <cpf>' \
--header 'x-pin: <pin>' \
--header 'x-sexo: <M ou F>' \
--header 'x-device: <model+version>' \
--data '{
"selfie": "base64 da foto"
}'
Para saber quais são os requisitos da foto a ser enviada acesse aqui
Códigos e Mensagens da API de Validação
| Código | Mensagem | HTTP | Versão |
|---|---|---|---|
| 1 | pin expirado | 422 | v1 e v2 |
| 2 | pin já validado | 422 | v1 e v2 |
| 3 | pin não encontrado | 422 | v1 e v2 |
| 5 | parâmetros de entrada inválidos | 422 | v1 e v2 |
| 6 | foto não encontrada | 422 | v1 e v2 |
| 7 | foto não reconhecida como real | 422 | v1 e v2 |
| 8 | usuário não possui cnh cadastrada na base do denatran | 422 | v1 e v2 |
| 9 | usuário não possui foto cadastrada na base de dados de cnh do denatran | 422 | v1 e v2 |
| 10 | device é obrigatório | 422 | v1 e v2 |
| 11 | baixa qualidade da imagem | 422 | v1 |
| 12 | quantidade de tentativas excedida | 422 | v1 |
| - | autorização para envio de foto expirada | 401 | v1 e v2 |
| - | push token inválido | 403 | v1 e v2 |
| - | erro ao validar autorização | 500 | v1 e v2 |
| - | erro interno do servidor | 500 | v1 e v2 |
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, o resultado da biometria, data e hora em que a prova de vida foi realizada e o gênero validado da pessoa (opcional).
Exemplo decodificado.
{
"iss": "biovalid",
"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
},
"sexo": true,
"selo_biometrico": "B",
"token": "RBPR6YFE3",
"data_prova_de_vida": "dd/MM/yyyy HH:mm:ss",
"kba_cliente_valido": true
}
Outra opção é configurar uma URL de Callback.
4. 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." }