Serviço Finger

API REST de Impressão Digital para a extração de templates e a autenticação 1:1.

Aviso importante de compatibilidade

IMPORTANTE - MUDANÇA INCOMPATÍVEL (BREAKING CHANGE) (2.0.0)

A partir da versão 2.0.0, os endpoints de operações de Impressão Digital não são compatíveis com a versão 1.x.x:

• POST /api/v1/finger/extract

• POST /api/v1/finger/authenticate

As rotas públicas herdadas POST /api/v1/finger/create-template e POST /api/v1/finger/verify não estão disponíveis na versão 2.0.0.

Os formatos de payload da requisição e da resposta mudaram. As integrações criadas para a versão 1.x.x devem migrar para o contrato público 2.0.0 antes de atualizar.

Visão geral

Facephi Finger Service expõe uma API pública sob /api/v1/finger/ com nomes de campo voltados para Impressão Digital como image, position, fingerTemplate, authStatus e similarity.

Opcionalmente, os endpoints públicos de Impressão Digital e de gerenciamento podem ser protegidos por autenticação JWT. Ela é configurada na inicialização do serviço a partir de config.json ou das variáveis de ambiente FACEPHI_FINGER_REST_*.

Para as requisições que incluem imagens de Impressão Digital (image, image1, image2), os formatos suportados são wsq, bmp, png, jpg e jp2.

O serviço fornece:

• Extração de templates de Impressão Digital

• Autenticação 1:1 de Impressão Digital

• Contadores de uso por meio de GET /api/v1/finger/metrics

• Endpoints de saúde, versão e configuração em tempo de execução

Contrato público

Extrair

Formatos de imagem suportados para image: wsq, bmp, png, jpg, jp2.

Requisição:

{
  "image": "<base64_fingerprint_image>",
  "position": "RightIndex",
  "options": {
    "dpi": 500,
    "scanType": "Plain",
    "includeQuality": true
  }
}

Resposta:

{
  "fingerTemplate": "<base64_generated_template>",
  "position": "RightIndex",
  "scanType": "Plain",
  "quality": 88,
  "qualityDetails": {
    "nfiq2": 79.0,
    "nfiq": 1.0,
    "score": 88.0
  },
  "sdkDuration": 123,
  "queueDuration": 2
}

Métricas

Resposta:

{
  "usageCountersEnabled": true,
  "extractCount": 12,
  "authenticateCount": 7,
  "totalCount": 19
}

Notas:

• usageCountersEnabled depende da chave de metadados de licença ActivateUsageCounters.

• extractCount e authenticateCount correspondem aos atributos de medição de licença FingerExtractCounter e FingerAuthenticateCounter.

• totalCount é calculado como extractCount + authenticateCount.

Autenticar

Formatos de imagem suportados para image1 e image2: wsq, bmp, png, jpg, jp2.

Requisição usando templates:

{
  "fingerTemplate1": "<base64_probe_template>",
  "fingerTemplate2": "<base64_gallery_template>",
  "position": "RightIndex",
  "options": {
    "authThreshold": 20
  }
}

Requisição usando imagens:

{
  "image1": "<base64_probe_image>",
  "image2": "<base64_gallery_image>",
  "position": "RightIndex",
  "options": {
    "authThreshold": 20
  }
}

Resposta:

{
  "authStatus": "Positive",
  "similarity": 84.65,
  "sdkDuration": 131,
  "queueDuration": 1
}

Endpoints da API

Endpoint	Método	Propósito
/api/v1/finger/extract	POST	Extrai uma template de Impressão Digital a partir de um payload público
/api/v1/finger/authenticate	POST	Executa a autenticação pública 1:1 de Impressão Digital
/api/v1/finger/metrics	GET	Obtém o relatório dos contadores de uso
/api/v1/finger/version	GET	Versão do serviço e estado da licença
/api/v1/finger/health	GET	Verificação de saúde e disponibilidade do serviço
/api/v1/finger/config	GET/POST	Obtém ou atualiza a configuração em tempo de execução

Início rápido

Requisitos

Componente	Requisito
SO	Linux x86_64
Tempo de execução	Docker é recomendado
Licença	Arquivo de licença Facephi válido

Implantação com Docker

docker run -d \\
  -p 6982:6982 \\
  -v /path/to/license:/app/license \\
  -v /path/to/config:/app/config \\
  --name finger-service \\
  facephicorp.jfrog.io/docker-pro-fphi/facephi-finger-service:2.1.0

Verificar a implantação

curl http://localhost:6982/api/v1/finger/health
curl http://localhost:6982/api/v1/finger/version

Respostas típicas:

{ "message": "Healthy" }

{ "message": "2.1.0 Copyright (c) 2026 FacePhi Biometria. All rights reserved." }

Quando a autenticação JWT está habilitada, health e version permanecem públicos, enquanto os endpoints protegidos requerem um JWT válido.

Configuração

Crie /app/config/config.json:

{
  "port": 6982,
  "number_of_threads": 1,
  "connection_timeout": 60,
  "keep_alive_request_number": 0,
  "client_max_body_size": 100,
  "logger_level": "info",
  "logger_path": "/app/logs",
  "logger_rotation": "daily",
  "logger_max_files": 7,
  "auth_enabled": false,
  "auth_jwt_secret": "",
  "auth_accept_authorization_header": true,
  "auth_accept_api_key_header": true,
  "auth_api_key_header_name": "x-api-key",
  "engine_connection_timeout": 10000,
  "engine_request_timeout": 60000,
  "engine_max_retries": 3,
  "engine_retry_delay": 1000,
  "engine_verify_ssl": false,
  "engine_verbose": false,
  "engine_pool_size": 4,
  "engine_url": "http://localhost:8080"
}

A configuração JWT é aplicada durante a inicialização do serviço. Se você atualizar esses valores, reinicie o serviço.

Documentação

• Guia de instalação

• Especificações técnicas

• Referência da API

• Registro de alterações

Nota sobre a abstração do fornecedor

A documentação e os payloads públicos mantêm intencionalmente abstraído o runtime de processamento. As integrações devem se apoiar somente no contrato público da Facephi documentado.

Suporte

Para licenças e Suporte Técnico, entre em contato com seu representante da Facephi.