> 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 exigidos | ## Restrições de runtime e compilação * Arquitetura compatível: x86\_64 * Sistema operacional de destino 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 de Facephi Características: * Não é armazenado estado de sessão 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 escalonamento horizontal atrá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 Do maior para o menor nível de 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, Timeout, 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, Timeout de conexão/requisição, retries, 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ó mestre * 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 requer 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 utilizados pelo serviço são `FingerExtractCounter` e `FingerAuthenticateCounter`. * `totalCount` é calculado como `extractCount + authenticateCount`. ## Considerações de desempenho | Dimensão | Guia | | ----------------------- | ----------------------------------------------------------------- | | Desempenho (throughput) | Escala com a capacidade do engine e o tamanho do pool de conexões | | Latência | Afetada pelo Timeout 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 requerer 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, garanta 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 API gateway. * Restrinja o acesso de entrada a redes confiáveis. * Use terminação TLS na gateway 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, use 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 de campo internos não são expostos nas respostas públicas. * Os payloads dos endpoints de gestão são estáveis e estão documentados no OpenAPI.