Ctrlk
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Autenticar usuário V3

/authenticateUser/v3

Descrição

Este serviço fornece persistência de Template Biométrico e Authentication facial 1:1 contra templates armazenados. Suporta dois modos operacionais dentro de um único Endpoint, determinados pelo corpo da solicitação:

  • Modo Enroll: Valida o teste de vida e realiza um Matching facial entre um Template Biométrico fornecido e uma captura ao vivo, e depois persiste o template associado a um userId.

  • Modo Authenticate: Recupera um template previamente armazenado por userId e realiza um Matching facial 1:1 e validação de teste de vida contra uma nova captura ao vivo.

Funcionalidade

  • Enroll: É enviado o userId junto com o Template Biométrico (templateRaw) e a melhor imagem tokenizada (bestImageToken). Valida-se o teste de vida e o Matching facial. Se ambos forem bem-sucedidos, o template associado ao usuário é persistido. Se o usuário já existir, o template é atualizado.

  • Authenticate: É enviado o userId junto com o bestImageToken da sessão atual. Recupera-se o template armazenado e realiza-se um Matching 1:1 contra a captura ao vivo. O resultado da Authentication é retornado com a pontuação de similaridade.

Casos de uso

  1. Cliente sem onboarding prévio com Facephi: Durante a recuperação de senha, o cliente realiza um Onboarding que gera um Template Biométrico. Esse template é cadastrado por meio deste Endpoint e associado a um userId. As futuras recuperações de senha autenticam diretamente contra o template armazenado sem repetir o Onboarding.

  2. Cliente com onboarding prévio com Facephi: O cliente já tem um template armazenado. As autenticações posteriores utilizam o Fluxo de Matching 1:1 contra o template armazenado.

Integração

Requer a implementação do Widget Selphi Mobile ou do Widget Selphi Web para gerar o bestImageToken e o Template Biométrico (templateRaw).

Endpoint

POST /services/authenticateUser/v3

Cabeçalhos

Cabeçalho
Tipo
Obrigatório
Descrição

x-api-key

String

Sim

API key do tenant

Content-Type

String

Sim

application/json

family

String

Não

Header de família obrigatório para Tracking

Todas as chamadas aos Endpoints com Tracking na Identity Platform devem conter o header family.

Modo Enroll

Enrola ou atualiza um Template Biométrico para um usuário. Requer que a validação de teste de vida e o Matching facial sejam bem-sucedidos antes de persistir o template.

A presença do campo templateRaw no corpo da solicitação ativa este modo.

Corpo da solicitação

Content-Type: application/json

Parâmetros

Parâmetro
Tipo (Conteúdo)
Obrigatório
Descrição

userId

String

Sim

Identificador único do usuário. Deve ter pelo menos 2 caracteres.

templateRaw

String (Base64)

Sim

Template Biométrico facial gerado a partir da melhor imagem durante o processo de Onboarding. Sua presença ativa o modo enroll.

bestImageToken

String (Base64)

Sim

Melhor imagem facial tokenizada gerada pelo Widget Selphi. É utilizada para validação do teste de vida e Matching facial contra o templateRaw para verificar que correspondem à mesma pessoa viva.

tracking

Objeto JSON

Não

Objeto que contém informações de Tracking.

extraData

String (Base64)

Não

Token gerado pelo SDK Mobile/Web que contém informações de Tracking tokenizadas.

operationId

String

Não

Identificador de operação gerado pelo SDK Mobile/Web.

Exemplo de solicitação: Enroll

Comportamento do enroll

  1. Teste de vida: Valida que o bestImageToken corresponde a uma pessoa viva.

  2. Matching facial: Realiza um Matching 1:1 entre templateRaw e bestImageToken para verificar que pertencem à mesma pessoa.

  3. Persistência: Se ambas as verificações forem aprovadas, consulta o userId:

    • Se o usuário não existir: cria o usuário e armazena o template.

    • Se o usuário já existir: atualiza o template armazenado com o novo.

  4. TTL (se estiver configurado): O Token do template tem um tempo de validade configurável para uso no serviço. Após expirar, deixa de ser válido para o enroll.

