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.