Insoft Hikvision Service no Ponto Soft

Gilberto Júnior

Insoft Hikvision Service para Ponto Soft

Objetivo

Esta documentação explica como usar o Insoft Hikvision Service integrado ao Ponto Soft.

Nesse modo, o serviço é responsável por manter os dispositivos Hikvision sincronizados com os funcionários cadastrados no Ponto Soft. Ele envia pessoas, cartões, biometrias faciais e digitais para os equipamentos, acompanha comandos pendentes e recebe as marcações realizadas nos dispositivos.

Quando uma pessoa registra o ponto no equipamento, o dispositivo envia o evento ao Insoft Hikvision Service. Depois disso, o serviço grava o evento localmente e sincroniza a marcação com a API do Ponto Soft.

Pré-requisitos

Antes de iniciar o serviço, confirme os itens abaixo.

API e licença

A API do Ponto Soft deve estar acessível pela rede.
A API precisa responder aos endpoints de autenticação, saúde e informações da API.
A versão da API do Ponto Soft deve ser 2.1.0 ou superior.
O servidor configurado no serviço deve existir na API principal.
A licença dos equipamentos deve estar válida. Quando a licença está inválida, o serviço interrompe a consulta de dispositivos.

Serviço e servidor

O Insoft Hikvision Service deve estar instalado em um servidor Windows.
O servidor precisa ter permissão de rede para acessar a API do Ponto Soft.
O servidor precisa acessar os dispositivos Hikvision diretamente pela rede ou acessar o Hik Device Gateway, se esse modo estiver habilitado.
O diretório do serviço precisa permitir escrita, pois o serviço cria logs, banco SQLite local e arquivos de imagem de eventos.
A porta do servidor de eventos deve estar liberada para receber chamadas dos dispositivos. Por padrão, a porta usada é 8888, mas ela pode ser alterada no arquivo de configuração.
Os requisitos de CPU, memória, armazenamento, latência, TCP/UDP quando aplicável, IPv4, DNS, hostnames e firewall devem ser validados em Infraestrutura e requisitos técnicos.

Dispositivos Hikvision

Os equipamentos devem estar cadastrados no Ponto Soft como dispositivos Hikvision.
O campo de tipo do equipamento deve indicar Hikvision. O serviço filtra os equipamentos do Ponto Soft pelo tipo HV.
O cadastro do equipamento deve conter endereço IP ou host, porta, usuário, senha, número de série e permissões de cadastro facial ou digital.
O usuário configurado no equipamento precisa ter permissão para consultar, cadastrar e remover pessoas, cartões, faces, digitais e eventos.
O horário do equipamento deve estar correto ou deve permitir ajuste pelo serviço.
A ISAPI do equipamento deve estar ativa e acessível.

Comunicação de eventos

O dispositivo precisa conseguir chamar o endereço do servidor onde o serviço está escutando eventos.

O serviço registra nos dispositivos um endpoint parecido com este:

http://SERVIDOR_DO_SERVICO:PORTA/eventRegistration

Se essa comunicação não funcionar, os cadastros podem ser enviados ao equipamento, mas as marcações não chegarão ao Ponto Soft.

Além da porta de eventos, valide as liberações de rede descritas em Infraestrutura e requisitos técnicos, principalmente:

saída do servidor do serviço para a API do Ponto Soft;
saída do servidor do serviço para os equipamentos, quando sem Gateway;
entrada dos equipamentos ou Gateway na porta eventServerPort;
resolução de hostnames, caso IP fixo não seja usado.

Uso com Hik Device Gateway

Se deviceGatewayEnabled estiver habilitado, além dos requisitos anteriores, consulte também:

Insoft Hikvision Service + Hik Device Gateway

Nesse modo, o serviço não chama diretamente a ISAPI de cada equipamento. Ele chama o Hik Device Gateway, que faz a comunicação com os dispositivos por ISUP.

Arquivos de configuração

O serviço utiliza configurações separadas por responsabilidade. Os arquivos ficam dentro do diretório da aplicação instalada.

