> 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-v2.md). # Autenticar usuário V2 Este serviço valida tanto o teste de vida quanto a autenticação facial. Compara o Template Biométrico, previamente validado e armazenado no repositório de dados do cliente durante o processo de Onboarding, com um bestImageToken gerado no momento da autenticação. #### Funcionalidade * **Primeira chamada**: Define um userId único para o usuário. * **Autenticação**: Em cada tentativa de autenticação, o userId é enviado junto com o Template Biométrico registrado. Esse Template Biométrico é comparado com a imagem tokenizada atual (bestImageToken). Se houver correspondência e a verificação de vida for aprovada, o usuário é autenticado com sucesso. ### 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/v2 ``` ### Cabeçalhos | Nome | Tipo | Obrigatório | Descrição | | ------------- | ------ | ----------- | ----------------------------------------------------------------- | | **x-api-key** | string | **Sim** | API Key de autorização de acesso. | | **family** | string | Não | Valor: **Authentication**. Obrigatório com o serviço de Tracking. | {% hint style="info" %} Todas as chamadas aos Endpoints para Tracking com **Identity Platform** devem conter o header `family`. {% endhint %} ### Corpo da solicitação **Content-Type:** `application/json` #### Parâmetros | Parâmetro | Tipo | Obrigatório | Descrição | | ----------------------- | ------ | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `userId` | string | **Sim** | Identificador único do usuário. Deve ser persistido e associado ao Template Biométrico correspondente. Precisa de pelo menos dois dígitos. | | `registeredTemplateRaw` | string | **Sim** | Template gerado pelo Widget Selphi, criptografado com AES256 e tokenizado, enviado em formato Base64. Representa o padrão facial do usuário com a pose frontal mais detectada. | | `image` | string | Não | Imagem em formato Base64 obtida do registro civil. Torna-se obrigatória se o Template Biométrico registrado (registeredTemplateRaw) não for fornecido. | | `bestImageToken` | string | **Sim** | Propriedade **bestImage tokenizada** gerada pelo Widget Selphi no momento da autenticação. | | `template` | string | Não | Template Biométrico em formato Base64. Torna-se obrigatório se a bestImage tokenizada (bestImageToken) não for fornecida. | | `merchantReferenceId` | string | **Sim** | Referência do cliente para cada autenticação. Recomenda-se que esse dado não contenha informações sensíveis como PII (informação de identificação pessoal). | | `rastreamento` | object | Não | Objeto que representa as informações de Tracking necessárias. | | `tracking.extraData` | string | Não | Token gerado pelo SDK Mobile/Web. Contém informações de Tracking tokenizadas com a Plataforma. | | `tracking.operationId` | string | Não | Identificador de operação gerado pelo SDK Mobile/Web. | #### Exemplo de solicitação: Com Template Biométrico registrado ```json { "userId": "001", "registeredTemplateRaw": "BAIBAQFpWLJtBYBymCoRF...", "bestImageToken": "BAIBAQIJTHP8obR2r9ALdDtR5lT...", "merchantReferenceId": "authenticate-001", "tracking": { "extraData": "BQABAQG2gBNjuHN...", "operationId": "123e4567-e89b-12d3-a456-426614174000" } } ``` #### Exemplo de solicitação: Com imagem do registro civil ```json { "userId": "001", "image": "/9j/4AAQ...", "bestImageToken": "BAIBAQIJTHP8obR2r9ALdDtR5lT...", "merchantReferenceId": "authenticate-001", "tracking": { "extraData": "BQABAQG2gBNjuHN...", "operationId": "123e4567-e89b-12d3-a456-426614174000" } } ``` ### Respostas #### `200` Sucesso #### Parâmetros de resposta | Parâmetro | Tipo | Descrição | | ----------------------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | | `serviceResultCode` | integer | Código que indica o **resultado geral** da execução do serviço. Veja [Código de Resultado do Serviço](#service-result-code) | | `serviceResultLog` | string | Campo descritivo do resultado da execução. Inclui detalhes quando há um erro ou exceção. Se for bem-sucedido, indica a descrição do código de resultado. | | `serviceFacialSimilarityResult` | number | Valor que indica a **similaridade facial** entre o registeredTemplateRaw e o bestImageToken. **1.0 = 100%** | | `serviceFacialAuthenticationLog` | string | Campo descritivo do resultado da autenticação facial. Inclui detalhes quando há um erro ou exceção no módulo. | | `serviceFacialAuthenticationResult` | integer | Código que indica o **resultado da autenticação facial**. Ver [Resultado da Autenticação Facial do Serviço](#service-facial-authentication-result) | | `serviceLivenessResult` | integer | Código que indica o **resultado do teste de vida passivo**. Ver [Resultado do Service Liveness](#service-liveness-result) | | `serviceLivenessLog` | string | Campo descritivo do resultado da verificação de vida passiva. Inclui detalhes quando há um erro ou exceção. | | `merchantReferenceId` | string | Referência enviada no corpo da solicitação. | | `registeredTemplateRaw` | string | Template Biométrico registrado devolvido pelo SDK SelphID para uso em autenticações posteriores. | | `timestamp` | string | Marca temporal (UTC) da resposta no formato YYYY-MM-DDThh:flag\_mm:ssZ | | `transactionId` | string | Identificador da 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 | A execução do serviço foi bem-sucedida, o módulo processou a solicitação corretamente. | 200 | #### Resultado do Service Liveness O `serviceLivenessResult` indica o resultado da avaliação do teste de vida passivo: | Código | Resultado | Descrição | | ------ | ------------------------------- | ----------------------------------------------------------------------------------------------------- | | 0 | None | Não foi possível avaliar o teste de vida. | | 1 | Spoof | DEPRECADO. Usar 'NoLive' em seu lugar. | | 2 | Uncertain | DEPRECADO | | 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 não foram detectados rostos. | | 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 muitos rostos 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á cortado. | | 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 | Não foi detectada vida. | | 18 | NoneBecauseEyesClosed | Não foi possível avaliar o teste de vida porque os olhos da pessoa estão fechados. | #### Resultado da Autenticação Facial do Serviço O `serviceFacialAuthenticationResult` indica o resultado das operações de correspondência facial: | 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 a % de semelhança entre as imagens comparadas. | | 4 | NENHUM DEVIDO A EXCESSO DE POSE | Não foi possível realizar a verificação facial devido à posição do rosto. | | 5 | NENHUM DEVIDO A EXTRAÇÕES INVÁLIDAS | Não foi possível realizar a verificação facial devido a problemas na extração do padrão facial. | #### Exemplo de resposta ```json { "merchantReferenceId": "82b0084f-ddec-4415-8d2f-b085b42a0155", "serviceResultCode": 0, "serviceResultLog": "", "serviceFacialSimilarityResult": 0.9946970343589783, "serviceFacialAuthenticationLog": "Positive", "serviceFacialAuthenticationResult": 3, "serviceLivenessLog": "Live", "serviceLivenessResult": 3, "timestamp": "2024-10-29T20:29:24Z", "transactionId": "531ecbb1-de3d-4907-a737-0db236674e9a", "registeredTemplateRaw": "BAIBAQGo+puJyHjfRD8n..." } ``` #### `400` Requisição inválida ```json { "status": 400, "title": "Bad Request", "detail": "Invalid request.", "type": "https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400", "errors": [] } ``` #### `401` Não autorizado ```json { "message": "Unauthorized" } ``` #### `403` Acesso negado ```json { "Message": "User is not authorized to access this resource with an explicit deny" } ``` #### `502` Gateway inválido ```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` Tempo limite do gateway ```json { "message": "Endpoint request timed out" } ```