> 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 Template Biométrico de Impressão Digital** a partir de imagens de Impressão Digital, abertas ou tokenizadas. Cada imagem se converte em um template (`template`) reutilizável no serviço de autenticação de impressão digital. {% hint style="warning" %} Tenha em conta 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 serem processadas. São permitidas de **1 a 10** impressões digitais por solicitação (configurável por tenant). | | `fingers[].position` | integer | **Sim** | Posição do dedo conforme a numeração NIST (**1–10**). Veja [Posições dos dedos](#posiciones-de-dedo). | | `fingers[].tokenBuffer` | string | **Sim** | Imagem da Impressão Digital em **Base64** ou um **token** da FacePhi. Veja [Formatos aceitos](#formatos-aceptados-tokenbuffer). | | `fingers[].dpi` | integer | Não | Resolução da imagem em pontos por polegada. Se omitida, é usado o valor padrão do tenant (500). | | `fingers[].scanType` | string | Não | Tipo de captura (`Plain` padrão). Veja [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` suporta 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 suportados pelo motor: | Formato | Descrição | | ------- | -------------------------------------------------------------------------------------------------- | | `WSQ` | Wavelet Scalar Quantization (padrão de Impressão Digital; formato habitual dos widgets de captura) | | `BMP` | Bitmap | | `PNG` | Portable Network Graphics | | `JPEG` | JPEG | | `JP2` | JPEG 2000 (contêiner `.jp2` ou codestream) | **Codificação**: 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 de uma única linha**. #### Tipos de captura (scanType) | Valor | Descrição | Suporte (Versão atual) | | -------- | -------------------------------------------------------- | ------------------------------------------ | | `Plain` | Captura plana / ao vivo (dedo apoiado plano) | **Suportado** (valor padrão) | | `Rolled` | Captura rodada (o dedo é rolado de um lado para o outro) | Requer uma imagem capturada no modo rodado | | `Latent` | Impressão Digital latente / forense | Requer uma imagem latente | * Se omitido, usa-se `Plain`. * O `scanType` deve corresponder ao tipo de imagem enviada. Para a captura padrão de Onboarding (incluída a do Widget) usar **`Plain`**. * Se o motor 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 motor (por ex. `"Falha na criação do template do dedo"`), não um `502`. #### Exemplo de solicitação ```json { "fingers": [ { "position": 2, "tokenBuffer": "Rk1SACAyMAAAAAEgAAABPAFiAMUAxQEAAAAo...", "dpi": 500, "scanType": "Plain" } ] } ``` ### 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 total de processamento **(milissegundos)**. | | `serviceTransactionId` | string | Identificador de transação associado à solicitação processada pela API. | | `templates` | array | Lista de templates extraídos, um por cada Impressão Digital enviada. Veja [Campos do template](#campos-de-la-plantilla). | #### Campos do template | Campo | Tipo | Descrição | | ---------------- | ------- | ---------------------------------------------------------------------------------------------- | | `position` | integer | Posição do dedo (1–10) correspondente ao template. | | `template` | string | Template Biométrico extraído, codificado em Base64. Reutilizável em `authenticateFingerprint`. | | `overallQuality` | integer | Qualidade geral da Impressão Digital. | | `nfiq2` | number | Pontuação de qualidade **NFIQ 2.0**. | | `nfiq` | number | Pontuação de qualidade **NFIQ**. | | `quality` | number | Pontuação de qualidade do motor biométrico. | | `dpi` | integer | Resolução utilizada 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` 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" } ```