> 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 templates biométricos e autenticação 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**: Envia-se o `userId` junto com o template biométrico (`templateRaw`) e a melhor imagem tokenizada (`bestImageToken`). Se valida 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. * **Autenticar**: Envia-se o `userId` junto com o `bestImageToken` Token da sessão atual. Recupera-se o template armazenado e realiza-se um matching 1:1 contra a captura ao vivo. O resultado da autenticação é 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. Este template é enrollado 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 usam 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 exigido 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. É usada para validação de teste de vida e Matching facial contra o `templateRaw` para verificar que correspondem à mesma pessoa viva. | | Tracking | JSON Object | 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 passarem, consulta o `userId`: * Se o usuário **não existe**: cria o usuário e armazena o template. * Se o usuário **já existe**: 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. Uma vez expirado, 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 enrollado (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 enrollado 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 de autenticação atual. É usada para validação de teste de vida e Matching 1:1 contra o template armazenado. | | Tracking | JSON Object | 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 autenticação 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 esta tiver sido excedida, 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 autenticação e diagnóstico de 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 o matching biométrico é realizado. | | serviceFacialAuthenticationLog | String | Campo descritivo do resultado da autenticação facial (ex. "Positive", "Negative", "Uncertain"). Presente somente quando o matching biométrico é realizado. | | serviceFacialAuthenticationResult | Integer | Código que indica o resultado da autenticação facial. Veja Tabela 2 - Service Facial Authentication Result. | | serviceLivenessLog | String | Campo descritivo do resultado do teste de vida passivo (ex. "Live", "Spoof"). Presente somente quando o teste de vida é avaliado. | | serviceLivenessResult | Integer | Código que indica o resultado da avaliação de teste de vida passivo. Veja 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. | #### Service Result Code 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 | Autenticação de 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 tem template armazenado. | 404 | | -105 | Template expirado — TTL excedido, o template não está mais disponível. | 200 | #### Resultado do Service Liveness O `serviceLivenessResult` indica o resultado da avaliação do teste de vida passivo:
Resultado do Service Liveness
CódigoResultadoDescrição
0NoneNão foi possível avaliar o teste de vida.
1SpoofDEPRECADO. Usar 'NoLive' em seu lugar.
2UncertainDEPRECADO
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á cortado.
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.
17NoLiveNenhuma vida foi detectada.
18NoneBecauseEyesClosedNão foi possível avaliar o teste de vida porque os olhos da pessoa estão fechados.
#### Resultado de Autenticação Facial do Serviço O `serviceFacialAuthenticationResult` indica o resultado das operações de correspondência facial:
Resultado de Autenticação 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: Autenticação bem-sucedida (match 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 authentication failed", "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": "Requisição inválida", "detail": "Solicitação inválida.", "type": "https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400", "errors": [ "userId is required" ] } ``` #### 401 Unauthorized ```json { "message": "Não autorizado" } ``` #### 403 Forbidden ```json { "Message": "O usuário não está autorizado a acessar este recurso com uma negação explícita" } ``` #### 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": "Gateway inválido", "detail": "O servidor recebeu uma resposta inválida.", "type": "https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/502" } ``` #### 504 Gateway Timeout ```json { "message": "A requisição do Endpoint excedeu o tempo limite" } ``` *** ### Diferenças com v1/v2 | Aspecto | v1/v2 | v3 | | -------------------------------------- | ----------------------------- | ------------------------------------------------------------------------------ | | Campo de template na solicitação | `registeredTemplateRaw` | `templateRaw` | | `merchantReferenceId` | Obrigatório | Não é utilizado | | `image` / `template` como input | Suportado | Não suportado — apenas `templateRaw` + `bestImageToken` | | Auto-registro na primeira autenticação | 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) | ***