Documentação Técnica App + API REST - Parte 2

Gilberto Júnior

6. INTEGRAÇÕES EXTERNAS

6.1 Dispositivo QFace (Digicon/Suprema)

Item	Detalhe
Protocolo	TCP/IP proprietário (SDK C/C++)
DLL	`QFM_SDK_DLL.dll` (32-bit e 64-bit)
IP padrão	`172.16.110.6`
Porta padrão	`12120`
Modo	Binário (asciiMode = false)
Configuração	`config/application.json` → `deviceIp`, `devicePort`, `asciiMode`

Funções da DLL utilizadas:

Função C	Wrapper TypeScript	Descrição
`QF_InitSocket`	`initSocket()`	Conecta ao dispositivo
`QF_CloseSocket`	`closeSocket()`	Desconecta
`QF_DeleteAll`	`deleteAllTemplates()`	Remove todos os templates do device
`QF_EnrollImage`	`enrollImage(userID, imageBuffer)`	Envia imagem e gera template
`QF_ReadTemplate`	`readTemplate(userID)`	Lê template gerado
`QF_ScanTemplate`	`scanTemplate()`	Captura template via câmera do device
`QF_GetFirmwareVersion`	`getDeviceInfo()`	Lê versão de firmware
`QF_GetSysParameter`	`getDeviceInfo()`	Lê número de série e build

Pontos de atenção:

A DLL não é thread-safe → usar sempre o mutex
O dispositivo precisa estar na mesma rede local (IP acessível)
Firewall do Windows pode bloquear a porta 12120

6.2 API Externa (Webhook de saída)

Descrição simplificada (Suporte):

O sistema pode enviar automaticamente os templates gerados para um sistema externo (ERP, controle de acesso, etc.) via HTTP.

Descrição técnica:

Item	Detalhe
Configuração	`externalApiEnabled`, `externalApiUrl`, `externalApiUser`, `externalApiPassword`
Formato de payload	Configurável via `payloadTemplate` (suporta variáveis: `{{biometric_data}}`, `{{user_id}}`, `{{timestamp}}`)
Endpoints customizados	`apiEndpoints` (JSON com lista de endpoints)
Backup	Registros mantidos por `backupRegistersDays` dias (padrão: 7)

6.3 Windows Service Manager (NSSM)

Item	Detalhe
Ferramenta	NSSM v2.24 (Non-Sucking Service Manager)
Localização	`nssm/win32/` e `nssm/win64/`
Uso	Registra `insoft-qface-win-api.exe` como serviço do Windows
Nome do serviço	`insoft-qface-win-api` (padrão)
Variáveis de ambiente	`CONFIG_PATH`, `QFACE_DLL_PATH`, `SHARED_I18N_PATH` configuradas no serviço

7. TRATAMENTO DE ERROS E EXCEÇÕES

Sistema de Logs

Aplicativo Electron (`insoft-qface-app`)

Aspecto	Detalhe
Biblioteca	`electron-log`
Arquivo de log	`<cwd>/logs/AppLog.log`
Níveis	`info`, `warn`, `error`, `debug`
Acesso	Dashboard → aba Logs → "Ver Logs"

API Windows (`insoft-qface-win-api`)

Aspecto	Detalhe
Arquivo de log	`<exeDir>/logs/AppLog.log`
Log de serviço	`<exeDir>/logs/service.log`
Log de erros	`<exeDir>/logs/error.log`
HTTP Requests	Morgan (`combined` format) no console

Proteção contra crashes

O sistema possui handlers globais para evitar que erros inesperados derrubem o aplicativo:

// No Electron (main.ts) e na API (start.ts / server/index.ts)
process.on('uncaughtException', (error) => {
  logger.error('Uncaught Exception:', error);
  // NÃO encerra o processo — mantém o app rodando
});

process.on('unhandledRejection', (reason) => {
  logger.error('Unhandled Rejection:', reason);
  // NÃO encerra o processo
});

Códigos de mensagem de erro

Todos os erros retornados pela API usam o sistema de mensagens codificadas (repp.message.X). A tabela completa está em shared/i18n/en-US.json e shared/i18n/pt-BR.json.

Erros mais comuns em produção:

Código	Constante	Mensagem (PT-BR)	Causa
`repp.message.24`	`FAILED_CONNECT_DEVICE`	Falha ao conectar no dispositivo	IP/porta errado ou dispositivo offline
`repp.message.55`	`API_WINDOWS_SERVICE_NOT_INSTALLED`	Serviço Windows não instalado	API não foi instalada como serviço
`repp.message.31`	`CAPTURE_TIMEOUT`	Timeout na captura	Usuário não posicionou rosto a tempo
`repp.message.27`	`INVALID_IMAGE`	Imagem inválida	Imagem não contém face detectável
`repp.message.43`	`TEMPLATE_SCAN_FAILED`	Falha na captura do template	Câmera do QFace com problema

🧪 8. CENÁRIOS COMUNS DE SUPORTE

