NexusID — Biometria facial
Reconhecimento facial em vários passos: cadastrar a pessoa, guiar a captura, cadastrar o rosto e conferir a cada batida, com prova de vida opcional (a pessoa gira a cabeça, pisca e sorri na ordem que o servidor sortear). Cada passo é uma rota, na ordem em que o seu aplicativo chama.
Cadastra a pessoa que vai bater o ponto
POST/v1/biometria/pessoas
Identifica a pessoa pelo CPF. O banco guarda o CPF inteiro cifrado, o HMAC (para achar a mesma pessoa) e o miolo, e a resposta devolve o CPF inteiro e formatado, 111.444.777-35. A pessoa cadastrada antes disso só tem o miolo até o próximo cadastro e volta como ***.444.777-**. Cadastrar o mesmo CPF de novo devolve a mesma pessoa. Não cobra: só a batida cobra.
Respostas
201Pessoa cadastrada.401422CPF inválido (urn:nexusquery:problema:cpf-invalido).
Mostra a pessoa e quantos cadastros de rosto ela tem
GET/v1/biometria/pessoas/{id}
Respostas
200A pessoa.401404
Elimina a pessoa e todo o material biométrico dela
DELETE/v1/biometria/pessoas/{id}
Apaga os rostos cadastrados e devolve quantos eram — o comprovante de eliminação (LGPD). O CPF volta a poder ser cadastrado; as batidas já feitas seguem no histórico, sem nada do rosto.
Respostas
200Eliminada.401404
Guia de captura — onde está o rosto e se a imagem serve
POST/v1/biometria/enquadramento
Um quadro por chamada, enquanto a pessoa se posiciona na câmera. Devolve a posição do rosto e se a captura serve, para o app avisar ("aproxime o rosto", "mais luz") antes de abrir a batida. Não cobra. Exige chave porque roda o detector. A porta de qualidade pede rosto ocupando pelo menos 8% do quadro — captura de perto, como uma selfie de portaria.
Respostas
200O que a câmera está vendo.401422Nenhum quadro, mais de um, ou quadro que não é base64 (urn:nexusquery:problema:quadros-invalidos).
Guarda o rosto da pessoa
POST/v1/biometria/cadastros
Manda de 1 a 8 quadros JPEG em base64 (512 KB cada). O motor extrai o vetor de identidade e o guarda cifrado; nenhuma imagem é gravada. Até 5 cadastros por pessoa. Quadro sem rosto ou sem nitidez responde aceito: false com o motivo — não é erro e não cobra.
Respostas
201Cadastro aceito ou recusado com motivo.401404422Quadro que não é base64 (quadros-invalidos) ou teto de cadastros (limite-de-cadastros).
Abre a batida e devolve o token de captura
POST/v1/biometria/verificacoes
Abre a verificação da pessoa e devolve o tokenDeCaptura, que vale 2 minutos e aparece uma única vez. Abrir não cobra.
Prova de vida ativa (opcional). Com "desafio": true, a resposta traz o desafio que o servidor sorteou para esta batida: três passos, na ordem em que a pessoa deve fazer, tirados de girar (para a esquerda ou a direita, de 15 a 30 graus), piscar (1 ou 2 vezes) e sorrir. Sempre há pelo menos um giro. Mostre um passo por vez e grave os quadros durante o movimento, não só no fim: o que conta é a passagem de um estado para o outro. Esquerda e direita são do ponto de vista da pessoa. Envie os quadros como a câmera vê, sem espelhar, mesmo que a pré-visualização na tela seja espelhada. O desafio é sempre do servidor: o que o seu app mandar de desafio é ignorado. Sem desafio, a batida funciona como antes.
Respostas
201Batida aberta.401404422Pessoa sem cadastro biométrico (urn:nexusquery:problema:sem-cadastro-biometrico).429Limite de gasto do dia (limite-do-dia) ou de requisições (muitas-requisicoes).
Conclui a batida com os quadros capturados
POST/v1/biometria/verificacoes/{id}/quadros
Compara os quadros com o rosto cadastrado e fecha a batida. Desfecho confere, nao_confere ou suspeita_de_fraude cobra; nao_emitida (sem rosto, sem nitidez, token vencido, desafio não cumprido) não cobra. Reenviar o mesmo token devolve o mesmo desfecho e cobra uma vez só. A prova de vida passiva entra como registro na resposta e nunca decide sozinha o desfecho.
Batida com desafio. Envie de 1 a 24 quadros, na ordem em que foram capturados, e instantesMs: um número por quadro, os milissegundos desde o primeiro (começa em 0 e sempre cresce). Ritmo de captura: 3 a 4 quadros por segundo nos giros e no sorriso, e 8 a 10 por segundo durante o passo de piscar, porque uma piscada dura menos de meio segundo. Gire devagar, em cerca de 1 segundo. Quem não cumpre o desafio recebe nao_emitida com a explicação "O desafio pedido não foi cumprido." e não é cobrado. Desafio não cumprido nunca vira suspeita_de_fraude: pode ser luz fraca, câmera ruim ou uma pessoa com dificuldade de movimento. O campo provaDeVidaAtiva diz o que aconteceu e, por enquanto, não é decisivo para fraude.
Respostas
200Batida concluída.401404413Mais de 24 quadros, quadro acima de 512 KB ou mais de 5 MB no total (urn:nexusquery:problema:quadros-invalidos). Nada é cobrado.422Quadro que não é JPEG em base64, ou batida com desafio seminstantesMsválido (urn:nexusquery:problema:quadros-invalidos). Nada é cobrado.503Motor de biometria indisponível (urn:nexusquery:problema:produto-indisponivel). Nada é cobrado.
Mostra a batida e o desfecho
GET/v1/biometria/verificacoes/{id}
Respostas
200A batida.401404
Comprovante assinado da batida
GET/v1/biometria/verificacoes/{id}/comprovante
Devolve um JWS compacto (ES256) com o desfecho, a evidência e o digest dos quadros. O cliente guarda esse comprovante e qualquer um confere depois, sozinho e sem chave de API, com a chave pública de /.well-known/jwks.json. Nenhuma imagem entra no comprovante, e o CPF aparece inteiro e formatado (pessoa eliminada se a pessoa já foi eliminada). Só batida concluída tem comprovante.
A data e a hora da batida (concluidaEm) seguem a Hora Legal Brasileira. Quando a hora foi conferida na conclusão, o comprovante traz horaLegal com a fonte: Observatório Nacional (NTP.br). Sem a conferência o campo não vem, e a hora é a do relógio do servidor.
O comprovante traz provaDeVidaAtiva: a situacao (cumprida, nao_cumprida, nao_avaliada ou nao_pedida) e, quando houve desafio, o id e os passos pedidos, com decisiva: false enquanto os limites não forem calibrados.
Respostas
200O comprovante.401404422Batida ainda sem desfecho (urn:nexusquery:problema:comprovante-indisponivel).503Comprovante desligado neste ambiente (urn:nexusquery:problema:comprovante-indisponivel).