> For the complete documentation index, see [llms.txt](https://docs.facephi.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.facephi.com/docs.facephi-pt-br/api-rest/identity-api/identity-api-reference/authentication/authenticate-user-v3.md). # Autenticar usuário 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 ```json { "userId": "user-001", "templateRaw": "BAEBAQIxLiHIhMPQWaUo…", "bestImageToken": "BgEBAQJksxGtVd++lRjN…", "tracking": { "extraData": "BQABAQG2gBNjuHN...", "operationId": "123e4567-e89b-12d3-a456-426614174000" } } ``` #### 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 ```json { "userId": "user-001", "bestImageToken": "BgEBAQJksxGtVd++lRjN…", "tracking": { "extraData": "BQABAQG2gBNjuHN...", "operationId": "123e4567-e89b-12d3-a456-426614174000" } } ``` #### 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:flag\_mm: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ódigoResultadoDescrição
0NoneNão foi possível avaliar o teste de vida.
1SpoofOBSOLETO. Use 'NoLive' em seu lugar.
2UncertainOBSOLETO
3LiveAssume-se que o sujeito está vivo.
4NoneBecauseBadQualityNão foi possível avaliar o teste de vida devido à má qualidade da imagem.
5NoneBecauseFaceTooCloseNão foi possível avaliar o teste de vida porque os rostos detectados estão muito próximos das bordas.
6NoneBecauseFaceNotFoundNão foi possível avaliar o teste de vida porque nenhum rosto foi detectado.
7NoneBecauseFaceTooSmallNão foi possível avaliar o teste de vida porque os rostos detectados são muito pequenos.
8NoneBecauseAngleTooLargeNão foi possível avaliar o teste de vida porque o ângulo entre os rostos excede o limite permitido.
9NoneBecauseImageDataErrorNão foi possível avaliar o teste de vida devido a erros no formato da imagem.
10NoneBecauseInternalErrorNão foi possível avaliar o teste de vida devido a um erro interno.
11NoneBecauseImagePreprocessErrorNão foi possível avaliar o teste de vida devido a um erro no pré-processamento da imagem.
12NoneBecauseTooManyFacesNão foi possível avaliar o teste de vida porque foram detectados rostos demais na imagem.
13NoneBecauseFaceTooCloseToBorderNão foi possível avaliar o teste de vida porque o rosto está muito próximo da borda.
14NoneBecauseFaceCroppedNão foi possível avaliar o teste de vida porque o rosto está recortado.
15NoneBecauseLicenseErrorNão foi possível avaliar o teste de vida devido a um erro de licença.
16NoneBecauseFaceOccludedNão foi possível avaliar o teste de vida porque o rosto está ocluído.
17NoLiveVida não detectada.
18NoneBecauseEyesClosedNã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 ```json { "serviceResultCode": 0, "serviceResultLog": "", "serviceFacialSimilarityResult": 0.9812, "serviceFacialAuthenticationLog": "Positive", "serviceFacialAuthenticationResult": 3, "serviceLivenessLog": "Live", "serviceLivenessResult": 3, "timestamp": "2026-04-20T15:12:07Z", "transactionId": "cd13a168-6eb0-4afd-bc88-408ca6a73437" } ``` #### Exemplo de resposta: Authentication bem-sucedida (Matching positivo) ```json { "serviceResultCode": 0, "serviceResultLog": "", "serviceFacialSimilarityResult": 0.9812, "serviceFacialAuthenticationLog": "Positive", "serviceFacialAuthenticationResult": 3, "serviceLivenessLog": "Live", "serviceLivenessResult": 3, "timestamp": "2026-04-20T15:12:28Z", "transactionId": "1ada7f96-44f2-48f1-87a5-0359621ae7a1" } ``` #### Exemplo de resposta: Match negativo ```json { "serviceResultCode": -102, "serviceResultLog": "User not found", "serviceFacialSimilarityResult": 0.0192, "serviceFacialAuthenticationLog": "Negative", "serviceFacialAuthenticationResult": 1, "serviceLivenessLog": "Live", "serviceLivenessResult": 3, "timestamp": "2026-04-20T15:34:47Z", "transactionId": "d6e29c6c-0da2-4620-9ca7-f483c6950d72" } ``` #### Exemplo de resposta: Usuário não encontrado ```json { "serviceResultCode": -103, "serviceResultLog": "User not found", "timestamp": "2026-04-20T15:12:29Z", "transactionId": "ca61856d-0eb8-49ca-8178-66346e0c75ab" } ``` #### 400 Bad Request ```json { "status": 400, "title": "Bad Request", "detail": "Invalid request.", "type": "https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400", "errors": [ "userId is required" ] } ``` #### 401 Unauthorized ```json { "message": "Unauthorized" } ``` #### 403 Forbidden ```json { "Message": "User is not authorized to access this resource with an explicit deny" } ``` #### 404 Not Found ```json { "serviceResultCode": -103, "serviceResultLog": "User not found", "timestamp": "2026-04-20T15:12:29Z", "transactionId": "ca61856d-0eb8-49ca-8178-66346e0c75ab" } ``` #### 502 Bad Gateway ```json { "status": 502, "title": "Bad Gateway", "detail": "Server got an invalid response.", "type": "https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/502" } ``` #### 504 Gateway Timeout ```json { "message": "Endpoint request timed out" } ``` *** ### 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) | ***