> 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/onboarding/identity-validation-v2.md). # Identity Validation V2 Este serviço realiza tanto a **teste de vida** quanto a **comparação facial** entre dois rostos, sejam fornecidos como imagens abertas ou como parâmetros tokenizados. Suporta dois tipos de validações faciais, dependendo do Widget integrado. ### Integração * Para a **validação tipo 3**, é necessária uma **imagem em formato aberto** da frente do documento de identidade, onde se encontra o rosto. * Para a **validação tipo 5**, é necessário implementar o **Widget SelphID Mobile** para gerar a propriedade **TokenFaceImage**. ### Endpoint ``` POST /onboarding/v2/identity ``` ### 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. Pode ser uma imagem base64 ou **TokenFaceImage**, dependendo do método. | | `bestImageToken` | string | **Sim** | Propriedade **bestImage tokenizada** gerada pelo Widget Selphi e tokenizada por meio da função nativa. | | `method` | string | **Sim** | Indica o **método de comparação** invocado. Ver [Especificação do método](#especificacion-de-metodo). | | `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 | | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | | **"3"** | Autenticação facial por meio de uma **imagem aberta** e **bestImage tokenizada** (Base64 & bestImageToken) | | **"5"** | Autenticação facial por meio do **token gerado pelo recorte da foto do documento** e **bestImage tokenizada** (tokenFaceImage & bestImageToken) | #### Exemplo de solicitação ```json { "token1": "/9j/4AAQSkZJRgABAQAASAB...", "bestImageToken": "BAMBAQLNHJoWGPj...", "method": "3", "tracking": { "extraData": "BQABAQG2gBNjuHN4kLmPqYf7R...", "operationId": "123e4567-e89b-12d3-a456-426614174000" } } ``` ### Respostas #### `200` Sucesso #### Parâmetros de resposta | Parâmetro | Tipo | Descrição | | -------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `serviceTransactionId` | string | Identificador de transação associado à solicitação da API. | | `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. Fornece detalhes de erros ou exceções quando ocorrem. | | `serviceTime` | string | Campo que indica o tempo de processamento **(milissegundos)**. | | `facialAuthenticationResult` | integer | Código que indica o **resultado da correspondência facial**. Consulte [Resultado de Authentication Facial do Serviço](#service-facial-authentication-result) | | `facialAuthenticationLog` | string | Campo descritivo do resultado da correspondência facial. | | `facialAuthenticationSimilarity` | number | Valor que indica a **similaridade facial** entre a foto do documento e a selfie tirada pelo usuário. **1.0 = 100%** | | `passiveLivenessResult` | integer | Código que indica o **resultado do teste de vida passiva**. Consulte [Resultado de Liveness do Serviço](#service-liveness-result) | | `passiveLivenessLog` | string | Campo descritivo do resultado do teste de vida passiva. | #### 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 Liveness do Serviço 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 | 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: | 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 ```json { "serviceTransactionId": "2db602ee-3564-4304-af95-92a52eaae12d", "serviceResultCode": 0, "serviceResultLog": "[identity] Service executed ok", "serviceTime": "2235", "facialAuthenticationResult": 3, "facialAuthenticationLog": "Positive", "facialAuthenticationSimilarity": 0.99214232, "passiveLivenessResult": 3, "passiveLivenessLog": "Live" } ``` #### `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" } ```