Problema 1: "API não está rodando" / Dashboard mostra serviço parado

Sintoma: Status da API aparece como "Parado" ou "Não instalado" na tela do Dashboard.

Possíveis causas:

O serviço insoft-qface-win-api não está instalado
O serviço foi interrompido manualmente
Alguma atualização removeu o serviço

Como investigar:

Abrir o Gerenciador de Serviços do Windows (services.msc)
Procurar por Insoft QFace Win API
Verificar logs: <pasta_instalação>\logs\service.log

Como resolver:

Se o serviço não existe: usar o botão "Instalar Serviço" no Dashboard
Se o serviço existe mas está parado: clicar em "Iniciar" no Dashboard ou no services.msc
Se há erro: verificar error.log para detalhes

Problema 2: Falha ao conectar no dispositivo QFace

Sintoma: Erros de conversão com mensagem repp.message.24 ou "Falha ao conectar no dispositivo".

Possíveis causas:

Dispositivo QFace desligado ou sem energia
IP ou porta errada na configuração
Firewall bloqueando a porta 12120
Dispositivo em outra sub-rede

Como investigar:

Verificar se o dispositivo está ligado (LEDs acesos)
Testar ping para o IP configurado: ping 172.16.110.6
Verificar config/application.json → campos deviceIp e devicePort
Verificar log: procurar por [QFace SDK] ou QF_ERR_CANNOT_CONNECT_SOCKET

Como resolver:

Corrigir IP/porta nas Configurações do aplicativo
Verificar regras do Firewall do Windows para porta 12120
Confirmar que o dispositivo e o PC estão na mesma rede

Problema 3: Imagens não geram template (qualidade ruim)

Sintoma: Retorno com error: repp.message.27 (imagem inválida) ou qualidade muito baixa.

Possíveis causas:

Imagem não contém rosto humano reconhecível
Resolução da imagem muito baixa
Imagem com iluminação inadequada (muito escura, muito clara, contra-luz)
Formato de imagem incompatível

Como investigar:

Verificar o campo quality no retorno (valores abaixo de 40 indicam baixa qualidade)
Revisar logs da API: [biometricTemplateController] → enrollImage result

Como resolver:

Garantir imagens com rosto frontal, bem iluminado, mínimo 200x200 pixels
Verificar que o formato é JPEG ou PNG

Problema 4: Câmera não funciona para captura ao vivo

Sintoma: Tela de captura abre mas câmera não inicializa ou mostra tela preta.

Possíveis causas:

Permissão de câmera negada no Windows
Driver da câmera do QFace não instalado
Outro aplicativo está usando a câmera

Como investigar:

Verificar Configurações do Windows → Privacidade → Câmera
O aplicativo possui botão "Abrir Configurações de Câmera" nas Configurações
Verificar log: [useCamera] ou [QFace SDK]

Como resolver:

Ativar permissão de câmera para o aplicativo
Reinstalar drivers do dispositivo QFace
Fechar outros aplicativos que possam estar usando a câmera

Problema 5: WebSocket desconectado — eventos não chegam à interface

Sintoma: A tela de conversão não atualiza, ou a captura não é iniciada apesar da requisição ter chegado à API.

Possíveis causas:

API rodando mas porta 3133 bloqueada por firewall
API reiniciou mas WebSocket do Electron ainda não reconectou

Como investigar:

Verificar log do Electron: procurar por [WebSocket]
Verificar se o serviço da API está rodando (porta 3133)

Como resolver:

Reiniciar a API pelo Dashboard (botão "Reiniciar API")
O WebSocket reconecta automaticamente em até 5 segundos

Problema 6: Erro de permissão / instalação de serviço falha

Sintoma: Botão "Instalar Serviço" retorna erro de permissão.

Possíveis causas:

Aplicativo não está rodando como Administrador
Antivírus bloqueando criação de serviço

Como resolver:

Fechar e reabrir o aplicativo com "Executar como Administrador" (o instalador já solicita isso automaticamente)
Adicionar exceção no antivírus para nssm.exe e insoft-qface-win-api.exe

9. BOAS PRÁTICAS E OBSERVAÇÕES

Padrões utilizados no código

Padrão	Onde é usado	Motivo
Mutex assíncrono	`QFaceMutex` na API	DLL não é thread-safe
IPC com Context Bridge	`preload.ts`	Segurança Electron: isola renderer do Node.js
Mensagens codificadas	Todo o sistema (MSG.XXX)	Internacionalização e rastreabilidade
Polling de saúde	`startApiServer()`	Garante que a API está realmente respondendo antes de sinalizar como ready
Fila de eventos	`EventQueue`	Evita perda de eventos se Electron conectar depois da API emitir
Context API React	`ConfigContext`, `ThemeContext`	Evita prop drilling e centraliza estado global
Reconexão WebSocket	`reconnectionAttempts: Infinity`	Alta disponibilidade da comunicação em tempo real

Cuidados ao modificar o sistema

️ DLL nativa (`QFM_SDK_DLL.dll`)

