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.
  • 401
  • 422CPF 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.
  • 401
  • 404

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.
  • 401
  • 404

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.
  • 401
  • 422Nenhum 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.
  • 401
  • 404
  • 422Quadro 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.
  • 401
  • 404
  • 422Pessoa 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.
  • 401
  • 404
  • 413Mais 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 sem instantesMs vá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.
  • 401
  • 404

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.
  • 401
  • 404
  • 422Batida ainda sem desfecho (urn:nexusquery:problema:comprovante-indisponivel).
  • 503Comprovante desligado neste ambiente (urn:nexusquery:problema:comprovante-indisponivel).