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:

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:

1. Cria os diretórios de recursos, logs, imagens e banco local.
2. Lê as configurações do serviço, da API, do módulo comum e da automação.
3. Autentica na API do Akita Soft.
4. Confere a versão da API.
5. Inicializa o banco SQLite local.
6. Carrega a lista de dispositivos Hikvision cadastrados no Akita Soft.
7. 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.

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:

1. A pessoa apresenta o cartão, face, digital ou outra credencial no dispositivo.
2. O equipamento gera um evento solicitando autorização.
3. O serviço recebe o evento no endpoint /eventRegistration.
4. O serviço consulta a API do Akita Soft no fluxo de validação.
5. A API retorna se o acesso deve ser liberado ou negado.
6. O serviço responde ao equipamento pela ISAPI RemoteCheck.
7. 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.