Configuração do serviço Hikvision

Arquivo:

device-serviceConfig/application.json

Exemplo para comunicação direta com os dispositivos:

{
  "useAllDigitsMifare": false,
  "deviceGatewayEnabled": false,
  "deviceGatewayWebServiceHost": null,
  "deviceGatewayEventListenerHost": null,
  "useSsl": false,
  "deviceGatewayPort": null,
  "deviceGatewayLogin": null,
  "deviceGatewayPassword": null
}

Exemplo para uso com Hik Device Gateway:

{
  "useAllDigitsMifare": false,
  "deviceGatewayEnabled": true,
  "deviceGatewayWebServiceHost": "192.168.0.10",
  "deviceGatewayEventListenerHost": "192.168.0.20",
  "useSsl": false,
  "deviceGatewayPort": 8180,
  "deviceGatewayLogin": "admin",
  "deviceGatewayPassword": "senha-do-gateway"
}

Campos principais:

useAllDigitsMifare: quando habilitado, os cartões Mifare são enviados com todos os dígitos, preenchendo com zeros à esquerda quando necessário.
deviceGatewayEnabled: ativa ou desativa o uso do Hik Device Gateway.
deviceGatewayWebServiceHost: endereço do WebService do Gateway.
deviceGatewayEventListenerHost: endereço que o Gateway ou os dispositivos devem usar para enviar eventos ao serviço.
useSsl: define se a comunicação com o Gateway será feita por HTTPS.
deviceGatewayPort: porta do Gateway. Quando não informada, o modo HTTP usa 8180.
deviceGatewayLogin e deviceGatewayPassword: credenciais usadas na autenticação Digest do Gateway.

Configuração de segurança e API principal

Arquivo:

security-gear-lib-apiConfig/application.json

Exemplo:

{
  "urlApi": "https://api-pontosoft.exemplo.com",
  "login": "usuario-integracao",
  "password": "senha",
  "serverId": 1,
  "logType": "INFORMATION"
}

Campos principais:

urlApi: endereço base da API do Ponto Soft.
login e password: credenciais de integração.
serverId: identificador do servidor cadastrado na API.
logType: nível de log desejado.

O serviço autentica na API, guarda o token e renova a autenticação periodicamente. Se a API ficar indisponível, o serviço pausa as chamadas dependentes da API e tenta se recuperar automaticamente.

Configuração comum

Arquivo:

common-gear-lib-apiConfig/application.json

Exemplo:

{
  "systemModule": "PontoSoft",
  "deviceModelType": "HV",
  "eventServerPort": 8888,
  "eventValidationTimeout": 3,
  "eventServerAddress": "192.168.0.20",
  "commandProcessingDelay": 3,
  "internalCommandDelay": 100,
  "apiErrorCommandDelay": 10,
  "deploymentMode": false,
  "eventLimitApiSync": 50,
  "eventSyncPauseTime": 5
}

Campos principais:

systemModule: deve indicar PontoSoft.
deviceModelType: tipo de modelo usado ao consultar equipamentos. Para Hikvision, use HV.
eventServerPort: porta em que o serviço receberá eventos.
eventServerAddress: endereço do servidor que será informado ao dispositivo.
commandProcessingDelay: intervalo mínimo entre ciclos de comandos por dispositivo.
apiErrorCommandDelay: pausa aplicada quando a API principal falha.
deploymentMode: quando habilitado, eventos anteriores ao início da implantação podem ser ignorados.
eventLimitApiSync: quantidade de eventos processados por ciclo de sincronização.
eventSyncPauseTime: intervalo entre sincronizações de eventos com a API.

Configuração da automação facial

Arquivo:

insoft-automacao-facial-lib-apiConfig/application.json

Exemplo:

{
  "beginTime": "00:00:00",
  "finishTime": "04:00:00",
  "routinePauseInterval": 5,
  "automationEnabled": true
}

