> 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/authenticate-fingerprint.md). # Autenticar impressão digital Serviço que realiza a **Verificação Biométrica de Impressão Digital 1:1**, comparando uma impressão de **probe** contra uma impressão de **gallery** da mesma posição. Cada lado pode ser fornecido como **imagem aberta/tokenizada** ou como **Template Biométrico** previamente extraído com [Fingerprint Extraction](/docs.facephi-pt-br/api-rest/identity-api/identity-api-reference/shared-biometric-components/fingerprint-extraction.md), admitindo-se a combinação de ambos os formatos. ### Endpoint ``` POST /services/authenticateFingerprint ``` ### 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 header `family`. {% endhint %} ### Corpo da solicitação **Content-Type:** `application/json` #### Parâmetros | Parâmetro | Tipo | Obrigatório | Descrição | | ----------------------------------------------- | ------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `probe` | array | **Sim** | Impressão de referência. Deve conter **exatamente um** elemento. | | `gallery` | array | **Sim** | Impressão de comparação. Deve conter **exatamente um** elemento, da **mesma posição** que o `probe`. | | `probe[].position` / `gallery[].position` | integer | **Sim** | Posição do dedo segundo a numeração NIST (**1–10**). Deve coincidir entre `probe` e `gallery`. | | `probe[].tokenBuffer` / `gallery[].tokenBuffer` | string | Condicional | Imagem da Impressão Digital em **Base64** ou um **token** da FacePhi. Obrigatório se tokenBuffer não for enviado `template`. Ver [Formatos aceitos](#formatos-aceptados). | | `probe[].template` / `gallery[].template` | string | Condicional | Template Biométrico (Base64) obtido de `extractFingerprint`. Obrigatório se tokenBuffer não for enviado `tokenBuffer`. Ver [Formatos aceitos](#formatos-aceptados). | | `threshold` | integer | Não | Limite de decisão. Se omitido, é usado o valor do tenant ou o do motor biométrico. | | `rastreamento` | 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. | {% hint style="info" %} O método de comparação é derivado automaticamente do formato de `probe` e `gallery` (imagem ou template). Ver [Especificação do método](#especificación-de-método). {% endhint %} #### Formatos aceitos * **Imagem** (`tokenBuffer`): Base64 de uma imagem de Impressão Digital em `WSQ`, `BMP`, `PNG`, `JPEG` ou `JP2`, ou um **token** da FacePhi. * **Template** (`template`): o `template` em Base64 retornado por [`extractFingerprint`](/docs.facephi-pt-br/api-rest/identity-api/identity-api-reference/shared-biometric-components/fingerprint-extraction.md) (impressão digital já convertida para Template Biométrico). * **Encoding**: base64 padrão, preferencialmente **sem quebras de linha**. Se chegar como "wrapped" (quebras CRLF), o serviço o normaliza antes de processá-lo. #### Especificação do método | Método | Descrição | Entrada | | ------ | ----------------------------------------------------- | ---------------------------------- | | **1** | Autenticação mediante duas **imagens** | probe: imagem, gallery: imagem | | **2** | Autenticação mediante duas **Templates Biométricos** | probe: template, gallery: template | | **3** | Autenticação mediante uma **imagem** e uma **modelo** | probe: imagem, gallery: template | | **4** | Autenticação mediante uma **modelo** e uma **imagem** | probe: template, gallery: imagem | #### Exemplo de solicitação ```json { "probe": [ { "position": 2, "tokenBuffer": "Rk1SACAyMAAAAAEgAAABPAFiAMUAxQEAAAAo..." } ], "gallery": [ { "position": 2, "template": "Rk1SACAyMAAAAAD6AAABPAFiAMUAxQEAAAA..." } ], "threshold": 40, "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. Veja [Código de Resultado do Serviço](#service-result-code). | | `serviceResultLog` | string | Campo descritivo do resultado da execução do serviço. | | `serviceTime` | string | Tempo total de processamento **(milisegundos)**. | | `serviceTransactionId` | string | Identificador da transação associado à solicitação processada pela API. | | `serviceFingerprintAuthStatus` | string | Resultado da correspondência. Ver [Fingerprint Auth Status](#fingerprint-auth-status). | | `serviceFingerprintScore` | number | Pontuação de similaridade entre as duas impressões digitais comparadas. | | `serviceFingerprintThreshold` | number | Limite de decisão aplicado na comparação. | #### Código de Resultado 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 | | -1 | O motor biométrico não conseguiu concluir a comparação (entrada não processável). | 200 | #### Fingerprint Auth Status | Estado | Descrição | | ---------- | ----------------------------------------------------------------------------------------------------- | | `MATCH` | A comparação é positiva: as impressões digitais coincidem. | | `NO_MATCH` | O processo foi executado corretamente, mas as impressões digitais não coincidem. | | `ERROR` | Não foi possível realizar a comparação (por exemplo, entrada inválida ou não processável pelo motor). | #### Exemplo de resposta: MATCH ```json { "serviceResultCode": 0, "serviceResultLog": "match", "serviceTime": "318", "serviceTransactionId": "a29cbe15-2b68-495f-b7eb-be985b21c486", "serviceFingerprintAuthStatus": "MATCH", "serviceFingerprintScore": 62.00000000, "serviceFingerprintThreshold": 40.00000000 } ``` #### Exemplo de resposta: NO\_MATCH ```json { "serviceResultCode": 0, "serviceResultLog": "no_match", "serviceTime": "305", "serviceTransactionId": "e96e85a4-3f94-4000-b639-15c4f18c345b", "serviceFingerprintAuthStatus": "NO_MATCH", "serviceFingerprintScore": 12.00000000, "serviceFingerprintThreshold": 40.00000000 } ``` #### `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` Acesso negado ```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` Tempo limite do gateway ```json { "message": "Endpoint request timed out" } ```