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.

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.

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.
fingers[].tokenBuffer	string	Sim	Imagem da Impressão Digital em Base64 ou um token da FacePhi. Veja Formatos aceitos.
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.

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

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

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

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

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

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