> 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/sdks/backend-sdk/finger.md). # Finger Service 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: ```json { "image": "", "position": "RightIndex", "options": { "dpi": 500, "scanType": "Plain", "includeQuality": true } } ``` Resposta: ```json { "fingerTemplate": "", "position": "RightIndex", "scanType": "Plain", "quality": 88, "qualityDetails": { "nfiq2": 79.0, "nfiq": 1.0, "score": 88.0 }, "sdkDuration": 123, "queueDuration": 2 } ``` ### Métricas Resposta: ```json { "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: ```json { "fingerTemplate1": "", "fingerTemplate2": "", "position": "RightIndex", "options": { "authThreshold": 20 } } ``` Requisição usando imagens: ```json { "image1": "", "image2": "", "position": "RightIndex", "options": { "authThreshold": 20 } } ``` Resposta: ```json { "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 ```bash 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 ```bash curl http://localhost:6982/api/v1/finger/health curl http://localhost:6982/api/v1/finger/version ``` Respostas típicas: ```json { "message": "Healthy" } ``` ```json { "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`: ```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](/docs.facephi-pt-br/sdks/backend-sdk/finger/installation/installation_instructions.md) * [Especificações técnicas](/docs.facephi-pt-br/sdks/backend-sdk/finger/technical_documentation/technical_specifications.md) * [Referência da API](https://github.com/facephi/facephi-gitbook-docs/tree/master/docs/sdks/backend-sdk/finger/technical_documentation/openapi.yaml) * [Registro de alterações](/docs.facephi-pt-br/sdks/backend-sdk/finger/changelog.md) ## 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.