Insoft Hikvision Service no Akita Soft

Gilberto Júnior

Insoft Hikvision Service para Akita Soft

Objetivo

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

Nesse modo, o serviço mantém os dispositivos Hikvision sincronizados com os cadastros do Akita Soft. Ele envia pessoas, cartões, faces, digitais, placas de veículos e configurações necessárias para controle de acesso. Também recebe eventos dos dispositivos, valida acessos remotamente quando configurado e sincroniza os registros com a API do Akita Soft.

Pré-requisitos

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

API e licença

A API do Akita 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 Akita Soft deve ser 2.0.1 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 Akita 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 Akita Soft como dispositivos Hikvision.
O tipo de modelo usado para consulta deve ser HV.
O cadastro do equipamento deve conter endereço IP ou host, porta, usuário, senha, número de série, modo de operação, sentido de acesso 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, placas e eventos.
A ISAPI do equipamento deve estar ativa e acessível.
O horário e o fuso horário do equipamento devem estar corretos ou devem permitir ajuste pelo serviço.

Modos de operação do equipamento

O serviço interpreta o modo de operação cadastrado no Akita Soft:

Valor	Modo	Uso
`L`	Leitor	Leitor de acesso
`C`	Controladora de acesso	Equipamento que controla liberação e pode usar validação remota
`V`	LPR veicular	Câmera ou dispositivo para leitura de placas

Equipamentos com modo inválido não são processados corretamente.

Validação remota

Para usar validação remota, confirme:

o equipamento deve estar no modo de controladora de acesso;
o campo de validação remota deve estar habilitado no cadastro do Akita Soft;
o equipamento precisa suportar RemoteCheck pela ISAPI;
o canal de verificação precisa aceitar escuta por ISAPI;
o servidor do serviço precisa receber eventos do equipamento;
o tempo de validação deve estar adequado no campo eventValidationTimeout.

Quando a validação remota está ativa, o dispositivo pergunta ao serviço se deve liberar ou negar o acesso. O serviço consulta a API do Akita Soft e responde ao equipamento com o resultado.

Para validação remota, a latência entre dispositivo, serviço e API precisa ser baixa e estável. Consulte os parâmetros recomendados em Infraestrutura e requisitos técnicos.

Veículos e placas

Para usar LPR, o equipamento deve estar cadastrado como modo V.

O serviço sincroniza placas e tags de veículos obtidas da API do Akita Soft. Os modelos tratados pelo código incluem dispositivos das famílias DS-TCG405-E, DS-TCG406-E e IDS-2CD7A46G0-P-IZHS.

Uso com Hik Device Gateway

Se deviceGatewayEnabled estiver habilitado, 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": true,
  "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-akitasoft.exemplo.com",
  "login": "usuario-integracao",
  "password": "senha",
  "serverId": 1,
  "logType": "INFORMATION"
}

Campos principais:

urlApi: endereço base da API do Akita 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": "AkitaSoft",
  "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 AkitaSoft.
deviceModelType: tipo de modelo usado ao consultar equipamentos. Para Hikvision, use HV.
eventServerPort: porta em que o serviço receberá eventos.
eventValidationTimeout: tempo de espera usado em validação remota.
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 Akita Soft.
Confere a versão da API.
Inicializa o banco SQLite local.
Carrega a lista de dispositivos Hikvision cadastrados no Akita 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 Akita Soft usando o tipo de modelo HV.

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;
modelo;
modo de operação;
sentido de acesso;
validação remota;
permissões de face e digital;
controle de tag veicular;
fuso horário;
funções de marcação, quando aplicável.

Dispositivos sem modo de operação válido ou sem dados mínimos de comunicação são tratados como inválidos ou offline 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 Akita Soft.

Para cada pessoa, o serviço pode enviar:

dados básicos;
cartão;
biometria facial;
biometria digital;
permissões e validade de acesso.

Pessoas

O serviço consulta as pessoas na API do Akita Soft e envia ao equipamento os dados necessários para controle de acesso.

O período de validade da pessoa é considerado durante o cadastro. Quando a API não informa uma validade específica, o serviço usa um período amplo, limitado por datas aceitas pelos equipamentos Hikvision.

Cartões

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

Quando há divergência, o serviço remove vínculos incorretos e cadastra os cartões corretos. Cartões provisórios são tratados com tipo apropriado no dispositivo, enquanto cartões comuns são enviados como cartões normais.

Biometria facial

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

Ao enviar uma face ao dispositivo, a imagem precisa estar em condições aceitas pelo Hikvision. Imagens com baixa qualidade, rosto distante, rosto mal enquadrado ou tamanho incompatível podem ser recusadas.

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 Akita Soft

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

