Insoft QFace App - Documentação - Parte 1

[Gilberto Júnior]

Guia do Usuário — Insoft QFace App

Versão: 1.0.0
Empresa: Insoft4 Informática LTDA
Plataforma: Windows
Data: Abril de 2026

---

1. BOAS-VINDAS

O que é o Insoft QFace App?

Bem-vindo ao Insoft QFace App! Este programa foi desenvolvido para facilitar o uso do leitor biométrico facial QFace da sua empresa.

De forma simples: ele é o painel de controle do seu leitor de reconhecimento facial. Por meio dele, você consegue:

• Cadastrar rostos de colaboradores no leitor biométrico (enviando fotos)
• Capturar fotos ao vivo usando a câmera do leitor QFace
• Monitorar em tempo real o que está acontecendo no sistema
• ️ Gerenciar o serviço que opera o leitor, sem precisar mexer no Windows manualmente

---

Para que serve no dia a dia?

Pense neste aplicativo como o gerente do seu leitor facial. Quando outro sistema da sua empresa (como um ERP, sistema de ponto eletrônico, ou controle de acesso) precisa cadastrar o rosto de um funcionário, é este aplicativo que faz toda a comunicação com o leitor e garante que tudo funcione corretamente.

---

Benefícios para você

Benefício	O que significa na prática
Tudo em um só lugar	Um programa para controlar e monitorar o leitor facial
Sem complicação	Não é necessário conhecimento técnico para o uso diário
Funcionamento em segundo plano	O sistema trabalha sozinho, você só monitora
Alertas visuais	Fica fácil saber se algo está funcionando ou com problema
Histórico de atividades	Tudo fica registrado para consulta posterior

---

2. PRIMEIROS PASSOS

Como abrir o programa

1. Procure o ícone Insoft QFace App na área de trabalho do seu computador
2. Dê um duplo clique no ícone para abrir
3. Se aparecer uma janela perguntando sobre permissões do Windows, clique em "Sim" — isso é necessário para que o programa funcione corretamente

Por que precisa de permissão de administrador? O programa precisa gerenciar um serviço do Windows (como um antivírus), o que requer esse nível de acesso.

---

Primeira vez abrindo o programa

Ao abrir pela primeira vez, você verá a Tela Inicial com duas opções:

┌─────────────────────────┐    ┌─────────────────────────┐
│  ⚙️  Configurar          │    │  📊 Dashboard            │
│     Aplicação           │    │                          │
│                         │    │  (disponível após        │
│  (começa aqui!)         │    │   configurar)            │
└─────────────────────────┘    └─────────────────────────┘

️ Se o botão "Configurar Aplicação" estiver piscando em amarelo, significa que há informações obrigatórias que precisam ser preenchidas antes de usar o sistema. Clique nele primeiro.

---

Configuração inicial obrigatória

Antes de usar o sistema pela primeira vez, você precisará informar:

1. Clique em "Configurar Aplicação"
2. Você será levado à tela de Configurações
3. Preencha os dados do seu dispositivo QFace (o responsável técnico da sua empresa terá essas informações):
   • Porta do dispositivo (número que identifica a conexão com o leitor)
   • IP do servidor (endereço do computador onde a API funcionará — normalmente localhost)
   • Porta do servidor (porta onde o sistema de API ficará disponível)
4. Clique em "Salvar Configurações"
5. Após salvar, clique no botão "Voltar" e depois em "Dashboard"

---

🧭 3. VISÃO GERAL DO SISTEMA

A tela principal e a navegação

Após a configuração inicial, o sistema possui uma tela principal com um menu lateral à esquerda. Esse menu é a forma de navegar entre todas as funcionalidades.

O menu lateral

O menu fica no lado esquerdo da tela. Ele pode estar recolhido (mostrando só ícones) ou expandido (mostrando os nomes). Para expandir ou recolher, clique na seta ( ‹ ) no topo do menu.

Ícone	Nome	O que é
	Dashboard	Tela principal de monitoramento
	Gestão QFace	Controla a conexão com o leitor facial
	API	Controla o "motor" do sistema
️	Configurações	Ajusta as preferências do aplicativo

---

As telas do sistema

Dashboard — A tela principal

É a primeira tela que você vê ao entrar no sistema. Ela mostra um resumo de tudo:

