> 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/shared-biometric-components/authenticate-facial.md). # Autenticação facial Serviço que realiza a validação facial entre dois rostos, incluindo tanto **imagens abertas** quanto **templates biométricos**. Este serviço pode ser usado para realizar as seguintes validações: 1. Autenticação facial entre dois **imagens abertas**, geradas ou não por widgets de FacePhi. 2. Autenticação facial entre dois **templates biométricos**, requer integração do Widget Selphi Mobile ou Web de FacePhi. 3. Autenticação facial entre uma **imagem aberta** e uma **Template Biométrico**, requer integração do Widget Selphi Mobile ou Web de FacePhi. 4. Autenticação facial entre o rosto presente na **foto do Documento de identidade (TokenFaceImage)** e uma **imagem aberta**, requer integração do Widget SelphID Mobile de FacePhi. 5. Autenticação facial entre o rosto presente na **foto do Documento de identidade (TokenFaceImage)** e uma **Template Biométrico**, requer integração dos widgets Selphi Mobile e SelphID Mobile de FacePhi. ### Integração * Para as **validações tipo 4 e 5**, é necessária a implementação do Widget SelphID Mobile para gerar a propriedade **TokenFaceImage**. * Para as **validações tipo 2, 3 e 5**, é necessária a implementação do Widget Selphi Mobile ou Web para gerar a **propriedade de Template Biométrico (TemplateRaw)**. ### Endpoint ``` POST /services/authenticateFacial ``` ### 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: **Onboarding**. Obrigatório com o serviço de Tracking. | {% hint style="info" %} Todas as chamadas aos Endpoints para Tracking com **Identity Platform** devem conter o cabeçalho `family`. {% endhint %} ### Corpo da solicitação **Content-Type:** `application/json` #### Parâmetros | Parâmetro | Tipo | Obrigatório | Descrição | | ---------------------- | ------- | ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `token1` | string | **Sim** | Imagem usada como **referência** para a comparação facial. Dependendo do método invocado, pode ser o token gerado pelos widgets SelphID (token da foto do documento), uma imagem aberta ou um Template Biométrico tokenizado. | | `token2` | string | **Sim** | Imagem usada para a **comparação**. Pode ser uma imagem aberta ou um Template Biométrico tokenizado. | | `method` | integer | **Sim** | Indica o **método de comparação** invocado. Ver [Especificação do método](#especificación-de-método). | | `tracking` | 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. | #### Especificação do método | Método | Descrição | Entrada | | ------ | ----------------------------------------------------------------------------------------------------------- | ------------------------------------------- | | **1** | Autenticação facial por meio de **imagens abertas** | token1: Base64, token2: Base64 | | **2** | Autenticação facial por meio de **templates biométricos** | token1: templateRaw, token2: templateRaw | | **3** | Autenticação facial por meio de uma **imagem aberta** e uma **Template Biométrico** | token1: Base64, token2: templateRaw | | **4** | Autenticação facial por meio do **token gerado pelo recorte da foto do documento** e uma imagem aberta | token1: tokenFaceImage, token2: Base64 | | **5** | Autenticação facial por meio do **token gerado pelo recorte da foto do documento** e um Template Biométrico | token1: tokenFaceImage, token2: templateRaw | #### Exemplo de solicitação ```json { "token1": "BAMBAQLNHJoWGPjfeuDIzDXdZuP...", "token2": "BAMBAQLNHJoWGPjfeuDIzDXdZuP...", "method": 1, "tracking": { "extraData": "BQABAQG2gBNjuHN4kLmPqYf7R...", "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 do serviço. Inclui detalhes quando há um erro ou exceção no módulo. | | `serviceTime` | string | Tempo total de processamento **(milissegundos)**. | | `serviceTransactionId` | string | Identificador de transação associado à solicitação processada pela API. | | `serviceFacialAuthenticationHash` | string | Hash de integridade do Template Biométrico utilizado em uma autenticação facial positiva ou incerta. **Aplicável apenas nos métodos 2, 3 e 5.** | | `serviceFacialAuthenticationResult` | integer | Código que indica o **resultado da correspondência facial**. Consulte [Resultado de Authentication Facial do Serviço](#service-facial-authentication-result) | | `serviceFacialSimilarityResult` | number | Valor que indica a **similaridade facial** entre o rosto na foto do Documento de identidade e a selfie tirada pelo usuário. **1.0 = 100%** | #### 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 de Authentication Facial do Serviço O `serviceFacialAuthenticationResult` indica o resultado das operações de Matching 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 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: Positivo ```json { "serviceResultCode": 0, "serviceResultLog": "Positivo", "serviceTime": "516", "serviceTransactionId": "a29cbe15-2b68-495f-b7eb-be985b21c486", "serviceFacialAuthenticationHash": "47D0ACDCF08C348469C2F512BB59216B46DCD9B253822ED0E4EEAFCEB76AADD5AEF20CA31EC52D03EB290EBC91A6AD65FB0416F9EB2164D3854932153074289E", "serviceFacialAuthenticationResult": 3, "serviceFacialSimilarityResult": 0.99153554 } ``` #### Exemplo de resposta: Negativo ```json { "serviceResultCode": 0, "serviceResultLog": "Negativo", "serviceTime": "502", "serviceTransactionId": "e96e85a4-3f94-4000-b639-15c4f18c345b", "serviceFacialAuthenticationHash": "09B9A4097E3642ADEDB665BA2E15B096FFB65A039E0D7137D0AD38666F90A010624C26867E6A7DB8346385610CC9FEDE435C3CC6A2AC9B008DD98C6EFE8C42E7", "serviceFacialAuthenticationResult": 1, "serviceFacialSimilarityResult": 0.01190000 } ``` #### `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` Proibido ```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` Gateway Timeout ```json { "message": "Endpoint request timed out" } ```