Modo Authenticate

Autentica um usuário comparando uma captura ao vivo contra seu Template Biométrico previamente armazenado. Este modo é ativado quando templateRaw não está incluído no corpo da solicitação.

Importante: O usuário deve ter sido previamente cadastrado (por meio do modo enroll ou do fluxo de auto-registro de v1/v2) antes de poder ser autenticado. Tentar autenticar um usuário não cadastrado retorna um erro Usuário não encontrado.

Parâmetros

Parâmetro
Tipo (Conteúdo)
Obrigatório
Descrição

userId

String

Sim

Identificador único do usuário a autenticar. Deve ter pelo menos 2 caracteres.

bestImageToken

String (Base64)

Sim

Melhor imagem facial tokenizada da sessão atual de Authentication. É utilizada para validação do teste de vida e Matching 1:1 contra o template armazenado.

tracking

Objeto JSON

Não

Objeto que contém informações de Tracking.

extraData

String (Base64)

Não

Token gerado pelo SDK Mobile/Web que contém informações de Tracking tokenizadas.

operationId

String

Não

Identificador de operação gerado pelo SDK Mobile/Web.

Exemplo de solicitação: Authenticate

Comportamento da Authentication

  1. Busca de usuário: Recupera o template armazenado associado ao userId.

  2. Verificação de TTL: Se o template tiver uma expiração configurada e ela tiver sido ultrapassada, retorna Template expirado.

  3. Teste de vida: Valida que o bestImageToken corresponde a uma pessoa viva.

  4. Matching facial: Realiza um Matching 1:1 entre o template armazenado e o bestImageToken.

  5. Resultado: Retorna o resultado do Matching incluindo pontuação de similaridade, estado de Authentication e diagnóstico do teste de vida.

Respostas

200 Sucesso

Parâmetros de resposta

Identificador
Tipo
Descrição

serviceResultCode

Integer

Código que indica o resultado geral da execução do serviço. Veja a tabela de Service Result Code a seguir.

serviceResultLog

String

Campo descritivo do resultado da execução. Vazio em caso de sucesso.

serviceFacialSimilarityResult

Float

Valor que indica a similaridade facial entre o template e o bestImageToken. 1.0 = 100%. Presente somente quando se realiza Matching biométrico.

serviceFacialAuthenticationLog

String

Campo descritivo do resultado da Authentication facial (ex. "Positive", "Negative", "Uncertain"). Presente somente quando se realiza Matching biométrico.

serviceFacialAuthenticationResult

Integer

Código que indica o resultado da Authentication facial. Veja a Tabela 2 - Service Facial Authentication Result.

serviceLivenessLog

String

Campo descritivo do resultado do teste de vida passiva (ex. "Live", "Spoof"). Presente somente quando o teste de vida é avaliado.

serviceLivenessResult

Integer

Código que indica o resultado da avaliação do teste de vida passivo. Veja a Tabela 3 - Service Liveness Result.

timestamp

String

Timestamp (UTC) da resposta no formato: YYYY-MM-DDThh🇲🇲ssZ

transactionId

String

Identificador de transação associado à solicitação processada pela API.

Código de Resultado do Serviço

O serviceResultCode indica o resultado geral da execução do serviço:

serviceResultCode
Descrição
Código HTTP

0

Operação bem-sucedida (Enroll concluído ou usuário autenticado).

200

-101

O bestImageToken não corresponde a uma pessoa viva.

200

-102

Authentication do usuário falhou — match facial negativo.

200

-103

Usuário não encontrado (somente modo authenticate).

404

-104

Template não encontrado — o usuário existe, mas não possui template armazenado.

404

-105

Template expirado — TTL excedido, o template já não está disponível.

200

Resultado de Liveness do Serviço

O serviceLivenessResult indica o resultado da avaliação do teste de vida passivo:

Resultado de Liveness do Serviço
Código
Resultado
Descrição

0

None

Não foi possível avaliar o teste de vida.

