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é-requisitosAntes 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 equipamentoO 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 placasEquipamentos com modo inválido não são processados corretamente.
Validação remotaPara 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 placasPara 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 GatewaySe deviceGatewayEnabled estiver habilitado, consulte também:
Insoft Hikvision Service + Hik Device GatewayNesse 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çãoO serviço utiliza configurações separadas por responsabilidade. Os arquivos ficam dentro do diretório da aplicação instalada.
Configuração do serviço HikvisionArquivo:
device-serviceConfig/application.jsonExemplo 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 principalArquivo:
security-gear-lib-apiConfig/application.jsonExemplo:
{ "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 comumArquivo:
common-gear-lib-apiConfig/application.jsonExemplo:
{ "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 facialArquivo:
insoft-automacao-facial-lib-apiConfig/application.jsonExemplo:
{ "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çãoAo 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 identificadosO 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 biometriasO 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. PessoasO 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õesOs 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 facialA 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 digitalO 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 SoftO 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 equipamentoAlguns 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 acessoQuando 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 acessoO dispositivo envia eventos ao endpoint:
/eventRegistrationO 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 LPRPara 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 dispositivosDurante 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 veicularQuando 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çõesQuando 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çãoQuando 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 ISAPIQuando 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 GatewayQuando 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áriaNo 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 offlineVerifique 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 SoftConfirme 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 acessoVerifique 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 WiegandConfirme 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 falhaConfira 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 falhaConfirme 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 sincronizamConfira 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álidaO 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.