> 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/facial-extraction.md).

# Extração facial

Serviço que realiza a **detecção e validação facial** a partir de uma imagem aberta ou tokenizada.

{% hint style="warning" %}
Observe que todos os valores retornados são estimativas baseadas na imagem facial fornecida. A precisão e a confiabilidade reais podem variar dependendo da qualidade e das características da imagem de entrada.
{% endhint %}

### Endpoint

```
POST /extractFacial
```

### 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                                                                                      |
| ---------------------- | ------ | ----------- | ---------------------------------------------------------------------------------------------- |
| `tokenBuffer`          | string | **Sim**     | Imagem codificada em **Base64** ou **tokenizada** para detecção facial.                        |
| `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.                                          |

#### Exemplo de solicitação

```json
{
  "tokenBuffer": "BAMBAQLNHJoWGPjfeuDIzDXdZuP...",
  "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.                                                                                          |
| `serviceResultLog`              | string  | Campo descritivo do resultado ou mensagem de erro, se aplicável.                                                                                         |
| `serviceTime`                   | string  | Tempo de processamento da solicitação **(milissegundos)**.                                                                                               |
| `serviceFacialExtractionResult` | string  | Objeto JSON que representa os resultados de **detecção e validação facial**. Consulte [Campos do resultado](#campos-del-resultado-de-extracción-facial). |
| `serviceTransactionId`          | string  | Identificador de transação associado à solicitação processada pela API.                                                                                  |

#### Campos do resultado da extração facial

| Campo            | Tipo    | Descrição                                                                                            |
| ---------------- | ------- | ---------------------------------------------------------------------------------------------------- |
| `faceConfidence` | float   | Indica o **nível de confiança** do rosto avaliado.                                                   |
| `age`            | integer | Indica a **idade possível** detectada.                                                               |
| `glasses`        | string  | Indica detecção de óculos. Valores possíveis: `Eye` (Óculos), `None` (Nenhum), `Sun` (Óculos de sol) |
| `gender`         | string  | Retorna o **gênero detectado**. Valores possíveis: `Male`, `Female`, `None` (Indeterminado)          |
| `iod`            | integer | Indica a **distância interpupilar**.                                                                 |

#### 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         |

#### Exemplo de resposta

```json
{
  "serviceResultCode": 0,
  "serviceResultLog": "Service request successfully processed",
  "serviceTime": "864",
  "serviceFacialExtractionResult": "{\"faceConfidence\":0.9999948143959045,\"age\":30,\"glasses\":\"None\",\"gender\":\"Male\",\"iod\":154}",
  "serviceTransactionId": "b2f6297b-01ca-4aa3-afd7-6cb3c9d74141"
}
```

#### `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"
}
```