> 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/sdks/backend-sdk/selphid/technical_documentation/api_reference.md).

# Guia de referência da API

## 1. Introdução

Este documento inclui a descrição da API das bibliotecas fornecidas no produto **FacePhi SelphID SDK**.

## 2. Descrição da API de SelphID (Front-end)

**SelphID SDK** é um conjunto de bibliotecas de servidor que utiliza as informações geradas pelos Widgets de **FacePhi** para aplicações nativas ou web. Como descrito nas seções a seguir, são fornecidos alguns componentes denominados Widgets para a captura facial (Selphi) e a captura de documentos de identidade (SelphID), que podem ser integrados no front-end de qualquer aplicação.

### 2.1. Widget Selphi

Por meio do widget **Selphi**, que incorpora o mecanismo de detecção e extração facial e de prova de vida do usuário, é possível obter as seguintes informações por meio das propriedades indicadas a seguir:

* **`Image` propriedade:** Representa a imagem do usuário com a pose facial mais frontal detectada.
* **`TemplateRaw` propriedade:** Representa o template biométrico tokenizado do usuário com a pose facial mais frontal detectada. Este template é utilizado para realizar a autenticação biométrica com o SelphID SDK.

> **Nota**
>
> Adicionalmente, é fornecida uma funcionalidade de tokenização **generateTemplateRaw** (ver API) que permite converter uma imagem ou um buffer de dados em um buffer de dados tokenizado na forma de `templateRaw`. Este `templateRaw` pode ser utilizado em várias funcionalidades do SelphID SDK.

### 2.2. Widget SelphID

Por meio do widget **SelphID**, que incorpora o mecanismo automático de detecção e captura de documentos, é possível obter as seguintes informações por meio das propriedades indicadas a seguir:

* **`TokenOCR` propriedade:** Representa um Token (marca de tempo + criptografia AES256) que contém os dados detectados no documento por meio do OCR realizado.
* **`TokenFrontDocument` propriedade:** Representa a imagem tokenizada (marca de tempo + criptografia AES256) da frente do documento ajustada às bordas do documento.
* **`TokenBackDocument` propriedade:** Representa a imagem tokenizada (marca de tempo + criptografia AES256) do verso do documento ajustada às bordas do documento.
* **`TokenFaceImage` propriedade:** Representa a imagem tokenizada (marca de tempo + criptografia AES256) da fotografia do usuário no documento. Este Token é utilizado para realizar a autenticação biométrica com o SDK.
* **`TokenRawFrontDocument` propriedade:** Representa a imagem tokenizada (marca de tempo + criptografia AES256) da frente do documento sem ser recortada às bordas do documento, ou seja, exatamente como foi capturada pela câmera.
* **`TokenRawBackDocument` propriedade:** Representa a imagem tokenizada (marca de tempo + criptografia AES256) do verso do documento sem ser recortada às bordas do documento, ou seja, exatamente como foi capturada pela câmera.

## 3. Descrição da API de SelphID (Back-end)

A seguir, é descrita a API das bibliotecas fornecidas em SelphID, detalhando os métodos que o integrador pode usar para incorporar as funcionalidades de reconhecimento facial, extração de informações em documentos de identidade e validação de documentos.

### 3.1. Inicialização das bibliotecas

`SelphIDVerifier` representa a classe principal das bibliotecas, que contém todos os métodos disponíveis para cada uma das funcionalidades.

A inicialização das bibliotecas pode ser realizada de três formas diferentes, dependendo das variáveis de ambiente configuradas:

#### 3.1.1. Inicialização por meio do método `loadWithConfigPath()`

> **Passos prévios**
>
> Configure as variáveis de ambiente e o arquivo config.cfg (configuração do SDK para instalação On-premise):
>
> * `FACEPHI_SELPHID_INSTALL_PATH`
> * `FACEPHI_SELPHID_INSTALL_BIN`
> * `LD_LIBRARY_PATH`
> * `PATH`

```java
public static void main(String[] args) {
  // Instantiate a SelphIDVerifier object.
  SelphIDVerifier verifier = new SelphIDVerifier();

  // Specifies the path where the configuration file is located.
  String configurationFilePath =
    "C:/Program Files/FacePhi/Sdk/SelphId/x.x.x.x/config/config.cfg";

  // Load the library indicating the path where to look for the config file.
  verifier.loadWithConfigPath(configurationFilePath);

  // Make use of the library.

  // Unload the library when you have finished.
  verifier.unload();
}
```

#### 3.1.2. Inicialização por meio do método `load()`

> **Passos prévios**
>
> Configure as variáveis de ambiente e o arquivo config.cfg (configuração do SDK para instalação On-premise):
>
> * `FACEPHI_SELPHID_INSTALL_PATH`
> * `FACEPHI_SELPHID_INSTALL_BIN`
> * `LD_LIBRARY_PATH`
> * `PATH`
>
> Não é necessário especificar o caminho do arquivo de configuração, pois ele será procurado automaticamente no seguinte caminho: `FACEPHI_SELPHID_INSTALL_PATH`/config/selphid.cfg

```java
public static void main(String[] args) {
  // Instantiate a SelphIDVerifier object.
  SelphIDVerifier verifier = new SelphIDVerifier();

  // Load the library.
  verifier.load();

  // Make use of the library.

  // Unload the library when you have finished.
  verifier.unload();
}
```

#### 3.1.3. Inicialização por meio do método `loadFromEnvVars()`

> **Passos prévios**
>
> Configure as variáveis de ambiente (configuração do SDK para instalação On-premise):
>
> * `FACEPHI_SELPHID_INSTALL_PATH`
> * `FACEPHI_SELPHID_INSTALL_BIN`
> * `LD_LIBRARY_PATH`
> * `PATH`
> * `FACEPHI_SELPHID_DEBUGPATH_KEY`
> * `FACEPHI_SELPHID_USAGEPATH_KEY`
> * `FACEPHI_SELPHID_FACIALLIVENESS_PATH_KEY`
> * `FACEPHI_SELPHID_FACIAL_LICPATH_KEY`
>
> Em vez de configurar o arquivo config.cfg, essas variáveis são definidas diretamente como variáveis de ambiente.

```java
public static void main(String[] args) {
  // Instantiate a SelphIDVerifier object.
  SelphIDVerifier verifier = new SelphIDVerifier();

  // Load the library.
  verifier.loadFromEnvVars();

  // Make use of the library.

  // Unload the library when you have finished.
  verifier.unload();
}
```