1

Spoof

OBSOLETO. Use 'NoLive' em seu lugar.

2

Uncertain

OBSOLETO

3

Live

Assume-se que o sujeito está vivo.

4

NoneBecauseBadQuality

Não foi possível avaliar o teste de vida devido à má qualidade da imagem.

5

NoneBecauseFaceTooClose

Não foi possível avaliar o teste de vida porque os rostos detectados estão muito próximos das bordas.

6

NoneBecauseFaceNotFound

Não foi possível avaliar o teste de vida porque nenhum rosto foi detectado.

7

NoneBecauseFaceTooSmall

Não foi possível avaliar o teste de vida porque os rostos detectados são muito pequenos.

8

NoneBecauseAngleTooLarge

Não foi possível avaliar o teste de vida porque o ângulo entre os rostos excede o limite permitido.

9

NoneBecauseImageDataError

Não foi possível avaliar o teste de vida devido a erros no formato da imagem.

10

NoneBecauseInternalError

Não foi possível avaliar o teste de vida devido a um erro interno.

11

NoneBecauseImagePreprocessError

Não foi possível avaliar o teste de vida devido a um erro no pré-processamento da imagem.

12

NoneBecauseTooManyFaces

Não foi possível avaliar o teste de vida porque foram detectados rostos demais na imagem.

13

NoneBecauseFaceTooCloseToBorder

Não foi possível avaliar o teste de vida porque o rosto está muito próximo da borda.

14

NoneBecauseFaceCropped

Não foi possível avaliar o teste de vida porque o rosto está recortado.

15

NoneBecauseLicenseError

Não foi possível avaliar o teste de vida devido a um erro de licença.

16

NoneBecauseFaceOccluded

Não foi possível avaliar o teste de vida porque o rosto está ocluído.

17

NoLive

Vida não detectada.

18

NoneBecauseEyesClosed

Não foi possível avaliar o teste de vida porque os olhos da pessoa estão fechados.

Resultado de Authentication Facial do Serviço

O serviceFacialAuthenticationResult indica o resultado das operações de Matching facial:

Resultado de Authentication Facial do Serviço
Código
Resultado
Descrição

0

NONE

Não foi possível realizar a verificação facial.

1

NEGATIVE

O processo foi executado corretamente. A comparação do padrão facial dos rostos não corresponde.

3

POSITIVE

O processo foi executado corretamente. A comparação do padrão facial dos rostos é positiva. O valor de serviceFacialSimilarityResult indica o % de semelhança entre as imagens comparadas.

4

NONE BECAUSE POSE EXCEED

Não foi possível realizar a verificação facial devido à posição do rosto.

5

NONE BECAUSE INVALID EXTRACTIONS

Não foi possível realizar a verificação facial devido a problemas na extração do padrão facial.

Exemplo de resposta: Enroll bem-sucedido

Exemplo de resposta: Authentication bem-sucedida (Matching positivo)

Exemplo de resposta: Match negativo

Exemplo de resposta: Usuário não encontrado

400 Bad Request

401 Unauthorized

403 Forbidden

404 Not Found

502 Bad Gateway

504 Gateway Timeout

Diferenças com v1/v2

Aspecto
v1/v2
v3

Campo de template na solicitação

registeredTemplateRaw

templateRaw

merchantReferenceId

Obrigatório

Não se utiliza

image / template como entrada

Suportado

Não suportado — apenas templateRaw + bestImageToken

Auto-registro na primeira Authentication

Sim

Não — requer Enroll explícito

Template na resposta

Sim (registeredTemplateRaw)

Não (não é retornado por segurança — evita transferência desnecessária de PII)

Teste de vida + Matching no Enroll

N/A

Obrigatório antes de persistir

TTL / expiração do template

Não suportado

Suportado (configurável por tenant por meio de templateTTLSeconds)

Novos códigos de erro

N/A

-104 (Template não encontrado), -105 (Template expirado)

AnteriorAutenticar usuário V2PróximoAtualizar template do usuário

Atualizado