> 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/technical_documentation/technical_specifications.md). # Especificações técnicas ## Aviso de compatibilidade IMPORTANTE - ALTERAÇÃO INCOMPATÍVEL (BREAKING CHANGE) (2.0.0) O contrato de payload REST para as operações de Impressão Digital mudou na versão 2.0.0 e não é compatível com os payloads de cliente 1.x.x. ## Requisitos mínimos | Componente | Requisito | | ---------- | -------------------- | | SO | Linux x86\_64 | | CPU | 4 núcleos | | Memória | 4 GB de RAM | | Disco | 2 GB de espaço livre | ## Recomendado para produção | Componente | Recomendação | | ------------- | ------------------------------------------------------------------------------------------------- | | SO | Ubuntu LTS | | CPU | 8 ou mais núcleos | | Memória | 8 GB ou mais de RAM | | Armazenamento | SSD para logs e camadas do contêiner | | Rede | Conectividade de baixa latência com os serviços de processamento de Impressão Digital necessários | ## Restrições de runtime e compilação * Arquitetura compatível: x86\_64 * Sistema operacional alvo compatível: Linux * Runtime base do contêiner: Ubuntu 20.04 ## Arquitetura do serviço O serviço atua como uma camada de adaptação de API Rest sem estado: Aplicação cliente -> Facephi Finger Service -> Processamento de Impressão Digital da Facephi Características: * Nenhum estado de sessão é armazenado na camada de API * As requisições públicas são validadas e normalizadas antes de serem processadas * As respostas de processamento são traduzidas de volta para o contrato público * Adequado para escalabilidade horizontal por trás de um balanceador de carga ## Disponibilidade de endpoints por função | Função | Endpoints | | -------- | ------------------------------------------------------------------- | | `master` | `extract`, `authenticate`, `health`, `version`, `metrics`, `config` | | `worker` | `health`, `version`, `metrics`, `config` | ## Formatos de imagem suportados (endpoints públicos de Impressão Digital) Para requisições baseadas em imagem em: * `POST /api/v1/finger/extract` (`image`) * `POST /api/v1/finger/authenticate` (`image1`, `image2`) os formatos de imagem de Impressão Digital suportados são: * `wsq` * `bmp` * `png` * `jpg` * `jp2` ## Modelo de configuração ### Ordem de precedência Da maior para a menor prioridade: 1. Variáveis de ambiente 2. `config.json` 3. Valores padrão do serviço ### Grupos de configuração em tempo de execução * Configurações do gerenciador REST: porta de escuta, threads, tempo limite, tamanho do body, logging * Configurações de autenticação REST: habilitação de JWT, segredo HS256, cabeçalhos de token aceitos * Configurações de processamento: URL, tempo limite de conexão/requisição, tentativas, tamanho do pool, verificação SSL * Configurações de topologia: função (`master`/`worker`), lista de serviços de processamento, endereço de descoberta do nó master * Contadores de uso de licença: habilitados por meio da chave de metadados de licença `ActivateUsageCounters` As configurações de autenticação JWT são aplicadas durante a inicialização do serviço. Alterá-las exige reiniciar o serviço. ## Contadores de uso * `GET /api/v1/finger/metrics` expõe os contadores de uso das operações `extract` e `authenticate` concluídas com sucesso. * Os campos da resposta são: `usageCountersEnabled`, `extractCount`, `authenticateCount`, `totalCount`. * Os atributos de medição de licença usados pelo serviço são `FingerExtractCounter` e `FingerAuthenticateCounter`. * `totalCount` é calculado como `extractCount + authenticateCount`. ## Considerações de desempenho | Dimensão | Guia | | ----------------------- | --------------------------------------------------------------------------- | | Desempenho (throughput) | Escala de acordo com a capacidade do engine e o tamanho do pool de conexões | | Latência | Afetada pelo tempo limite de requisição do engine e pelas tentativas | | Concorrência | Influenciada por `number_of_threads` e `engine_pool_size` | | Tamanho do payload | Controlado por `client_max_body_size` | ## Notas operacionais * Durante a inicialização do contêiner, os serviços de processamento podem exigir um tempo de aquecimento. * As verificações de saúde validam o contexto do serviço, a licença e a disponibilidade do processamento. * Em implantações orientadas a cluster, assegure uma configuração de descoberta consistente entre os nós. ## Recomendações de segurança * Implante atrás de um proxy reverso ou de uma gateway de API. * Restrinja o acesso de entrada a redes confiáveis. * Use terminação TLS na gateway de API ou no balanceador de carga. * Proteja os arquivos de licença e configuração montados com permissões de privilégio mínimo. * Mantenha `auth_jwt_secret` em um cofre de segredos ou injetado como variável de ambiente em vez de incluí-lo diretamente nas imagens. * Quando JWT estiver habilitado, utilize tokens HS256 com um claim `exp` válido e proteja todos os endpoints não públicos. * Habilite a verificação SSL para a comunicação com o backend de processamento quando a infraestrutura permitir. Os endpoints públicos que permanecem sem autenticação são `GET /api/v1/finger/health`, `GET /api/v1/finger/version` e as solicitações de preflight `OPTIONS`. ## Logging e monitoramento Use estes endpoints para verificações de disponibilidade (liveness): * `GET /api/v1/finger/health` * `GET /api/v1/finger/version` * `GET /api/v1/finger/metrics` Configure os logs com: * `logger_level` * `logger_path` * `logger_rotation` * `logger_max_files` ## Notas de compatibilidade * Os payloads da API para operações de Impressão Digital utilizam o contrato público 2.0.0. * Os nomes internos dos campos não são expostos nas respostas públicas. * Os payloads dos endpoints de gerenciamento são estáveis e estão documentados em OpenAPI.