• Status da API — se o serviço está funcionando (Verde = Online / Vermelho = Parado)
• Dispositivo QFace — se o leitor está conectado
• Templates Convertidos — quantas conversões de fotos foram realizadas com sucesso
• Erros — quantidade de erros detectados
• Pessoas Processadas — total de pessoas cadastradas
• Preview do Log — últimas atividades registradas pelo sistema

Gestão QFace — O leitor facial

Aqui você vê as informações do leitor biométrico e pode:

• Ver se o leitor está conectado ou desconectado
• Ver o modelo, versão do firmware e número de série do equipamento
• Reconectar, testar ou desconectar o leitor manualmente

API — O motor do sistema

Esta seção tem três partes acessíveis pelo submenu:

• Gestão da API — Controla o serviço que faz o sistema funcionar (iniciar, parar, reiniciar, instalar)
• Conversão de Fotos — Mostra o progresso quando fotos estão sendo convertidas em dados biométricos
• Captura de Fotos — Mostra a tela de captura ao vivo pela câmera do leitor

️ Configurações — Preferências do sistema

Onde você ajusta todas as opções do sistema, divididas em abas:

• Geral — Tema visual (claro/escuro), porta do servidor, modo de operação
• QFace — Configurações do dispositivo (porta de conexão, captura pela câmera)
• Servidor — Configurações de rede e segurança
• Avançado — API externa, armazenamento de dados, chave de acesso
• Certificados — Gerenciamento de certificados de segurança (SSL)

---

️ 4. COMO USAR AS PRINCIPAIS FUNCIONALIDADES

Dashboard — Monitoramento em Tempo Real

O que é:

O Dashboard é o painel de controle central. Ele se atualiza automaticamente a cada 20 segundos, mostrando o estado atual de todo o sistema sem que você precise fazer nada.

️ Como usar:

1. Clique em "Dashboard" no menu lateral
2. Observe os cartões coloridos no topo — eles mostram os status mais importantes
3. Para ver os logs completos, clique na área de "Preview do Log" (a caixa com texto cinza na parte inferior)
4. Na janela de logs, use os botões de arquivos à esquerda para ver logs de datas diferentes
5. Para fechar os logs, clique no "X" no canto da janela

Dicas úteis:

• Um badge Verde "Online" no cartão "Status da API" significa que tudo está funcionando
• Um badge Vermelho "Parado" indica que o serviço precisa ser iniciado — vá para Gestão da API
• O número de "Erros" não necessariamente indica um problema grave; consulte os logs para entender
• Clicar no cartão "Status da API" leva direto para a tela de Gestão da API
• Clicar no cartão "Dispositivo QFace" leva direto para a tela de Gestão QFace

---

Gestão da API — Controlando o Serviço

O que é:

A "API" é o programa que fica rodando em segundo plano e faz toda a comunicação com o leitor biométrico. Sem ela, o sistema não funciona. Esta tela permite que você a instale, inicie, pare e reinicie.

️ Como instalar o serviço (primeira vez):

1. Clique em "API" no menu lateral
2. Clique em "Gestão da API" no submenu
3. Se aparecer o botão " Instalar Serviço Windows", clique nele
4. Aguarde a mensagem de confirmação: "O serviço da API foi instalado com sucesso"
5. Clique em "OK"

Por que instalar como serviço? Quando instalado como serviço Windows, a API inicia automaticamente toda vez que o computador ligar, mesmo sem abrir o aplicativo. É como configurar um antivírus para iniciar com o Windows.

️ Como iniciar a API:

1. Acesse API → Gestão da API
2. Verifique se o status mostra " Parado"
3. Clique no botão verde " Iniciar"
4. Aguarde a confirmação: "A API foi iniciada com sucesso"

️ Como parar a API:

1. Acesse API → Gestão da API
2. Clique no botão vermelho " Parar"
3. Uma janela de confirmação aparecerá perguntando se você tem certeza
4. Clique em "Parar" para confirmar

️ Atenção: Parar a API interrompe todas as conversões de fotos e capturas em andamento. Só faça isso se necessário.

️ Como reiniciar a API:

1. Acesse API → Gestão da API
2. Clique no botão " Reiniciar"
3. Aguarde a confirmação de sucesso