Essa rotina compara a base da API, a base local e a base do dispositivo. Quando encontra diferenças, ela cria comandos de sincronização para corrigir cadastros, faces e digitais.

Fluxo de inicialização

Ao iniciar, o serviço executa as seguintes etapas:

Cria os diretórios de recursos, logs, imagens e banco local.
Lê as configurações do serviço, da API, do módulo comum e da automação.
Autentica na API do Ponto Soft.
Confere a versão da API.
Inicializa o banco SQLite local.
Carrega a lista de dispositivos Hikvision cadastrados no Ponto Soft.
Inicia o monitoramento dos dispositivos, o processamento de comandos e o recebimento de eventos.

Se algum arquivo de configuração obrigatório não existir, o serviço não inicia corretamente.

Como os dispositivos são identificados

O serviço busca os equipamentos na API do Ponto Soft e considera apenas os dispositivos do tipo Hikvision.

Os principais dados usados são:

código do equipamento;
endereço IP ou host;
porta de comunicação;
usuário e senha do equipamento;
número de série;
permissões de cadastro facial;
permissões de cadastro digital;
modelo e informações técnicas.

Dispositivos sem dados mínimos de comunicação são tratados como offline ou inválidos até que o cadastro seja corrigido.

Cadastro de pessoas, cartões e biometrias

O serviço mantém o equipamento alinhado com o cadastro do Ponto Soft.

Para cada funcionário, o serviço pode enviar:

dados básicos da pessoa;
cartão;
biometria facial;
biometria digital.

O envio acontece por comandos vindos da API ou pela rotina de automação, quando habilitada.

Pessoas

O serviço consulta os funcionários na API do Ponto Soft e envia ao equipamento os dados necessários para que o acesso ou marcação funcione.

Se uma pessoa existe no equipamento, mas não existe mais na API para aquele dispositivo, o serviço pode removê-la do equipamento durante a sincronização.

Cartões

Os cartões são comparados entre a API e o equipamento.

Quando há divergência, o serviço remove cartões incorretos e cadastra os cartões corretos. Isso evita que um cartão fique vinculado à pessoa errada ou com tipo incorreto no dispositivo.

Biometria facial

A biometria facial pode ser enviada da API para o equipamento ou coletada do equipamento para ser salva na API, dependendo do comando executado.

Ao enviar uma face ao dispositivo, a imagem precisa estar em condições aceitas pelo equipamento. Imagens muito pequenas, sem nitidez, com rosto distante ou fora do padrão podem ser recusadas pelo próprio Hikvision.

Biometria digital

O serviço também pode enviar ou coletar digitais. Cada pessoa pode ter até 10 posições de digitais no equipamento.

Se o dispositivo não tiver módulo de digital, os comandos de digital não são aplicáveis.

Comandos utilizados pelo Ponto Soft

O serviço consulta comandos pendentes na API e executa cada comando no dispositivo correspondente.

Código	Finalidade
`100`	Ajustar data e hora do equipamento
`103`	Buscar eventos do equipamento por data e enviar para a API
`108`	Sincronizar pessoa, cartão, face e digital
`110`	Copiar digitais do equipamento para a API
`111`	Enviar digitais da API para o equipamento
`112`	Remover digitais do equipamento
`113`	Conferir se a pessoa existe no equipamento
`130`	Copiar face do equipamento para a API
`131`	Enviar face da API para o equipamento
`132`	Remover face do equipamento
`133`	Capturar face remotamente no equipamento
`134`	Capturar digital remotamente no equipamento

Alguns comandos exigem parâmetros:

comandos de pessoa, face e digital normalmente exigem o código da pessoa ou funcionário;
o comando de busca de eventos por backup exige uma data no formato dd/MM/yyyy.

Cargas de funcionários

No modo Ponto Soft, o serviço também acompanha cargas de funcionários.

As cargas pendentes são consultadas na API, processadas e confirmadas. Quando uma carga falha, o serviço informa o erro de retorno para que o suporte consiga identificar a causa.

