Autenticação de 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, 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.

Todas as chamadas aos Endpoints para Tracking com Identity Platform devem conter o header family.

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

O método de comparação é derivado automaticamente do formato de probe e gallery (imagem ou template). Ver Especificação do método.

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

{
  "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.
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.
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

{
  "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

{
  "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

{
  "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

{
  "message": "Unauthorized"
}

403 Acesso negado

{
  "Message": "User is not authorized to access this resource with an explicit deny"
}

502 Gateway inválido

{
  "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

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