Código	Finalidade
`1`	Copiar uma digital do equipamento para a API
`3`	Copiar todas as digitais do equipamento para a API
`11`	Enviar uma digital da API para o equipamento
`13`	Enviar todas as digitais da API para o equipamento
`21`	Remover uma digital do equipamento
`23`	Remover todas as digitais do equipamento
`200`	Ajustar data e hora do equipamento
`201`	Sincronizar pessoa, cartão, face e digital
`206`	Sincronizar placas de veículos
`207`	Remover placas de veículos
`208`	Buscar eventos do equipamento por data e enviar para a API
`210`	Copiar face do equipamento para a API
`211`	Enviar face da API para o equipamento
`212`	Remover face do equipamento
`213`	Conferir se a pessoa existe no equipamento
`220`	Capturar face remotamente no equipamento
`221`	Capturar digital remotamente no equipamento

Alguns comandos exigem parâmetros:

comandos de pessoa, face e digital normalmente exigem o código da pessoa;
o comando de busca de eventos por backup exige uma data no formato dd/MM/yyyy;
comandos de placa dependem do cadastro de veículos na API do Akita Soft.

Validação remota de acesso

Quando o equipamento está configurado para validação remota, o fluxo acontece assim:

A pessoa apresenta o cartão, face, digital ou outra credencial no dispositivo.
O equipamento gera um evento solicitando autorização.
O serviço recebe o evento no endpoint /eventRegistration.
O serviço consulta a API do Akita Soft no fluxo de validação.
A API retorna se o acesso deve ser liberado ou negado.
O serviço responde ao equipamento pela ISAPI RemoteCheck.
O evento é gravado e sincronizado com a API.

Esse modo depende de comunicação rápida entre equipamento, serviço e API. Se a API estiver lenta ou indisponível, o acesso pode falhar conforme o tempo de validação configurado.

Eventos de acesso

O dispositivo envia eventos ao endpoint:

/eventRegistration

O serviço interpreta o evento, identifica o dispositivo e grava o acesso no banco local. Depois, o sincronizador do Akita Soft envia:

acessos de pessoas para /v1/acessoPessoa;
acessos de veículos para /v1/veiculo/inserirAcesso.

Em dispositivos de controle de acesso, o serviço também pode atualizar a área da pessoa pela API do Akita Soft quando o evento exige essa atualização.

Controle de veículos e LPR

Para dispositivos LPR, o serviço consulta veículos na API do Akita Soft e envia placas e tags para o equipamento.

Durante a sincronização, o serviço:

remove caracteres inválidos das placas;
evita duplicidades;
compara placas existentes no equipamento com as placas da API;
remove placas antigas ou divergentes;
envia novas placas em lotes.

Os modelos têm formatos de envio diferentes, por isso o serviço identifica o modelo do dispositivo antes de montar a requisição.

Configurações aplicadas nos dispositivos

Durante a operação, o serviço pode configurar automaticamente:

servidor de eventos HTTP;
modo de armazenamento de eventos como ciclo, permitindo sobrescrita;
data e hora;
leitores;
validação remota;
Wiegand para leitura de tag veicular;
modo de atendimento ou marcação, quando houver funções configuradas no Akita Soft.

Wiegand e tag veicular

Quando o controle de tag veicular está habilitado, o equipamento precisa suportar Wiegand em modo de recebimento. Caso contrário, o serviço registra falha de configuração e a funcionalidade não opera corretamente.

Atendimento e funções

Quando o cadastro do equipamento possui lista de funções, o serviço configura teclas e planos de atendimento no dispositivo. Isso permite que o equipamento use funções como entrada, saída, intervalo e hora extra, conforme o cadastro do Akita 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. No Akita Soft, a automação pode criar comandos de sincronização de pessoa, atualização de face e atualização de digitais.

Modo direto por ISAPI

Quando deviceGatewayEnabled está desabilitado, o serviço acessa cada equipamento pelo endereço IP e porta cadastrados no Akita 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, validação remota 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 Akita 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 a validação remota está respondendo no tempo esperado;
se placas e tags estão sincronizadas nos dispositivos LPR;
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 Akita 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.

Validação remota não libera acesso

Verifique se a API do Akita Soft está disponível, se o dispositivo suporta RemoteCheck, se a validação remota está habilitada no cadastro do equipamento e se o tempo de validação é suficiente.

Erro ao configurar Wiegand

Confirme se o dispositivo possui interface Wiegand e se ela suporta modo de recebimento. Essa condição é necessária para controle de tag veicular.

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.

Placas não sincronizam

Confira o modelo do equipamento LPR, o cadastro do veículo na API, a placa normalizada e a tag vinculada. Também verifique se existem placas duplicadas ou em formato inválido.

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 Akita Soft acessível.
Versão da API validada como 2.0.1 ou superior.
systemModule configurado como AkitaSoft.
deviceModelType configurado como HV.
Servidor cadastrado e serverId correto.
Equipamentos Hikvision cadastrados com modo de operação válido.
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.
Validação remota testada, se usada.
Placas testadas em equipamentos LPR, se usadas.
Sincronização de eventos validada na API.
Se usar Gateway, requisitos do Insoft Hikvision Service + Hik Device Gateway validados.