> 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 digital de **probe** contra uma impressão digital de **gallery** da mesma posição. Cada lado pode ser fornecido como **imagem aberta/tokenizada** ou como **Template Biométrico** previamente extraída com [Fingerprint Extraction](/docs.facephi-pt-br/api-rest/identity-api/identity-api-reference/shared-biometric-components/fingerprint-extraction.md), sendo permitida 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**. Requerido 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 digital de referência. Deve conter **exatamente um** elemento. | | `gallery` | array | **Sim** | Impressão digital 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 de acordo com 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 não for enviado `template`. Ver [Formatos aceitos](#formatos-aceptados). | | `probe[].template` / `gallery[].template` | string | Condicional | Template Biométrico (Base64) obtida de `extractFingerprint`. Obrigatório se não for enviado `tokenBuffer`. Ver [Formatos aceitos](#formatos-aceptados). | | `threshold` | integer | Não | Limiar de decisão. Se for omitido, usa-se o valor do tenant ou o do motor biométrico. | | `Tracking` | object | Não | Objeto que representa a informação de Tracking necessária. | | `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). * **Codificação**: base64 padrão, preferencialmente **sem quebras de linha**. Se chegar "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 por meio de duas **imagens** | probe: imagem, gallery: imagem | | **2** | Autenticação por meio de duas **Templates Biométricos** | probe: template, gallery: template | | **3** | Autenticação por meio de uma **imagem** e uma **modelo** | probe: imagem, gallery: template | | **4** | Autenticação por meio de 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. Ver [Service Result Code](#service-result-code). | | `serviceResultLog` | string | Campo descritivo do resultado da execução do serviço. | | `serviceTime` | string | Tempo total de processamento **(milissegundos)**. | | `serviceTransactionId` | string | Identificador de transação associado à solicitação processada pela API. | | `serviceFingerprintAuthStatus` | string | Resultado da correspondência. Ver [Status de Autenticação da Impressão Digital](#fingerprint-auth-status). | | `serviceFingerprintScore` | number | Pontuação de similaridade entre as duas impressões digitais comparadas. | | `serviceFingerprintThreshold` | number | Limiar de decisão aplicado na comparação. | #### Service Result Code | 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 pôde concluir a comparação (entrada não processável). | 200 | #### Status de Autenticação da Impressão Digital | Status | 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` Bad Request ```json { "status": 400, "title": "Requisiçã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": "Não autorizado" } ``` #### `403` Proibido ```json { "Message": "O usuário não está autorizado a acessar este recurso com uma negação explícita" } ``` #### `502` Bad Gateway ```json { "status": 502, "title": "Gateway inválido", "detail": "O servidor recebeu uma resposta inválida.", "type": "https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/502" } ``` #### `504` Gateway Timeout ```json { "message": "A requisição do Endpoint excedeu o tempo limite" } ```