> **Importante**
>
> A inicialização das bibliotecas por meio do método `load()`, `loadWithConfigPath()` ou `loadFromEnvVars()` deve ser realizada apenas uma vez durante o ciclo de vida da sua aplicação.
>
> Depois de finalizados todos os processos que envolvem o uso dessas bibliotecas, é importante liberar os recursos associados a elas; **não se esqueça de descarregar (unload) a biblioteca antes de fechar a aplicação**.
>
> O encerramento das bibliotecas por meio do método `unload()` deve ser realizada apenas uma vez durante o ciclo de vida da sua aplicação. **Uma vez invocado o método `unload()`, já não é possível realizar um `load()`**.
>
> Se ocorrer alguma condição que impeça o carregamento correto das bibliotecas, será lançada uma `SelphIDException`. Para conhecer os tipos de exceção, consulte a seção correspondente [3.10. Descrição de SelphIDException](#310-descripción-de-selphidexception) na API fornecida.

### 3.2. Métodos de extração facial

Para realizar a extração dos dados faciais de um usuário, o integrador dispõe de diferentes métodos na classe `SelphIDVerifier`. O integrador deverá utilizar um método ou outro dependendo dos dados gerados no cliente. A seguir, são descritas cada uma das possíveis situações.

> **Nota**
>
> O resultado desses métodos será sempre um objeto `SelphIDFacialExtractionResult`, explicado em [3.9.1. SelphIDFacialExtractionResult](#391-selphidfacialextractionresult).

#### 3.2.1. Extração facial por meio de uma imagem

O método a ser utilizado é o seguinte:

```java
SelphIDFacialExtractionResult r = extractFacialWithImageBuffer(
  byte[] imageBuffer,
  SelphIDVerifierOptions options
);
```

Os passos necessários para realizar uma extração facial por meio de uma imagem são os seguintes (método de exemplo):

> **Passos prévios**
>
> * Obtenha a imagem (string em base64) por meio da propriedade Image usando o widget Selphi.
> * Envie a string em base64 da imagem ao servidor.

```java
String extractBiometricFacialTemplate(String imageBase64) {
  // Decode base64 to get the byte array corresponding to the image on the server.
  byte[] imageBuffer = Base64.getDecoder().decode(
    imageBase64.getBytes());

  // Create the SelphIDVerifierOptions and configure it if needed.
  SelphIDVerifierOptions options = new SelphIDVerifierOptions();

  // Extraction
  // Check 3.1. section to initializate SelphIDVerifier.
  SelphIDFacialExtractionResult r = verifier.extractFacialWithImageBuffer(imageBuffer, options);

  // Explore the information obtained in SelphIDFacialExtractionResult like facial position.
  Rectangle facePostion = r.getFaceRectangle();

  // Return the biometric facial template.
  return r.getFacialTemplate();
}
```

#### 3.2.2. Extração facial por meio de um template biométrico

O método a ser utilizado é o seguinte:

```java
SelphIDFacialExtractionResult r = extractFacialWithRawTemplate(
  byte[] rawTemplateBuffer,
  SelphIDVerifierOptions options
);
```

Os passos necessários para realizar uma extração facial por meio de uma template biométrica são os seguintes (método de exemplo):

> **Passos prévios**
>
> * Obtenha o template biométrico (string em base64) por meio da propriedade TemplateRaw usando o widget Selphi.
> * Envie a string em base64 do template biométrico ao servidor.

```java
String extractBiometricFacialTemplate(String templateRawBase64) {
  // Decode base64 to get the byte array corresponding to the template.
  byte[] rawTemplateBuffer = Base64.getDecoder().decode(
    templateRawBase64.getBytes());

  // Create the SelphIDVerifierOptions and configure it if needed.
  SelphIDVerifierOptions options = new SelphIDVerifierOptions();

  // Extraction
  // Check 3.1. section to initializate SelphIDVerifier.
  SelphIDFacialExtractionResult r = verifier.extractFacialWithRawTemplate(rawTemplateBuffer, options);

  // Explore the information obtained in SelphIDFacialExtractionResult like facial position.
  Rectangle facePostion = r.getFaceRectangle();

  // Return the biometric facial template.
  return r.getFacialTemplate();
}
```

### 3.3. Métodos de autenticação facial

Para realizar a autenticação facial de um usuário, o integrador dispõe de diferentes métodos na classe `SelphIDVerifier`. O integrador deverá utilizar um método ou outro dependendo dos dados gerados no cliente. Cada uma das possíveis situações é descrita nos subtópicos a seguir.

> **Nota**
>
> O resultado desses métodos será sempre um objeto `SelphIDFacialAuthenticationResult`, explicado em [3.9.2. SelphIDFacialAuthenticationResult](#392-selphidfacialauthenticationresult).

#### 3.3.1. Autenticação facial por meio de imagens

```java
SelphIDFacialAuthenticationResult r = authenticateFacialWithImageBuffers(
  byte[] imageQuery,
  byte[] imageTarget,
  SelphIDVerifierOptions options
);
```

Os passos necessários para realizar uma autenticação facial por meio de duas imagens são os seguintes (método de exemplo):

> **Passos prévios**
>
> * Obtenha a primeira imagem (string em base64) por meio da propriedade Image usando o widget Selphi.
> * Obtenha a segunda imagem (string em base64) por meio da propriedade Image usando o widget Selphi.
> * Envie ambas as strings em base64 ao servidor.

```java
boolean isMatch(String firstImageBase64, String secondImageBase64) {
  // Decode base64 to get the byte array corresponding to each image on the server.
  byte[] imageQuery = Base64.getDecoder().decode(
    firstImageBase64.getBytes());
  byte[] imageTarget = Base64.getDecoder().decode(
    secondImageBase64.getBytes());

  // Create the SelphIDVerifierOptions and configure it if needed.
  SelphIDVerifierOptions options = new SelphIDVerifierOptions();

  // Extraction
  // Check 3.1. section to initializate SelphIDVerifier.
  SelphIDFacialAuthenticationResult r = verifier.authenticateFacialWithImageBuffers(
    imageQuery, imageTarget, options);

  // Explore the information obtained in SelphIDFacialAuthenticationResult like similarity
  float similarity = r.getSimilarity();

  // Return if images are matching
  return r.getFacialAuthenticationStatus() == FacialAuthenticationStatus.Positive;
}
```

#### 3.3.2. Autenticação facial por meio de templates biométricos

O método a ser utilizado é o seguinte:

```java
SelphIDFacialAuthenticationResult r = authenticateFacialWithRawTemplates(
  byte[] templateQuery,
  byte[] templateTarget,
  SelphIDVerifierOptions options
);
```

Os passos necessários para realizar uma autenticação facial por meio de dois templates biométricos são os seguintes (método de exemplo):

> **Passos prévios**
>
> * Obtenha o primeiro template biométrico (string em base64) por meio da propriedade TemplateRaw usando o widget Selphi.
> * Obtenha o segundo template biométrico (string em base64) por meio da propriedade TemplateRaw usando o widget Selphi.
> * Envie ambas as strings em base64 ao servidor.

```java
boolean isMatch(String firstTemplateRawBase64, String secondTemplateRawBase64) {
  // Decode base64 to get the byte array corresponding to each image on the server.
  byte[] templateQuery = Base64.getDecoder().decode(
    firstTemplateRawBase64.getBytes());
  byte[] templateTarget = Base64.getDecoder().decode(
    secondTemplateRawBase64.getBytes());

  // Create the SelphIDVerifierOptions and configure it if needed.
  SelphIDVerifierOptions options = new SelphIDVerifierOptions();

  // Extraction
  // Check 3.1. section to initializate SelphIDVerifier.
  SelphIDFacialAuthenticationResult r = verifier.authenticateFacialWithRawTemplates(
    templateQuery, templateTarget, options);

  // Explore the information obtained in SelphIDFacialAuthenticationResult like similarity
  float similarity = r.getSimilarity();

  // Return if images are matching
  return r.getFacialAuthenticationStatus() == FacialAuthenticationStatus.Positive;
}
```

#### 3.3.3. Autenticação facial por meio de uma imagem e um template biométrico

O método a ser utilizado é o seguinte:

```java
SelphIDFacialAuthenticationResult r = authenticateFacialWithImageRawTemplate(
  byte[] imageQuery,
  byte[] templateTarget,
  SelphIDVerifierOptions options
);
```

Os passos necessários para realizar uma autenticação facial por meio de uma imagem e um template biométrico são os seguintes (método de exemplo):

> **Passos prévios**
>
> * Obtenha a imagem (string em base64) por meio da propriedade Image usando o widget Selphi.
> * Obtenha o template biométrico (string em base64) por meio da propriedade TemplateRaw usando o widget Selphi.
> * Envie ambas as strings em base64 ao servidor.

```java
boolean isMatch(String imageBase64, String templateRawBase64) {
  // Decode base64 to get the byte array corresponding to each image on the server.
  byte[] imageQuery = Base64.getDecoder().decode(
    imageBase64.getBytes());
  byte[] templateTarget = Base64.getDecoder().decode(
    templateRawBase64.getBytes());

  // Create the SelphIDVerifierOptions and configure it if needed.
  SelphIDVerifierOptions options = new SelphIDVerifierOptions();

  // Extraction
  // Check 3.1. section to initializate SelphIDVerifier.
  SelphIDFacialAuthenticationResult r = verifier.authenticateFacialWithImageRawTemplate(
    imageQuery, templateTarget, options);

  // Explore the information obtained in SelphIDFacialAuthenticationResult like similarity
  float similarity = r.getSimilarity();

  // Return if images are matching
  return r.getFacialAuthenticationStatus() == FacialAuthenticationStatus.Positive;
}
```

#### 3.3.4. Autenticação facial por meio da fotografia do documento e uma imagem

O método a ser utilizado é o seguinte:

```java
SelphIDFacialAuthenticationResult r = authenticateFacialWithRawDocumentImage(
  byte[] rawDocument,
  byte[] imageTarget,
  SelphIDVerifierOptions options
);
```

Os passos necessários para realizar uma autenticação facial por meio da fotografia do documento e uma imagem são os seguintes (método de exemplo):

> **Passos prévios**
>
> * Obtenha o Token da fotografia do documento (string em base64) por meio da propriedade TokenFaceImage usando o widget SelphID.
> * Obtenha a imagem (string em base64) por meio da propriedade Image usando o widget Selphi.
> * Envie ambas as strings em base64 ao servidor.

```java
boolean isMatch(String tokenFaceImageBase64, String imageBase64) {
  // Decode base64 to get the byte array corresponding to each image on the server.
  byte[] rawDocument = Base64.getDecoder().decode(
    firstImageBase64.getBytes());
  byte[] imageTarget = Base64.getDecoder().decode(
    secondImageBase64.getBytes());

  // Create the SelphIDVerifierOptions and configure it if needed.
  SelphIDVerifierOptions options = new SelphIDVerifierOptions();

  // Extraction
  // Check 3.1. section to initializate SelphIDVerifier.
  SelphIDFacialAuthenticationResult r = verifier.authenticateFacialWithRawDocumentImage(
    rawDocument, imageTarget, options);

  // Explore the information obtained in SelphIDFacialAuthenticationResult like similarity
  float similarity = r.getSimilarity();

  // Return if images are matching
  return r.getFacialAuthenticationStatus() == FacialAuthenticationStatus.Positive;
}
```

#### 3.3.5. Autenticação facial por meio da fotografia do documento e um template biométrico

O método a ser utilizado é o seguinte:

```java
SelphIDFacialAuthenticationResult r = authenticateFacialWithRawDocumentRawTemplate(
  byte[] rawDocument,
  byte[] templateTarget,
  SelphIDVerifierOptions options
);
```

* Os passos necessários para realizar a autenticação facial por meio da fotografia do documento e do template biométrico do usuário são os seguintes (método de exemplo):

> **Passos prévios**
>
> * Obtenha o Token da fotografia do documento (string em base64) por meio da propriedade TokenFaceImage usando o widget SelphID.
> * Obtenha o template biométrico (string em base64) por meio da propriedade TemplateRaw usando o widget Selphi.
> * Envie ambas as strings em base64 ao servidor.

```java
boolean isMatch(String rawDocumentBase64, String templateTargetBase64) {
  // Decode base64 to get the byte array corresponding to each image on the server.
  byte[] rawDocument = Base64.getDecoder().decode(
    rawDocumentBase64.getBytes());
  byte[] templateTarget = Base64.getDecoder().decode(
    templateTargetBase64.getBytes());

  // Create the SelphIDVerifierOptions and configure it if needed.
  SelphIDVerifierOptions options = new SelphIDVerifierOptions();

  // Extraction
  // Check 3.1. section to initializate SelphIDVerifier.
  SelphIDFacialAuthenticationResult r = verifier.authenticateFacialWithRawDocumentRawTemplate(
    rawDocument, templateTarget, options);

  // Explore the information obtained in SelphIDFacialAuthenticationResult like similarity
  float similarity = r.getSimilarity();

  // Return if images are matching
  return r.getFacialAuthenticationStatus() == FacialAuthenticationStatus.Positive;
}
```

## 3.4. Método de extração de dados do documento

Para obter os dados do documento necessários nos processos de onboarding digital, o integrador dispõe de um método na classe `SelphIDVerifier`.

> **Nota**
>
> O resultado deste método será um objeto `SelphIDDocumentResult` que contém todos os dados detectados no documento. Para mais informações, consulte a seção [3.9.3. SelphIDDocumentResult](#393-selphiddocumentresult).

#### 3.4.1. Obtenção dos dados detectados em um documento

O método a ser utilizado é o seguinte:

```java
SelphIDDocumentResult extractDocumentWithRawDocument(
  byte[] rawDocumentBuffer,
  SelphIDVerifierOptions selphIDVerifierOptions
);
```

Os passos necessários para obter os dados de um documento são os seguintes (método de exemplo):

> **Passos prévios**
>
> * Obtenha o valor da propriedade `TokenOCR` (string em base64) usando o widget SelphID.
> * Envie a string em base64 ao servidor.

```java
void printDocumentData(String tokenOCRBase64) {
  // Decode base64 to obtain the byte array corresponding to the token on the server.
  byte[] rawDocumentBuffer = Base64.getDecoder().decode(
    tokenOCRBase64.getBytes());

  // Create the SelphIDVerifierOptions and configure it if needed.
  SelphIDVerifierOptions options = new SelphIDVerifierOptions();

  // Extraction
  // Check 3.1. section to initializate SelphIDVerifier.
  SelphIDDocumentResult r = verifier.extractDocumentWithRawDocument(
    rawDocumentBuffer, options);

  // Explore the information obtained in SelphIDDocumentResult.

  // Get document keys.
  String[] keys = r.listDocumentKeys();

  // Print document data.
  for(int x=0; x<keys.length; x++) {
    System.out.println(
      keys[x] + ": " + getDocumentValue(keys[x]);
    );
  }
}
```

## 3.5. Métodos de avaliação de prova de vida

Para avaliar a prova de vida do usuário no servidor, funcionalidade necessária no processo de onboarding digital para evitar fraude por foto ou vídeo, o integrador dispõe de um método para esse fim na classe `SelphIDVerifier`.

> **Nota**
>
> O resultado desses métodos será sempre um objeto `SelphIDFacialLivenessResult`, explicado em [3.9.4. SelphIDFacialAuthenticationResult](#394-selphidfaciallivenessresult).

#### 3.5.1. Avaliação de prova de vida a partir de uma imagem

```java
SelphIDFacialLivenessResult r = evaluatePassiveLivenesWithImageBuffer(
  byte[] imageBuffer
);
```

Os passos necessários para realizar uma autenticação facial por meio de duas imagens são os seguintes (método de exemplo):

> **Passos prévios**
>
> * Obtenha uma imagem do usuário (string em base64) usando o widget Selphi.
> * Envie a string em base64 da imagem ao servidor.

```java
boolean isAlive(String imageBase64) {
  // Decode the base64 image to get the byte array.
  byte[] imageBuffer = Base64.getDecoder().decode(
    imageBase64.getBytes());

  // Evaluate
  // Check 3.1. section to initializate SelphIDVerifier.
  SelphIDFacialLivenessResult r = verifier.evaluatePassiveLivenesWithImageBuffer(
    imageBuffer);

  // Return if is alive
  return r.getFacialLivenessDiagnostic == FacialLivenessDiagnostic.Live;
}
```

#### 3.5.2. Avaliação de prova de vida a partir de uma imagem tokenizada

> A partir da versão `6.21.0`, a imagem tokenizada incorpora um mecanismo de defesa contra ataques de injeção. Se for detectado um token inválido, será retornado `NoneBecauseTokenDataError` ou `NoneBecauseTokenSecurity` como diagnóstico.

```java
SelphIDFacialLivenessResult r = evaluatePassiveLivenessWithTokenBuffer(
  byte[] tokenBuffer
);
```

Os passos necessários para realizar uma autenticação facial por meio de duas imagens são os seguintes (método de exemplo):

> **Passos prévios**
>
> * Obtenha uma imagem do usuário (string em base64) usando o widget Selphi.
> * Envie a string em base64 da imagem ao servidor.

```java
boolean isAlive(String imageBase64) {
  // Decode the base64 image to get the byte array.
  byte[] tokenBuffer = Base64.getDecoder().decode(
    imageBase64.getBytes());

  // Evaluate
  // Check 3.1. section to initializate SelphIDVerifier.
  SelphIDFacialLivenessResult r = verifier.evaluatePassiveLivenessWithTokenBuffer(
    tokenBuffer);

  // Return if is alive
  return r.getFacialLivenessDiagnostic == FacialLivenessDiagnostic.Live;
}
```

## 3.6. Métodos de identificação 1:N

Para realizar buscas 1:N que permitam identificar um determinado padrão biométrico frente a um banco de dados e, assim, obter um conjunto de candidatos com um maior percentual de semelhança, o integrador dispõe de diferentes métodos na classe `SelphIDIdentifier`.

```java
public class SelphIDIdentifier {
  // True if gallery has been created correctly.
  boolean createGallery(String galleryID) {}

  // True if gallery has been created correctly.
  boolean createGalleryWithPath(String galleryID, String galleryFilePath) {}

  // True if gallery has been removed correctly.
  boolean clearGallery(String galleryID) {}

  // Get all galleries for identification.
  String[] getAllGalleries() {}

  // True if each gallery have been removed correctly.
  boolean clearAllGalleries() {}

  // Feed a gallery with a new template using SelphIDFacialExtractionResult
  int enrollWithExtractionResult(String galleryID, String templateID, SelphIDFacialExtractionResult extractionResult) {}

  // Feed a gallery with a new template using byte[] template
  int enrollWithFacialTemplate(String galleryID, String templateID, byte[] facialTemplateBuffer) {}

  // Check if a person exists in the gallery via SelphIDFacialExtractionResult.
  SelphIDIdentifierResult identifyWithExtractionResult(String galleryID, SelphIDFacialExtractionResult extractionResult, SelphIDIdentifierOptions identifierOptions) {}

  // Check if a person exists in the gallery via byte[] template.
  SelphIDIdentifierResult identifyWithFacialTemplate(String galleryID, byte[] facialTemplateBuffer, SelphIDIdentifierOptions identifierOptions) {}

  SelphIDFacialGalleryInfo getGalleryInfo(String galleryID) {}

  boolean removeWithGalleryIndex(String galleryID, int templateIndex) {}

  boolean removeWithTemplateID(String galleryID, String templateID) {}
}
```

#### 3.6.1. Construção da galeria de busca

Como passo prévio para realizar operações de identificação, deve-se criar uma galeria e registrar nela o conjunto de padrões biométricos sobre os quais a busca será realizada. Para incorporar templates à galeria, você pode usar os seguintes métodos:

```java
public class SelphIDIdentifier {
  int enrollWithExtractionResult(
    String galleryID,
    String templateID,
    SelphIDFacialExtractionResult extractionResult
  ) {}

  int enrollWithFacialTemplate(
    String galleryID,
    String templateID,
    byte[] facialTemplateBuffer
  ) {}
}
```

Em ambos os métodos, será especificado o identificador da galeria à qual o template deve ser adicionado, bem como um identificador lógico relacionado à lógica de negócios da aplicação, de modo que os candidatos obtidos como resultado de uma busca na galeria possam ser vinculados a ele.

```java
// 1. Create the gallery.
String galleryID = "my-new-id-or-uuid-1";
createGallery(galleryID);

// 2. Generate the facial templates from the images if you do not have them.
byte[] image1 = ...;
byte[] image2 = ...;
SelphIDVerifierOptions options = new SelphIDVerifierOptions();

SelphIDFacialExtractionResult extractionResult1 = extractFacialWithImageBuffer(
  image1, options);

SelphIDFacialExtractionResult extractionResult2 = extractFacialWithImageBuffer(
  image2, options);

// 3. The obtained facial templates will be added to the gallery by using any of the following methods of the `SelphIDIdentifier` class (you need to initializate it).

//    3.1. Create / Generate the template ID that will have in gallery
String templateID1 = "my-new-id-or-uuid-2";
String templateID2 = "my-new-id-or-uuid-3";

//    3.2. Insert the templates into the gallery with enrollWithExtractionResult
identifier.enrollWithExtractionResult(galleryID, templateID1, extractionResult1);

//    3.3. Insert the templates into the gallery with enrollWithFacialTemplate
byte[] facialTemplateBuffer = extractionResult2.getFacialTemplate();

identifier.enrollWithFacialTemplate(galleryID, templateID2, facialTemplateBuffer);
```

> **Nota**
>
> Para registrar um template biométrico em uma galeria, será necessário gerar o padrão facial equivalente ou FacialTemplate por meio de qualquer um dos seguintes métodos da classe `SelphIDVerifier`:
>
> * `ExtractFacialWithRawTemplate`
> * `ExtractFacialWithImageBuffer`
>
> Consulte a seção [3.2.1. Extração facial por meio de uma imagem](#321-extracción-facial-mediante-una-imagen).

#### 3.6.2. Identificação de um template frente a uma galeria de busca

O processo de busca será realizado por meio de qualquer um dos dois métodos a seguir da classe `SelphIDIdentifier`:

```java
public class SelphIDIdentifier {
  SelphIDIdentifierResult identifyWithExtractionResult(
    String galleryID,
    SelphIDFacialExtractionResult extractionResult,
    SelphIDIdentifierOptions identifierOptions
  ) {}

  SelphIDIdentifierResult identifyWithFacialTemplate(
    String galleryID,
    byte[] facialTemplateBuffer,
    SelphIDIdentifierOptions identifierOptions
  ) {}
}
```

Serão especificados o identificador da galeria e um objeto `SelphIDIdentifierOptions` com as seguintes opções de busca:

* `MaxIdentificationCandidates`, para indicar o número máximo de candidatos retornados, ordenados do maior para o menor percentual de similaridade.
* `MinIdentificationSimilarity`, para indicar o limite mínimo de similaridade na comparação para que um candidato seja incluído no conjunto de resultados.

> **Nota**
>
> Por padrão, `MaxIdentificationCandidates` será `20` e `MinIdentificationSimilarity` será `0f`.

A seguir veremos um exemplo com ambos os métodos:

```java
// 1. Para uma galeria existente, só precisamos do seu ID e da imagem para procurar essa pessoa na galeria.
String galleryID = "galleryID";
byte[] imageToSearch = ...;
SelphIDIdentifierOptions identifierOptions = new SelphIDIdentifierOptions();

// 2. Configure as SelphIDIdentifierOptions
identifierOptions.setMaxIdentificationCandidates(5);
identifierOptions.setMinIdentificationSimilarity(0.6f);

// 3. Extraia o template facial
SelphIDVerifierOptions verifierOptions = new SelphIDVerifierOptions();

SelphIDFacialExtractionResult extractionResult = identifier.extractFacialWithImageBuffer(
  imageToSearch, verifierOptions);

// 4. Pesquise-o com identifyWithExtractionResult ou identifyWithFacialTemplate se você já tiver o template facial.
SelphIDIdentifierResult result = identifier.identifyWithExtractionResult(
  galleryID, extractionResult, identifierOptions);

byte[] facialTemplateBuffer = extractionResult.getFacialTemplate();
SelphIDIdentifierResult result = identifyWithFacialTemplate(
  galleryID, facialTemplateBuffer, identifierOptions);

// 5. Veja os resultados. Obtemos um array com todas as possíveis coincidências, então, por exemplo, se quisermos obter a primeira coincidência:
if (result.size() > 0) {
  FacialAuthenticationStatus authenticate = identifierResult.getFacialAuthenticationStatus(0);
  float similarity = result.getSimilarity(0);
  String templateId = result.getTemplateID(0);
}
```

> **Nota**
>
> Para saber mais sobre `SelphIDIdentifierResult`, consulte a seção [3.9.5. SelphIDIdentifierResult](#395-selphididentifierresult).

#### 3.6.3. Excluir um template da galeria

O processo de exclusão consiste em bloquear um template biométrico de uma galeria específica para que ele não seja levado em conta nos processos de identificação. Se utilizarmos a variável de ambiente `FACEPHI_SELPHID_GALLERY_REMOVE_METHOD=noerase`, essa exclusão não reduz o tamanho da galeria nem a indexação dos templates biométricos associados. Pelo contrário, omitir essa variável ou utilizar `FACEPHI_SELPHID_GALLERY_REMOVE_METHOD=erase` reduzirá o tamanho da galeria após a exclusão, alterando a indexação dos templates.

```java
public class SelphIDIdentifier {
  boolean removeWithGalleryIndex(
    String galleryID,
    int templateIndex
  ) {}

  boolean removeWithTemplateID(
    String galleryID,
    String templateID
  ) {}

}
```

O processo de exclusão é realizado com o seguinte método da classe `SelphIDIdentifier`:

```java
// Por exemplo, vamos remover um usuário específico.
String galleryID = "galleryID";
byte[] facialTemplateBuffer = ...;
SelphIDIdentifierOptions identifierOptions = new SelphIDIdentifierOptions();
identifierOptions.setMaxIdentificationCandidates(1);
identifierOptions.setMinIdentificationSimilarity(0.5f);

// Pesquise o template coincidente na galeria.
SelphIDIdentifierResult identifierResult = identifier.identifyWithFacialTemplate(
  galleryID, facialTemplateBuffer, identifierOptions);

// Se a coincidência tiver sido encontrada e corresponder, ela será removida.
if (result.size() > 0 &&
  identifierResult.getFacialAuthenticationStatus(0) == FacialAuthenticationStatus.Positive) {
  // Obtenha o índice do template
  int templateIndex = identifierResult.getGalleryIndex(0);

  boolean removed = removeWithGalleryIndex(galleryID, templateIndex);

  if (removed) {
    System.out.println("Template correctly removed.");
  }
}
```

#### 3.6.4. Consultar e excluir templates obsoletos

A partir da versão `6.17.0`, cada padrão biométrico armazena o carimbo de data/hora (relógio do sistema) em que foi indexado na galeria. Isso permite consultar e excluir templates "expirados" de acordo com critérios específicos.

```java
public class SelphIDIdentifier {
  String[] listObsoleteGalleryTemplateIDs(
    String galleryID,
    int intervalSeconds
  ) {}

  String[] removeObsoleteGalleryTemplateIDs(
    String galleryID,
    int intervalSeconds
  ) {}
}
```

Em ambos os casos, serão listados os IDs de template cujos carimbos de data/hora sejam anteriores ao intervalo indicado (em segundos). No caso de `removeObsoleteGalleryTemplateIDs()`, a operação será atômica e eliminará todos os padrões obsoletos em uma única operação. Se tiver sido configurado `FACEPHI_SELPHID_GALLERY_REMOVE_METHOD=erase`, o tamanho da galeria será reduzido e os padrões restantes serão reindexados.

```java
// Por exemplo, vamos remover um usuário específico.
String galleryID = "galleryID";

// Remova todos os padrões biométricos com mais de um dia
String [] obsoleteIDs = removeObsoleteGalleryTemplateIDs(galleryID, 24 * 3600);

if (obsoleteIDs.length > 0) {
  System.out.println("Biometric patterns removed from gallery.");
  for (int i = 0; i < obsoleteIDs.length; ++i)
    System.out.println(obsoleteIDs[i]);
}
```

#### 3.6.5. Consultar informações de uma galeria

O objetivo do processo de consulta de uma galeria é servir como etapa prévia para poder realizar outras consultas sobre ela.

O processo será realizado com a seguinte classe de `SelphIDIdentifier`:

```java
public class SelphIDIdentifier {
  SelphIDFacialGalleryInfo getGalleryInfo(
    String galleryID
  ) {}
}
```

Deve ser utilizado um identificador de galeria para consultar a galeria específica. A seguir veremos em que consiste o objeto `SelphIDFacialGalleryInfo`:

```java
public class SelphIDFacialGalleryInfo {
  // Verifica se a galeria é válida.
  boolean getValidGallery();

  // Obtém o ID da galeria.
  String getGalleryID();

  // Obtém o tamanho da galeria.
  int getGallerySize();

  // Obtém um template com o índice.
  String getTemplateID(int index);

  // Obtém todos os índices de uma galeria que correspondem a um valor exato.
  int[] getIndicesWithTemplateID(String templateID);
}
```

#### 3.6.6. Consultar os índices que coincidem com um `templateID` específico

O processo de consulta de todos os índices de uma galeria que coincidem com um valor exato de `templateID` deve ser realizado com o seguinte método de `SelphIDFacialGalleryInfo` que vimos na [seção anterior](#365-consultar-información-de-una-galería):

> **Importante**
>
> A partir do SelphID `6.15.0`, **não são permitidos elementos com templateID duplicado**.

```java
public class SelphIDFacialGalleryInfo {
  int[] getIndicesWithTemplateID(
    String templateID
  );
}
```

Deve ser especificado um `templateID` que corresponda ao `templateID` que se busca na galeria.

Para isso, é necessário dispor de uma instância de `SelphIDFacialGalleryInfo` com dados válidos:

```java
String galleryID = "galleryID";
String templateID = "templateID";

SelphIDFacialGalleryInfo galleryInfo = identifier.getGalleryInfo(galleryID);

int[] indicesTemplateID = galleryInfo.getIndicesWithTemplateID(templateID);
```

## 3.7. Orquestrador

O orquestrador permite obter, na mesma chamada, a autenticação facial e o teste de vida da pessoa. Podemos optar por realizar o teste com uma imagem e um template, ou com dois templates.

> **Importante**
>
> O teste de vida será realizado somente após uma autenticação bem-sucedida.

```java
SelphIDVerifierResult r = verifySelphIDWithImageRawTemplate(
  byte[] imageBuffer,
  byte[] templateTarget,
  SelphIDVerifierOptions options
);

SelphIDVerifierResult r = verifySelphIDWithRawTemplates(
  byte[] templateQuery,
  byte[] templateTarget,
  SelphIDVerifierOptions options
);
```

> **Nota**
>
> Para mais informações sobre `SelphIDVerifierResult`, consulte a seção [3.9.6. SelphIDVerifierResult](#396-selphidverifierresult).

## 3.8. API Tracking

A partir da versão 4.1.0, o SelphID-SDK incorpora a funcionalidade de rastreamento de eventos (event tracking) que permite monitorar e visualizar a atividade da API por meio de uma interface web. A licença do SelphID incluirá todos os dados necessários para acessar a plataforma (na versão single-tenant).

Todos os métodos anteriores de outras versões da API continuam vigentes. Foram adicionados alguns métodos duplicados que agora recebem um novo parâmetro no qual se encontram dados tokenizados com a informação essencial para se comunicar com o servidor de Tracking. Esse parâmetro se denomina `extraData`.

### 3.8.1. Versão Multi-tenant

A partir da versão 4.3.0, o SelphID-SDK permite dois modos de funcionamento em relação ao registro de eventos por meio da API-Tracking:

* **Single-tenant**: Os dados de conexão ao serviço de API Tracking estão criptografados dentro da licença do SelphID-SDK e serão utilizados em todas as chamadas ao serviço.
* **Multi-tenant**: Os dados de conexão serão recebidos em cada chamada por meio do aplicativo móvel. Isso permitirá que o SDK registre eventos em diferentes servidores de acordo com o cliente que realiza a chamada.

> **Importante**
>
> Para habilitar o modo multi-tenant, os dados de Tracking não devem ser incluídos na licença do SelphID-SDK. Caso contrário, o modo single-tenant será ativado ao iniciar o backend.

A partir da versão 5.0.0, é possível alternar entre os modos Single-tenant e Multi-tenant em tempo de execução, utilizando estes métodos de `SelphIDVerifier`:

```java
void setMultitenantMode(boolean multiTenant);

boolean isMultitenantEnabled();
```

### 3.8.2. Registro

Com o seguinte método, permite-se a descriptografia dos dados tokenizados em `rawDocumentBuffer`, como: OCR, imagens do documento etc. No parâmetro `extraData` devem ser enviados os dados necessários para o serviço de Tracking.

```java
SelphIDDocumentResult r = extractDocumentWithRawDocument(
  byte[] rawDocumentBuffer,
  byte[] extraData,
  SelphIDVerifierOptions options
);
```

Os métodos a seguir recebem uma imagem criptografada `rawTemplateBufferTarget` ou uma imagem não criptografada `imageBufferTarget`, para compará-la com a imagem extraída do documento `rawDocumentBufferQuery`. Em ambos os casos, os dados necessários para o serviço de Tracking devem ser enviados no parâmetro `extraData`.

```java
SelphIDFacialAuthenticationResult r = authenticateFacialWithRawDocumentRawTemplate(
  byte[] rawDocumentBufferQuery,
  byte[] rawTemplateBufferTarget,
  byte[] extraData,
  SelphIDVerifierOptions options
);

SelphIDFacialAuthenticationResult r = authenticateFacialWithRawDocumentImage(
  byte[] rawDocumentBufferQuery,
  byte[] imageBufferTarget,
  byte[] extraData,
  SelphIDVerifierOptions options
);
```

### 3.8.3. SelphIDVerifierOptions

Os métodos a seguir, adicionados à classe `SelphIDVerifierOptions`, permitem que as informações inseridas pelo cliente sejam representadas nos servidores de Tracking, no caso de uso de registro.

```java
public class SelphIDVerifierOptions {
  void setElapsedTimeAllowed(int elapsedTimeAllowed);
  void setFutureTimeAllowed(int futureTimeAllowed);
  void setFacialDetectionType(FacialDetectionType facialDetectionType);
  void setMinFaceAbs(int minFaceAbs);
  void setMinFaceRel(float minFaceRel);
  void setFalseDetectRate(float rate);
  void setMinIODThreshold(int minIODThreshold);
  void setMaxPoseThreshold(int maxPoseThreshold);
  void setMinimumFacialQuality(int minimumFacialQuality);
  void setAnalyticsDetection(boolean analyticsDetection);
  void setFacialTemplateRawExtraction(boolean facialTemplateRawExtraction);
  void setOptionalDataClientInformation(String json);
  void setCustomFacialAuthenticationThreshold(int customFacialAuthenticationThreshold);
  void setLivenessDepth(LivenessDepth livenessDepth);
}
```

O parâmetro de entrada do método `setOptionalDataClientInformation` deve ser um JSON bem formado que aceitará as seguintes chaves:

```json
{
  "address": "String",
  "birthDate": "String",
  "birthPlace": "String",
  "city": "String",
  "documentNumber": "String",
  "name": "String",
  "nationality": "String",
  "surname": "String"
}
```

> **Nota**
>
> Qualquer outra chave será ignorada. No futuro, haverá suporte a mais chaves.

A partir da versão `6.17.0`, foi adicionada a propriedade `futureTimeAllowed`. Isso permite estabelecer um intervalo de tempo (em segundos) durante o qual serão aceitos templates e imagens tokenizadas com uma data futura, retornando `true` no método `getValidTimeStamp()`. Isso tem como objetivo mitigar as diferenças de fuso horário entre dispositivos. Esse valor pode ser configurado globalmente por meio da variável de ambiente `FACEPHI_SELPHID_FUTURE_TIME_ALLOWED=3600`.

A partir da versão `6.18.0`, podemos especificar quais pipelines de Liveness queremos executar para cada operação por meio de `setLivenessDepth()`. No caso de `None` (valor padrão), será aplicada a configuração global definida por `FACEPHI_SELPHID_FACIALLIVENESS_DEPTH`.

### 3.8.4. Autenticação

Os métodos a seguir estão disponíveis para realizar a autenticação. Os parâmetros `rawTemplateBuffer` recebem a imagem criptografada, e o parâmetro `imagebufferQuery` recebe a imagem não criptografada. Em ambos os casos, os dados necessários para o serviço de Tracking devem ser enviados no parâmetro `extraData`.

```java
SelphIDFacialAuthenticationResult r = authenticateFacialWithRawTemplates(
  byte[] rawTemplateBufferQuery,
  byte[] rawTemplateBufferTarget,
  byte[] extraData,
  SelphIDVerifierOptions options
);

SelphIDFacialAuthenticationResult r = authenticateFacialWithImageRawTemplate(
  byte[] imageBufferQuery,
  byte[] rawTemplateBufferTarget,
  byte[] extraData,
  SelphIDVerifierOptions options
);
```

### 3.8.5. Liveness passivo

Os métodos a seguir estão disponíveis para realizar o teste de vida passivo. O parâmetro `tokenBuffer` recebe a imagem criptografada e `imageBuffer` a imagem não criptografada. Em ambos os casos, os dados necessários para o serviço de Tracking devem ser enviados no parâmetro `extraData`.

```java
SelphIDFacialLivenessResult r = evaluatePassiveLivenessWithTokenBuffer(
  byte[] tokenBuffer,
  byte[] extraData
);

SelphIDFacialLivenessResult r = evaluatePassiveLivenesWithImageBuffer(
  byte[] imageBuffer,
  byte[] extraData
);
```

### 3.8.6. Eventos personalizados

A partir da versão 4.5.0, o SelphID implementa a possibilidade de enviar eventos personalizados para a API de Tracking, não vinculados a nenhuma operação interna do SDK. Todas as operações de eventos personalizados retornam um código de status e uma mensagem, dentro de um objeto `SelphIDApiTrackingResult`.

O método a seguir permite enviar à API de Tracking o evento de **Autenticação facial**, utilizando os parâmetros `authStatus` e `similarity`. Também podemos registrar no serviço de API Tracking a(s) imagem(ns) envolvida(s) na autenticação. Ambas as imagens são opcionais, aceitando buffers nulos ou vazios.

```java
SelphIDApiTrackingResult r = authenticateFacialTrackingEvent(
  TrackingFamily family,
  FacialAuthenticationStatus authStatus,
  float similarity,
  String source,
  byte[] imageBufferQuery,
  byte[] imageBufferTarget,
  byte[] extraData
);
```

Valores possíveis de `TrackingFamily`:

```java
public enum TrackingFamily {
  Onboarding,
  Authentication
}
```

O método a seguir permite enviar à API de Tracking o evento de **Liveness**, utilizando os parâmetros `diagnostic` e `similarity`. Também podemos registrar no serviço de API Tracking a imagem envolvida no processo de vida, embora isso seja opcional, aceitando um buffer nulo ou vazio.

```java
SelphIDApiTrackingResult r = evaluatePassiveLivenessTrackingEvent(
  TrackingFamily family,
  FacialLivenessDiagnostic diagnostic,
  String source,
  byte[] imageBuffer,
  byte[] extraData
);
```

O método a seguir permite enviar à API de Tracking o evento de **Autenticação por voz**, utilizando o parâmetro `probability`. Também podemos registrar no serviço de API Tracking as pistas de áudio envolvidas no processo de autenticação por voz. Ambos os buffers são opcionais, aceitando valores nulos ou vazios.

```java
SelphIDApiTrackingResult r = voiceAuthenticationTrackingEvent(
  float probabiliy,
  String source,
  byte[] audioDataBufferQuery,
  byte[] audioDataBufferTarget,
  byte[] extraData
);
```

O método a seguir permite enviar um evento personalizado de OCR ao servidor da API Tracking.

```java
SelphIDApiTrackingResult r =  ocrTrackingEvent(
  String ocrDataJson,
  String source,
  byte[] extraData
);
```

`ocrDataJson` é um dicionário chave-valor em formato JSON bem formado. Aceita qualquer tipo de nome de chave com qualquer valor de string:

```json
{
  "OCR_Key1": "OCR_Value1",
  "OCR_Key2": "OCR_Value2",
  "OCR_Key3": "OCR_Value3",
  "OCR_Key4": "OCR_Value4",
  "OCR_Key5": "OCR_Value5"
}
```

O método a seguir permite enviar um evento personalizado SECURITY\_INFO\_DATA ao servidor da API Tracking:

```java
  SelphIDApiTrackingResult r = securityInfoTrackingEvent(
  String securityDataJson,
  boolean succeed,
  String source,
  byte[] extraData
  );
```

`securityDataJson` são os dados de segurança em formato JSON:

```json
{
  "Security_Key1": "Security_Value1",
  "Security_Key2": "Security_Value2",
  "Security_Key3": "Security_Value3",
  "Security_Key4": "Security_Value4",
  "Security_Key5": "Security_Value5"
}
```

`succeed` é um valor booleano que indica se a obtenção dos dados de segurança foi realizada corretamente ou não, e `source` é o nome do serviço ou da origem dos dados de segurança.

Para todas as operações de eventos personalizados, podemos modificar o campo criptografado `eventSource` dentro do token `extraData`.

```java
byte[] extraData2 = setTrackingEventSource(
  String eventSource,
  byte[] extraData
);
```

Dentro dos eventos personalizados, oferece-se a possibilidade de **encerrar a operação** por meio do seguinte método:

```java
SelphIDApiTrackingResult r = finishTrackingEvent(
  TrackingFamily family,
  OperationResultStatus status,
  OperationResultReason reason,
  byte[] extraData
);
```

Este método registrará no serviço de API Tracking os eventos de **Resultado da operação** (Operation result) e **Finalização de mudança de etapa** (Step change finish), que encerram a operação.

> **Importante**
>
> O significado desses atributos, incluindo esses enums, será determinado pelo usuário.

Valores possíveis de `OperationResultStatus`:

```java
public enum OperationResultStatus {
  Succeeded,

  // Negado.
  Denied,

  // Erro.
  Error,

  // Cancelado.
  Cancelled
}
```

Valores possíveis de `OperationResultReason`:

```java
public enum OperationResultReason {
  // Não especificamos um motivo concreto.
  None,

  // Algum erro ao usar o SDK.
  InternalError,

  // A operação foi cancelada pelo usuário.
  CancelledByUser,

  // O Timeout definido expirou.
  Timeout,

  // A validação do documento falhou.
  DocumentValidationNotPassed,

  // Erro durante a validação do documento.
  DocumentValidationError,

  // Authentication falhou.
  AuthenticationNotPassed,

  // Erro durante a Authentication.
  AuthenticationError,

  // Liveness falhou.
  LivenessNotPassed,

  // Erro durante o Liveness.
  LivenessError
}
```

### 3.8.7. Servidor proxy

Desde a Versão 4.5.5 do SelphID-SDK, é possível enviar solicitações para a API de Tracking por meio de um servidor proxy. Para configurar os parâmetros do proxy, use o seguinte método:

```java
setTrackingProxy(
        String proxyHost,
        int proxyPort,
        String proxyUser,
        String proxyPass);
```

Para desabilitar o proxy, deve ser passada uma string vazia como parâmetro `proxyHost`.

## 3.9. Descrição dos resultados da API

As seguintes propriedades, nas classes de resultado, permitem avaliar os resultados de cada um dos métodos mencionados acima.

A partir da versão `6.18.0`, além de verificar a validade de um Token por meio de `getValidTimeStamp()`, agora podemos obter a marca temporal incorporada no próprio Token por meio de `getTokenTimeStamp()`. Isso afeta:

* `SelphIDFacialExtractionResult`.
* `SelphIDFacialAuthenticationResult`.
* `SelphIDDocumentResult`.
* `SelphIDFacialLivenessResult`.

### 3.9.1. SelphIDFacialExtractionResult

Apresenta diferentes propriedades para avaliar o resultado da extração facial:

```java
public class SelphIDFacialExtractionResult {
  // Indica se a extração conseguiu ser processada com sucesso.
  boolean getExtractionOK() {}

  // Padrão biométrico da pessoa detectada.
  byte[] getFacialTemplate() {}

  // Valor (0, 1) que indica o grau de confiabilidade da extração.
  float getFaceConfidence() {}

  // Localização dos pontos de referência detectados na imagem.
  Point getLeftEye() {}
  Point getRightEye() {}
  Point getChin() {}
  Point getNose() {}
  Point getLeftMouth() {}
  Point getRigthMouth() {}

  // Distância interocular.
  int getIOD() {}

  // Orientação do rosto em relação à câmera. Os valores possíveis são os seguintes:
  FacialPose getFacialPose() {}

  // Ângulos de orientação do rosto.
  float getYaw() {}
  float getPitch() {}
  float getRoll() {}

  // Valor (0, 1) que indica a qualidade da imagem de entrada.
  float getImageQuality() {}

  // Indica a qualidade do rosto detectado. Os valores possíveis são os seguintes:
  FacialQuality getFacialQuality() {}

  // Indica se a pessoa usa óculos. Os valores possíveis são os seguintes:
  FacialGlasses getGlasses() {}

  // Valor numérico que indica a idade aproximada da pessoa.
  int getAge() {}

  // Gênero da pessoa. Os valores possíveis são os seguintes:
  FacialGender getGender() {}

  // Valor (0, 1) que indica a probabilidade de a pessoa usar uma máscara.
  float getFacialMask() {}

  // Obtém se o timestamp é válido.
  boolean getValidTimeStamp() {}

  // Obtém o timestamp do Token.
  long getTokenTimeStamp() {}
}
```

Valores possíveis de `FacialPose`:

```java
public enum FacialPose {
  // Desconhecido ou não calculado.
  None,

  // Olhando diretamente para a frente.
  Frontal,

  // Pessoa olhando para a direita.
  RightAngled,

  // Pessoa olhando para a esquerda.
  LeftAngled
}
```

Valores possíveis de `FacialQuality`:

```java
public enum FacialQuality {
  None,
  Bad,
  Regular,
  Good
}
```

Valores possíveis de `Glasses`:

```java
public enum Glasses {
  None,
  Eyes,
  Sun
}
```

Valores possíveis de `Gender`:

```java
public enum Gender {
  None,
  Male,
  Feminino
}
```

### 3.9.2. SelphIDFacialAuthenticationResult

Apresenta diferentes propriedades para avaliar o resultado da Authentication biométrica:

```java
public class SelphIDFacialAuthenticationResult {
  // Resultados de um processo de Authentication facial.
  FacialAuthenticationStatus getFacialAuthenticationStatus() {}

  // Valor de similaridade entre 0 e 1 que representa a similaridade entre os rostos das duas imagens.
  float getSimilarity() {}

  // Obtém se o timestamp é válido.
  boolean getValidTimeStamp() {}

  // Obtém o timestamp do Token.
  long getTokenTimeStamp() {}
}
```

> **Importante**
>
> Para avaliar o resultado, você deve utilizar a propriedade `FacialAuthenticationStatus`; o valor `similarity` é usado apenas para fins estatísticos.

Valores possíveis de `FacialAuthenticationStatus`:

```java
public enum FacialAuthenticationStatus {
  // A Authentication biométrica não pôde ser realizada.
  None,

  // Resultado negativo de Authentication.
  Negative,

  // OBSOLETO.
  Uncertain,

  // Resultado positivo de Authentication.
  Positive,

  // A Authentication biométrica não pôde ser realizada porque o ângulo máximo permitido entre os rostos de cada imagem fornecida foi excedido.
  NoneBecausePoseExceeded,

  // A Authentication biométrica não pôde ser realizada porque a extração de características biométricas não pôde ser realizada em nenhuma das imagens fornecidas.
  NoneBecauseInvalidExtractions
}
```

### 3.9.3. SelphIDDocumentResult

Apresenta diferentes métodos para recuperar as imagens usadas no processo e os dados lidos do documento. Os métodos são os seguintes:

```java
public class SelphIDDocumentResult {
  // Obtém todas as chaves associadas a cada um dos dados lidos do documento.
  String[] listDocumentKeys() {}

  // Obtém um determinado dado lido do documento por meio de sua chave associada.
  String getDocumentValue(String key) {}

  // Obtém todas as chaves associadas a cada uma das imagens lidas do documento.
  String[] listImageKeys() {}

  // Obtém uma determinada imagem do documento por meio de sua chave associada.
  byte[] getImage(String key) {}

  // Obtém a lista de chaves de ExtraData.
  String[] listExtraDataKeys() {}

  // Obtém o valor de ExtraData para a chave fornecida.
  String getExtraDataValue(String key) {}

  // Obtém se o timestamp é válido.
  boolean getValidTimeStamp() {}

  // Obtém o timestamp do Token.
  long getTokenTimeStamp() {}
}
```

### 3.9.4. SelphIDFacialLivenessResult

Apresenta a propriedade `FacialLivenessDiagnostic` para avaliar o resultado do diagnóstico de teste de vida passivo.

```java
public class SelphIDFacialLivenessResult {
  // Obtém o diagnóstico de Liveness facial.
  FacialLivenessDiagnostic getFacialLivenessDiagnostic() {}

  // Adicionado em 6.18.0
  // Obtém informações adicionais quando o diagnóstico de Liveness facial é NoLive.
  SelphIDNoLiveDetails getNoLiveDetails() {}

  // Obtém o timestamp válido
  boolean getValidTimeStamp() {}

  // Obtém o timestamp do Token.
  long getTokenTimeStamp() {}
}
```

Valores possíveis de `FacialLivenessDiagnostic`:

```java
public enum FacialLivenessDiagnostic {
  // O diagnóstico de Liveness não pôde ser avaliado.
  None,

  // Uma condição de fraude foi detectada, um vídeo ou uma fotografia.
  // OBSOLETO > use "NoLive".
  Spoof,

  // OBSOLETO.
  Uncertain,

  // O sujeito passa no diagnóstico de Liveness.
  Live,

  // O Liveness não pôde ser avaliado devido à baixa qualidade das imagens usadas.
  NoneBecauseBadQuality,

  // O Liveness não pôde ser avaliado porque o rosto está muito próximo da câmera.
  NoneBecauseFaceTooClose,

  // O Liveness não pôde ser avaliado porque nenhum rosto foi detectado nas imagens usadas.
  NoneBecauseFaceNotFound,

  // O Liveness não pôde ser avaliado porque foram detectados rostos muito pequenos nas imagens usadas.
  NoneBecauseFaceTooSmall,

  // O Liveness não pôde ser avaliado porque o ângulo entre os rostos foi excedido.
  NoneBecauseAngleTooLarge,

  // O Liveness não pôde ser avaliado devido ao formato das imagens usadas.
  NoneBecauseImageDataError,

  // O Liveness não pôde ser avaliado devido a um erro interno.
  NoneBecauseInternalError,

  // O Liveness não pôde ser avaliado devido a um erro no processamento das imagens usadas.
  NoneBecauseImagePreprocessError,

  // O Liveness não pôde ser avaliado porque há muitas pessoas na cena.
  NoneBecauseTooManyFaces,

  // O Liveness não pôde ser avaliado porque o rosto está muito próximo das bordas da imagem.
  NoneBecauseFaceTooCloseToBorder,

  // O Liveness não pôde ser avaliado porque a imagem usada está recortada.
  NoneBecauseFaceCropped,

  // O teste de vida não pôde ser avaliado devido a um erro de licença.
  NoneBecauseLicenseError,

  // O Liveness não pôde ser avaliado porque o rosto da pessoa está ocluído.
  NoneBecauseFaceOccluded,

  // A imagem não corresponde a uma pessoa real.
  NoLive,

  // O Liveness não pôde ser avaliado porque os olhos da pessoa estão fechados.
  NoneBecauseEyesClosed,

  // O Liveness não pôde ser avaliado porque os olhos da pessoa estão ocluídos.
  NoneBecauseEyesOccluded,

  // None devido a erro nos dados do Token ou formato incorreto.
  NoneBecauseTokenDataError,

  // None devido a quebra das medidas internas de segurança do Token.
  NoneBecauseTokenSecurity
}
```

A partir da Versão 6.18.0, a estrutura `SelphIDNoLiveDetails` com informações adicionais sobre o caso `NoLive`. No caso `Live`, também podemos consultar as pontuações (scores) do pipeline.

```java
// Detalhes do SelphID para o caso FacialLivenessDiagnostic::NoLive.
public class SelphIDNoLiveDetails {
  // Causa principal em alto nível do diagnóstico NoLive.
  NoLiveMainCause getNoLiveMainCause() {}

  // Status da detecção de ataque de apresentação facial (fPAD).
  FPadStatus getFPadStatus() {}

  // Score fPAD normalizado (0..1), se disponível.
  float getFPadScore() {}

  // Status da detecção de ataque de manipulação facial (fMAD).
  FMadStatus getFMadStatus() {}

  // Score fMAD normalizado (0..1), se disponível.
  float getFMadScore() {}

  // Score de coerção normalizado (0..1), se disponível.
  float getCoercionScore() {}

  // Mensagem de motivo legível para humanos, para logs/Backoffice.
  String getReasonMessage() {}
}
```

### 3.9.5. SelphIDIdentifierResult

Apresenta diferentes métodos para obter as informações de comparação de cada um dos candidatos retornados como resultado de uma busca 1:N. São os seguintes:

```java
public class SelphIDIdentifierResult {
  // Obtém o número de candidatos obtidos na busca.
  int size() {}

  // Obtém a similaridade a partir do índice do resultado.
  float getSimilarity(int index) {}

  // Obtém o índice da galeria a partir do índice do resultado.
  int getGalleryIndex(int index) {}

  // Obtém o templateID a partir do índice do resultado.
  String getTemplateID(int index) {}

  // Obtém o código de status da comparação realizada entre o template de busca e o candidato indicado.
  FacialAuthenticationStatus getFacialAuthenticationStatus(int index) {}

  // Obtém informações adicionais caso a comparação biométrica entre o template de busca e o candidato indicado tenha sido positiva.
  FacialAuthenticationDetail getFacialAuthenticationDetail(int index) {}
}
```

Valores possíveis de `FacialAuthenticationStatus`:

```java
public enum FacialAuthenticationStatus {
  // A comparação biométrica não pôde ser realizada.
  None,

  // Os padrões faciais não correspondem.
  Negative,

  // OBSOLETO.
  Uncertain,

  // Os padrões faciais correspondem.
  Positive,

  // A comparação biométrica não pôde ser realizada porque o rosto em algumas das capturas está em um ângulo de rotação muito alto em relação à câmera.
  NoneBecausePoseExceed,

  // A comparação biométrica não pôde ser realizada porque nenhum rosto pôde ser detectado em nenhuma das capturas realizadas.
  NoneBecauseInvalidExtractions
}
```

Valores possíveis de `FacialAuthenticationDetail`:

```java
public enum FacialAuthenticationDetail {
  // A comparação não foi bem-sucedida.
  None,

  // Os padrões faciais correspondem com uma baixa porcentagem de similaridade.
  PositiveLowSecurityLevel,

  // Os padrões faciais correspondem com uma porcentagem média de similaridade.
  PositiveMediumSecurityLevel,

  // Os padrões faciais correspondem com uma alta porcentagem de similaridade.,
  PositiveHighSecurityLevel
}
```

### 3.9.6. SelphIDVerifierResult

Apresenta diferentes métodos para obter informações do orquestrador. São os seguintes:

```java
public class SelphIDVerifierResult {
  // Obtém informações sobre o documento.
  SelphIDDocumentResult getSelphIDDocumentResult() {}

  // Obtém informações sobre o processo de Authentication.
  SelphIDFacialAuthenticationResult GetSelphIDFacialAuthenticationResult() {}

  // Obtém informações sobre o processo de Liveness.
  SelphIDFacialLivenessResult GetSelphIDFacialLivenessResult() {}
}
```

> **Nota**
>
> Para mais informações:
>
> * [3.9.2. SelphIDFacialAuthenticationResult](#392-selphidfacialauthenticationresult)
> * [3.9.3. SelphIDDocumentResult](#393-selphiddocumentresult)
> * [3.9.4. SelphIDFacialLivenessResult](#394-selphidfaciallivenessresult)

### 3.9.7. SelphIDApiTrackingResult

Apresenta diferentes métodos para obter informações da operação da API Tracking. São os seguintes:

```java
public class SelphIDApiTrackingResult {
  // Obtém o resultado HTTP da solicitação de Tracking.
  int GetTrackingStatus() {}

  // Obtém a mensagem da solicitação de Tracking.
  String GetTrackingMessage() {}
}
```

## 3.10. Descrição de SelphIDException

Se ocorrer um erro dentro do SelphID-SDK, a exceção SelphIDException será lançada.

```java
public class SelphIDException extends Exception {
  // Obtém o tipo de exceção que ocorreu.
  SelphIDExceptionType getExceptionType() {}
}
```

Valores possíveis de `SelphIDExceptionType`:

```java
public enum SelphIDExceptionType {
  // Erro no conteúdo da licença.
  ErrorLicenseContent,

  // A licença expirou.
  ErrorLicenseExpired,

  // Erro no HostID da licença.
  ErrorLicenseHostID,

  // Erro no template facial.
  ErrorFacialTemplate,

  // Erro ao carregar a biblioteca.
  // OBSOLETO.
  ErrorLoadingLibrary,

  // Erro no registro de uso da licença.
  ErrorLicenseUsageLogging,

  // Imagem facial com erro ou inválida.
  ErrorFacialImage,

  // Erro nos dados do documento.
  ErrorDocumentData,

  // Erro na licença de rede.
  ErrorLicenseNetwork,

  // Erro porque o número de conexões da licença de rede foi excedido.
  ErrorLicenseNetworkConnectionsExceeded,

  // Tamanho da galeria atingido.
  ErrorLicenseGallerySizeReached,

  // Opções inválidas.
  ErrorInvalidOptions,

  // Erro: a licença está muito antiga.
  ErrorLicenseTooOld,

  // Erro porque um recurso não está disponível.
  ErrorUnavailableFeature,

  // Erro porque o template facial é incompatível.
  ErrorIncompatibleFacialTemplate,

  // Erro ao acessar o arquivo de configuração.
  ErrorConfigurationFileAccess,

  // Erro ao acessar os dados de API Tracking.
  ErrorTrackingFileAccess,

  // Erro ao carregar o arquivo de configuração da API Tracking.
  // OBSOLETO.
  ErrorLoadingTrackingFile,

  // As variáveis de configuração do SelphID estão vazias (arquivo de configuração ou variáveis de ambiente).
  ErrorConfigVarsEmpty,

  // A chave `FACEPHI_SELPHID_INSTALL_PATH` está vazia.
  ErrorInstallPathEmpty,

  // A chave `FACEPHI_SELPHID_FACIALLIVENESS_PATH_KEY` está vazia.
  ErrorLivenessDataPathEmpty,

  // Erro ao carregar a biblioteca de Authentication facial.
  ErrorLoadingFacialLibrary,

  // Erro ao carregar a biblioteca de Liveness.
  ErrorLoadingLivenessLibrary,

  // Erro interno ao executar a extração facial.
  ErrorProcessingFacial,

  // Erro interno ao executar a verificação de Liveness.
  ErrorProcessingLiveness,

  // Erro ao acessar uma galeria no disco.
  ErrorGalleryFile
}
```