Quando reiniciar? Sempre que você alterar as configurações do sistema, é recomendado reiniciar a API para que as novas configurações sejam aplicadas.

️ Como remover o serviço:

1. Acesse API → Gestão da API
2. Primeiro, pare a API clicando em " Parar"
3. Após parada, clique em "️ Remover Serviço Windows"
4. Confirme na janela que aparecer

Informações visíveis na tela:

Informação	O que significa
Serviço Windows: ✓ Instalado	O serviço está registrado no Windows
Estado do Serviço: Running	O serviço está em execução
Estado do Serviço: Stopped	O serviço está parado
Status da API: 🟢 Em Execução	A API está respondendo e funcionando
Porta	O número da porta onde a API está escutando
Tempo Online	Há quanto tempo a API está funcionando sem parar
Requisições	Quantas operações a API já processou

---

Gestão do Dispositivo QFace — O Leitor Biométrico

O que é:

Esta tela mostra as informações técnicas do leitor facial QFace conectado à sua rede e permite que você gerencie essa conexão.

️ Como verificar o status do leitor:

1. Clique em "Gestão QFace" no menu lateral
2. Veja o badge no canto superior direito:
   • Verde "Conectado" → o leitor está pronto para uso
   • Vermelho "Desconectado" → o leitor não está acessível

️ Como reconectar o leitor:

1. Acesse "Gestão QFace"
2. Se o leitor aparecer como "Desconectado", clique em " Reconectar"
3. Aguarde a mensagem de resultado

️ Como testar o leitor:

1. Acesse "Gestão QFace"
2. Clique em "🧪 Testar" (disponível apenas quando o leitor está conectado)
3. O sistema realizará um teste de comunicação e mostrará o resultado

️ Como desconectar o leitor manualmente:

1. Acesse "Gestão QFace"
2. Clique em "✕ Desconectar" (disponível apenas quando conectado)
3. Confirme na janela que aparecer

Informações exibidas na tela:

Informação	O que significa
Modelo	O modelo do leitor QFace (ex: QFace-M)
Firmware	A versão do software interno do leitor
Endereço IP	O endereço de rede do leitor no formato IP:Porta
Número de Série	O identificador único do equipamento
Última Atividade	Quando foi a última vez que o leitor respondeu ao sistema

---

Conversão de Fotos — Transformando Imagens em Dados Biométricos

O que é:

Quando um sistema externo (como o ERP ou sistema de ponto da sua empresa) envia fotos de colaboradores, o Insoft QFace App processa automaticamente essas imagens e transforma cada foto em um "código biométrico" que representa o rosto da pessoa. Esta tela mostra o andamento desse processo.

️ Como acompanhar uma conversão em andamento:

Você não precisa iniciar uma conversão manualmente por esta tela. O processo é iniciado automaticamente pelo sistema externo integrado. Quando uma conversão começa, esta tela é aberta automaticamente.

1. Quando uma conversão é iniciada pelo sistema externo, o aplicativo abre automaticamente a tela "Conversão de Fotos"
2. Você verá uma lista de cartões, um para cada pessoa sendo processada
3. Cada cartão mostra:
   • A foto do colaborador (se disponível)
   • O ID da pessoa (personId)
   • O status: Aguardando → Sucesso ou Erro
4. Acompanhe o progresso enquanto cada foto é processada sequencialmente
5. Ao final, todos os cartões mostrarão o resultado (sucesso ou erro)

Dicas úteis:

• O processo é automático — você não precisa clicar em nada durante a conversão
• Se aparecer algum cartão com (erro), verifique se a foto do colaborador está nítida e com o rosto visível
• A tela pode ser fechada após a conversão; os dados ficam salvos
• Você pode clicar na foto de um cartão para ampliá-la e verificar a qualidade

---

Captura de Fotos ao Vivo — Usando a Câmera do Leitor

O que é:

Além de enviar fotos prontas, o sistema também pode capturar fotos diretamente pela câmera embutida no leitor QFace. Quando um sistema externo solicita a captura, esta tela é aberta automaticamente para que o colaborador possa se posicionar na frente do leitor.

️ Como funciona uma captura ao vivo:

Assim como a conversão, você não inicia a captura manualmente. Ela é acionada pelo sistema externo.

