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

# Extração de impressão digital

Serviço que realiza a **captura e extração de templates biométricos de impressão digital** a partir de imagens de impressão digital, abertas ou tokenizadas. Cada imagem é convertida em um template (`template`) reutilizável no serviço de autenticação por impressão digital.

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

### Endpoint

```
POST /services/extractFingerprint
```

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

### Corpo da solicitação

**Content-Type:** `application/json`

#### Parâmetros

| Parâmetro               | Tipo    | Obrigatório | Descrição                                                                                                                           |
| ----------------------- | ------- | ----------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| `fingers`               | array   | **Sim**     | Lista de impressões digitais a processar. São aceitas de **1 a 10** impressões digitais por solicitação (configurável por tenant).  |
| `fingers[].position`    | inteiro | **Sim**     | Posição do dedo de acordo com a numeração NIST (**1–10**). Consulte [Posições dos dedos](#posiciones-de-dedo).                      |
| `fingers[].tokenBuffer` | string  | **Sim**     | Imagem da impressão digital em **Base64** ou um **token** da FacePhi. Consulte [Formatos aceitos](#formatos-aceptados-tokenbuffer). |
| `fingers[].dpi`         | inteiro | Não         | Resolução da imagem em pontos por polegada. Se omitido, é usado o valor padrão do tenant (500).                                     |
| `fingers[].scanType`    | string  | Não         | Tipo de captura (`Plain` por padrão). Consulte [Tipos de captura](#tipos-de-captura-scantype).                                      |

#### Posições dos dedos

| Posição | Dedo        | Posição | Dedo       |
| ------- | ----------- | ------- | ---------- |
| 1       | RightThumb  | 6       | LeftThumb  |
| 2       | RightIndex  | 7       | LeftIndex  |
| 3       | RightMiddle | 8       | LeftMiddle |
| 4       | RightRing   | 9       | LeftRing   |
| 5       | RightLittle | 10      | LeftLittle |

#### Formatos aceitos (tokenBuffer)

O campo `tokenBuffer` aceita uma imagem de impressão digital codificada em **Base64**, ou um **token** da FacePhi (referência tokenizada que o serviço resolve internamente).

Formatos de imagem compatíveis com o mecanismo:

| Formato | Descrição                                                                                       |
| ------- | ----------------------------------------------------------------------------------------------- |
| `WSQ`   | Wavelet Scalar Quantization (padrão de Impressão Digital; formato comum dos widgets de captura) |
| `BMP`   | Bitmap                                                                                          |
| `PNG`   | Portable Network Graphics                                                                       |
| `JPEG`  | JPEG                                                                                            |
| `JP2`   | JPEG 2000 (contêiner `.jp2` ou codestream)                                                      |

**Encoding**: base64 padrão. Recomenda-se enviá-lo **sem quebras de linha**; se a imagem vier com base64 "wrapped" (quebras CRLF), o serviço as normaliza automaticamente. O `template` retornado na resposta é **base64 em uma única linha**.

#### Tipos de captura (scanType)

| Valor    | Descrição                                                | Compatibilidade (versão atual)             |
| -------- | -------------------------------------------------------- | ------------------------------------------ |
| `Plain`  | Captura plana / ao vivo (dedo apoiado na horizontal)     | **Compatível** (valor padrão)              |
| `Rolled` | Captura rolada (o dedo é rolado de um lado para o outro) | Requer uma imagem capturada no modo rolado |
| `Latent` | Impressão Digital latente / forense                      | Requer uma imagem latente                  |

* Se omitido, será usado `Plain`.
* O `scanType` deve corresponder ao tipo de imagem enviada. Para a captura padrão do onboarding (incluindo a do Widget), use **`Plain`**.
* Se o mecanismo não conseguir gerar o template com o modo indicado (por exemplo, uma imagem plana enviada como `Rolled`/`Latent`), o serviço responde **`400`** com a mensagem do mecanismo (por exemplo, `"Finger template creation failed"`), e não um `502`.

#### Exemplo de solicitação

```json
{
  "fingers": [
    {
      "position": 2,
      "tokenBuffer": "Rk1SACAyMAAAAAEgAAABPAFiAMUAxQEAAAAo...",
      "dpi": 500,
      "scanType": "Plain"
    }
  ]
}
```

{% hint style="warning" %}
**Tamanho máximo da solicitação: 6 MB.** As imagens de impressão digital em Base64 ou tokenizadas (`fingers[].tokenBuffer`, de 1 a 10 por solicitação) são contabilizadas juntas nesse limite, com uma sobrecarga de \~33% em relação ao arquivo original (máximo de \~4,5 MB de arquivos originais no total). Recomendam-se formatos compactados, como `WSQ`, `JPEG` ou `JP2`. Se o limite for excedido, o gateway responde `413` sem processar a solicitação. Consulte [Limite de tamanho da solicitação](https://docs.facephi.com/pages/1b12810f7c9abac00ee2fed384b12d3575d93434#l%C3%ADmite-de-tama%C3%B1o-de-la-solicitud).
{% endhint %}

### Respostas

#### `200` Sucesso

#### Parâmetros de resposta

| Parâmetro              | Tipo    | Descrição                                                                                                                     |
| ---------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------- |
| `serviceResultCode`    | inteiro | Código que indica o **resultado geral** da execução do serviço.                                                               |
| `serviceResultLog`     | string  | Campo descritivo do resultado ou da mensagem de erro, se aplicável.                                                           |
| `serviceTime`          | string  | Tempo total de processamento **(milissegundos)**.                                                                             |
| `serviceTransactionId` | string  | Identificador da transação associado à solicitação processada pela API.                                                       |
| `templates`            | array   | Lista de templates extraídos, um para cada impressão digital enviada. Consulte [Campos do template](#campos-de-la-plantilla). |

#### Campos do template

| Campo            | Tipo    | Descrição                                                                                              |
| ---------------- | ------- | ------------------------------------------------------------------------------------------------------ |
| `position`       | inteiro | Posição do dedo (1–10) correspondente ao template.                                                     |
| `template`       | string  | Template Biométrico extraído, codificado em Base64. Pode ser reutilizado em `authenticateFingerprint`. |
| `overallQuality` | inteiro | Qualidade geral da impressão digital.                                                                  |
| `nfiq2`          | número  | Pontuação de qualidade **NFIQ 2.0**.                                                                   |
| `nfiq`           | número  | Pontuação de qualidade **NFIQ**.                                                                       |
| `quality`        | número  | Pontuação de qualidade do mecanismo biométrico.                                                        |
| `dpi`            | inteiro | Resolução usada para processar a impressão digital.                                                    |
| `scanType`       | string  | Tipo de captura processado (`Plain`, `Rolled`, `Latent`).                                              |

#### 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": "742",
  "serviceTransactionId": "b2f6297b-01ca-4aa3-afd7-6cb3c9d74141",
  "templates": [
    {
      "position": 2,
      "template": "Rk1SACAyMAAAAAD6AAABPAFiAMUAxQEAAAA...",
      "overallQuality": 82,
      "nfiq2": 78.0,
      "nfiq": 2.0,
      "quality": 0.91,
      "dpi": 500,
      "scanType": "Plain"
    }
  ]
}
```

#### `400` Solicitação inválida

```json
{
  "status": 400,
  "title": "Solicitação inválida",
  "detail": "Solicitação inválida.",
  "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"
}
```

#### `413` Payload muito grande

A solicitação excede o tamanho máximo permitido. O gateway a rejeita **sem processá-la**: a resposta não inclui `serviceResultCode` nem `serviceTransactionId`. Consulte [Limite de tamanho da solicitação](https://docs.facephi.com/pages/1b12810f7c9abac00ee2fed384b12d3575d93434#l%C3%ADmite-de-tama%C3%B1o-de-la-solicitud).

Solicitação maior que 6 MB e de até 10 MB (`Content-Type: application/json`):

```json
{
  "message": "Request Too Long"
}
```

Solicitação maior que 10 MB (10.485.760 bytes) (`Content-Type: text; charset=utf-8`, texto simples, não JSON):

```
HTTP content length exceeded 10485760 bytes.
```

#### `502` Bad Gateway

```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` Timeout do gateway

```json
{
  "message": "Endpoint request timed out"
}
```