NUNCA fazer chamadas concorrentes à DLL sem usar o qfaceMutex
A DLL é 32-bit em alguns ambientes — verificar compatibilidade do processo
Alterações nas assinaturas de função precisam ser sincronizadas com qface-sdk.ts

️ Arquivo `application.json`

É o único ponto de configuração compartilhado entre Electron e API
Tanto o Electron (main.ts) quanto a API (configManager.ts) leem este arquivo
Ao salvar configurações pela UI, o Electron atualiza o arquivo e notifica a API via HTTP (/internal/config/update)
Em produção, o arquivo fica na pasta do instalador, NÃO dentro do ASAR

️ Mensagens i18n

Nunca usar strings literais de erro — sempre usar MSG.NOME_DA_CONSTANTE
Ao adicionar nova mensagem: adicionar em message-codes.json, en-US.json E pt-BR.json
Executar npm run validate:i18n para verificar consistência

️ Gerenciamento de janela

A função bringWindowToFront() usa sequência específica para garantir que a janela apareça acima de outros aplicativos no Windows
O setTimeout(180ms) é intencional para estabilizar o foco após setAlwaysOnTop

️ Build e empacotamento

O electron-builder.json define que o instalador exige privilégios de Administrador (requireAdministrator)
A API .exe é copiada para build-api/ antes do build do Electron
O NSSM é incluído para ambas as arquiteturas (win32/win64) e selecionado automaticamente

Portas utilizadas pelo sistema

Porta	Protocolo	Serviço	Configurável?
`3333`	HTTP	API REST principal	Sim (`serverPort` no config)
`3133`	HTTP/WebSocket	Socket.IO (eventos em tempo real)	Não (fixo no código)
`12120`	TCP	Dispositivo QFace	Sim (`devicePort` no config)
`4443`	HTTPS	API REST (modo SSL)	Não (fixo, fallback)

Estrutura do `application.json` (referência completa)

{
  "deviceIp": "172.16.110.6",       // IP do dispositivo QFace
  "devicePort": 12120,               // Porta TCP do dispositivo
  "asciiMode": false,                // Protocolo binário (false) ou ASCII (true)
  "apiKey": "<uuid>",                // Chave de autenticação da API REST
  "useSsl": false,                   // Habilitar HTTPS na API
  "certFiles": null,                 // Caminho dos arquivos de certificado SSL
  "useCertificate": false,           // Usar certificado SSL customizado
  "backgroundMode": true,            // API roda em segundo plano
  "saveTemplates": true,             // Salvar templates em disco
  "saveImages": true,                // Salvar imagens em disco
  "serverIp": "localhost",           // IP de escuta da API REST
  "serverPort": 3333,                // Porta HTTP da API REST
  "theme": "dark",                   // Tema da UI: "dark" | "light"
  "qfaceCapture": true,              // Habilitar captura via câmera QFace
  "externalApiEnabled": false,       // Enviar templates para API externa
  "externalApiUrl": "",              // URL da API externa
  "externalApiUser": "",             // Usuário da API externa
  "externalApiPassword": "",         // Senha da API externa
  "apiEndpoints": "[]",              // Endpoints customizados (JSON)
  "payloadTemplate": "...",          // Template do payload de saída
  "backupRegistersDays": 7           // Dias de retenção de registros
}

Documentação gerada em Abril de 2026 — Insoft4 Informática LTDA

Documentação Técnica App + API REST - Parte 2

6. INTEGRAÇÕES EXTERNAS

6.1 Dispositivo QFace (Digicon/Suprema)

6.2 API Externa (Webhook de saída)

6.3 Windows Service Manager (NSSM)

7. TRATAMENTO DE ERROS E EXCEÇÕES

Sistema de Logs

Aplicativo Electron (insoft-qface-app)

API Windows (insoft-qface-win-api)

Proteção contra crashes

Códigos de mensagem de erro

🧪 8. CENÁRIOS COMUNS DE SUPORTE

Problema 1: "API não está rodando" / Dashboard mostra serviço parado

Problema 2: Falha ao conectar no dispositivo QFace

Problema 3: Imagens não geram template (qualidade ruim)

Problema 4: Câmera não funciona para captura ao vivo

Problema 5: WebSocket desconectado — eventos não chegam à interface

Problema 6: Erro de permissão / instalação de serviço falha

9. BOAS PRÁTICAS E OBSERVAÇÕES

Padrões utilizados no código

Cuidados ao modificar o sistema

️ DLL nativa (QFM_SDK_DLL.dll)

️ Arquivo application.json

️ Mensagens i18n

️ Gerenciamento de janela

️ Build e empacotamento

Portas utilizadas pelo sistema

Estrutura do application.json (referência completa)

Aplicativo Electron (`insoft-qface-app`)

API Windows (`insoft-qface-win-api`)

️ DLL nativa (`QFM_SDK_DLL.dll`)

️ Arquivo `application.json`

Estrutura do `application.json` (referência completa)