1. O sistema externo solicita a captura de um colaborador
2. O aplicativo abre automaticamente a tela de captura (a janela vem para a frente na sua tela)
3. O colaborador deve se posicionar na frente do leitor QFace
4. O sistema inicia uma contagem regressiva de 5 segundos
5. Durante a contagem, o colaborador deve olhar diretamente para o leitor
6. O leitor QFace captura o rosto automaticamente
7. O resultado é exibido na tela com a indicação de qualidade:
   • 🟢 Qualidade Excelente → ótimo resultado
   • 🟡 Qualidade Razoável → resultado aceitável
   • Qualidade muito baixa → a captura precisa ser refeita

Dicas para uma boa captura:

• O colaborador deve estar à frente do leitor, com o rosto bem iluminado
• Evite contra-luz (janelas ou lâmpadas atrás da pessoa)
• O rosto deve estar centralizado no campo de visão da câmera
• O colaborador não deve usar óculos de sol ou chapéu que cubra o rosto
• A distância ideal do leitor é de aproximadamente 30 a 50 centímetros

---

Configurações — Personalizando o Sistema

O que é:

A tela de configurações permite ajustar todos os parâmetros do sistema. As configurações são organizadas em abas, cada uma responsável por um grupo de opções.

️ Como acessar as configurações:

1. Clique em "Configurações" no menu lateral (ícone de engrenagem ️)
2. Escolha a aba desejada no topo da tela

---

Aba Geral

️ Como alterar o tema visual:

1. Acesse Configurações → Aba Geral
2. Na seção "Tema", escolha entre:
   • ️ Claro — fundo branco, ideal para ambientes bem iluminados
   • Escuro — fundo escuro, ideal para ambientes com pouca luz ou uso prolongado
   • Sistema — segue automaticamente a configuração do seu Windows
3. Clique em " Salvar Configurações"

️ Como configurar a porta do servidor:

1. Acesse Configurações → Aba Geral
2. Encontre o campo "IP do Servidor" e "Porta do Servidor"
3. Normalmente, o IP deve ser localhost e a porta é um número como 3333
4. Clique em " Salvar Configurações"

---

Aba QFace

️ Como configurar a conexão com o leitor:

1. Acesse Configurações → Aba QFace
2. Verifique o campo "Porta do Dispositivo" (padrão: 12120)
3. Ative ou desative a opção "Habilitar Captura QFace" conforme necessário
4. Clique em " Salvar Configurações"

---

Aba Servidor

️ Como habilitar conexão segura (SSL):

1. Acesse Configurações → Aba Servidor
2. Ative a opção "Usar SSL"
3. Siga as instruções para configurar o certificado SSL
4. Clique em " Salvar Configurações"
5. Reinicie a API para que as alterações sejam aplicadas

---

Aba Avançado

️ Como configurar o envio automático para um sistema externo:

1. Acesse Configurações → Aba Avançado
2. Ative a opção "Habilitar API Externa"
3. Preencha:
   • URL da API Externa: o endereço do sistema que receberá os dados
   • Usuário: login de acesso ao sistema externo (se necessário)
   • Senha: senha de acesso ao sistema externo (se necessário)
4. Configure o Template de Payload (o formato dos dados que serão enviados)
5. Adicione os Endpoints (endereços específicos) que receberão os dados
6. Clique em " Salvar Configurações"

️ Como configurar o tempo de retenção de registros:

1. Acesse Configurações → Aba Avançado
2. Encontre o campo "Dias de Retenção"
3. Informe por quantos dias os registros devem ser mantidos (padrão: 7 dias)
4. Clique em " Salvar Configurações"

---

Aba Certificados

️ Como gerenciar certificados SSL:

1. Acesse Configurações → Aba Certificados
2. Para adicionar um certificado:
   • Clique em "Selecionar Certificado" e escolha o arquivo (.pem, .crt, .cer)
   • Clique em "Selecionar Chave Privada" e escolha o arquivo correspondente
3. Os certificados instalados aparecem na lista abaixo
4. Para remover um certificado, clique no botão de remoção ao lado dele

---

A documentação continua na parte 2, através da seguinte URL:

Insoft QFace App - Documentação de Usuário - Parte 2