Recebimento de marcações

O dispositivo envia eventos ao endpoint:

/eventRegistration

O serviço interpreta o evento, identifica o dispositivo e grava a marcação no banco local. Depois, o sincronizador do Ponto Soft envia a marcação para:

/v1/registro

Para a marcação ser sincronizada corretamente, a pessoa precisa ter dados suficientes na API, especialmente CPF e vínculo com empregador quando exigido pelo Ponto Soft.

Rotina de automação

Quando habilitada, a automação roda dentro da janela de horário configurada.

Ela compara:

pessoas existentes na API;
pessoas existentes no equipamento;
cartões;
faces;
digitais;
registros locais de sincronização.

Quando encontra divergências, cria comandos na API para corrigir os cadastros. Isso reduz a necessidade de manutenção manual, principalmente em ambientes com muitos equipamentos.

Modo direto por ISAPI

Quando deviceGatewayEnabled está desabilitado, o serviço acessa cada equipamento pelo endereço IP e porta cadastrados no Ponto Soft.

Exemplo de destino:

http://IP_DO_EQUIPAMENTO:PORTA/ISAPI/...

Nesse modo, o próprio serviço autentica no equipamento usando autenticação Digest e executa chamadas de cadastro, consulta, remoção, captura e configuração.

Modo com Hik Device Gateway

Quando deviceGatewayEnabled está habilitado, o serviço acessa o Hik Device Gateway.

Exemplo de destino:

http://HOST_DO_GATEWAY:8180/ISAPI/...

O Gateway encaminha as operações ao dispositivo Hikvision correspondente. O serviço usa o identificador interno do dispositivo no Gateway, chamado devIndex, para direcionar a chamada ao equipamento correto.

Para detalhes de instalação, requisitos e solução de problemas, consulte:

Insoft Hikvision Service + Hik Device Gateway

Operação diária

No dia a dia, a equipe de suporte deve acompanhar:

se o serviço está em execução;
se a API do Ponto Soft está respondendo;
se a licença está válida;
se os dispositivos aparecem online;
se há comandos parados em processamento;
se existem eventos pendentes ou com erro de API;
se os arquivos de log mostram falhas de autenticação, conexão ou cadastro.

Problemas comuns

Dispositivo offline

Verifique IP, porta, usuário, senha, rede, firewall e se o equipamento está ligado. Em modo Gateway, verifique se o equipamento está online dentro do Gateway.

Eventos não chegam ao Ponto Soft

Confirme se o dispositivo consegue acessar o servidor do serviço na porta configurada. Também confirme se o endpoint /eventRegistration foi configurado no equipamento.

Marcações ficam pendentes

Verifique se a API do Ponto Soft está disponível e se a pessoa possui os dados necessários para sincronização, como CPF e empregador.

Comando de face falha

Confira a qualidade da imagem facial. O equipamento pode recusar imagens com baixa nitidez, rosto distante, enquadramento inadequado ou tamanho fora do padrão.

Comando de digital falha

Confirme se o equipamento possui módulo de digital e se a pessoa ainda possui posições disponíveis. O limite tratado pelo serviço é de até 10 digitais por pessoa.

Licença inválida

O serviço não processa normalmente a lista de equipamentos se a licença retornada pela API estiver inválida. Nesse caso, regularize a licença no sistema principal.

Checklist de implantação

API do Ponto Soft acessível.
Versão da API validada como 2.1.0 ou superior.
systemModule configurado como PontoSoft.
deviceModelType configurado como HV.
Servidor cadastrado e serverId correto.
Equipamentos Hikvision cadastrados como HV.
Credenciais dos equipamentos testadas.
Porta de eventos liberada.
Eventos recebidos em /eventRegistration.
Requisitos de infraestrutura validados em Infraestrutura e requisitos técnicos.
Comandos de pessoa, cartão, face e digital testados.
Sincronização de marcações validada na API.
Se usar Gateway, requisitos do Insoft Hikvision Service + Hik Device Gateway validados.