Objetivo

Esta documentação explica como o Insoft Hikvision Service opera quando o modo Hik Device Gateway está habilitado.

O Hik Device Gateway é um WebService da Hikvision que pode intermediar a comunicação com os dispositivos. Nesse cenário, o Insoft Hikvision Service não precisa falar diretamente com a ISAPI de cada equipamento. Ele envia as requisições ao Device Gateway, e o Device Gateway se comunica com os dispositivos usando ISUP, protocolo fechado da Hikvision.

Quando usar

Use o Hik Device Gateway quando o ambiente exigir comunicação centralizada com os dispositivos Hikvision, principalmente quando os equipamentos não estão acessíveis diretamente pelo servidor do Insoft Hikvision Service ou quando a arquitetura do cliente já utiliza ISUP.

Pré-requisitos do Device Gateway

WebService Hik Device Gateway

• O Hik Device Gateway deve estar instalado, configurado e acessível pelo servidor onde o Insoft Hikvision Service está rodando.
• o Device Gateway deve aceitar autenticação HTTP. A documentação da Hikvision descreve uso de autenticação Basic ou Digest; o serviço utiliza autenticação Digest.
• O usuário configurado para o Device Gateway precisa ter permissão para adicionar dispositivos, listar dispositivos, consultar informações, encaminhar chamadas ISAPI e configurar eventos.
• A porta do Device Gateway deve estar liberada na rede. No serviço, quando a porta não é informada e o uso de SSL está desabilitado, o padrão utilizado é 8180.
• As portas de conexão dos dispositivos no Device Gateway precisam estar liberadas conforme a tela Device Connection Port do próprio Hik Device Gateway.
• CPU, memória, armazenamento, latência, portas TCP/UDP quando aplicável, IPv4, DNS, hostnames e firewall devem ser validados em Infraestrutura e requisitos técnicos.

Dispositivos Hikvision

• Os dispositivos precisam estar compatíveis com o modo ISUP/eHome esperado pelo Device Gateway.
• Cada dispositivo precisa ter um identificador ISUP/eHome configurado.
• Cada dispositivo precisa ter uma chave ISUP/eHome configurada.
• O dispositivo deve conseguir se conectar ao Device Gateway pela rede.
• O dispositivo deve aparecer online na lista de dispositivos do Device Gateway.

No código do serviço, o dispositivo é adicionado ao Device Gateway com:

• protocolType como ehomeV5;
• nome do dispositivo como código do equipamento com quatro dígitos;
• EhomeID como o mesmo código formatado;
• EhomeKey como a senha cadastrada para o dispositivo na API principal.

Por isso, o cadastro do equipamento na API principal e a configuração ISUP/eHome no dispositivo precisam estar alinhados.

Rede e firewall

A comunicação precisa estar liberada em três sentidos:

• Insoft Hikvision Service para Hik Device Gateway;
• dispositivos Hikvision para Hik Device Gateway;
• dispositivos ou Device Gateway para o endpoint de eventos do Insoft Hikvision Service.

Também valide:

• resolução de hostname do Device Gateway pelo servidor do serviço;
• resolução de hostname do servidor de eventos pelo Device Gateway ou pelos dispositivos;
• porta deviceGatewayPort, padrão 8180 quando HTTP;
• porta HTTPS customizada quando useSsl=true;
• portas ISUP/eHomeV5 configuradas no Device Gateway;
• porta eventServerPort, padrão 8888, para eventos em /eventRegistration.

O endpoint de eventos usado pelo serviço é:

/eventRegistration

A porta desse endpoint é definida em eventServerPort, no arquivo common-gear-lib-apiConfig/application.json.

O guia da Hikvision descreve portas padrão de protocolo, como HTTP 80, HTTPS 443 e RTSP 554. No Insoft Hikvision Service, a porta de acesso ao WebService do Device Gateway é definida por deviceGatewayPort.

Portas no WebService do Device Gateway

O painel do Hik Device Gateway separa as portas em dois grupos:

• Device Connection Port: portas usadas pelos dispositivos Hikvision para se conectarem ao Device Gateway.
• Gateway Access Port: portas usadas por aplicações, clientes ou serviços para acessar o WebService do Device Gateway.

As portas abaixo são o padrão utilizado nas instalações de exemplo. Elas devem ser conferidas no ambiente do cliente, porque o Hik Device Gateway permite alterar esses valores.

Importante: os IPs e hostnames exibidos nas imagens são exemplos do ambiente usado como referência. O endereço 201.20.147.94, por exemplo, não deve ser tratado como padrão para clientes. Em cada implantação, use o IP, hostname ou FQDN real que os dispositivos e servidores conseguem alcançar.

Device Connection Port

Para o uso normal do Insoft Hikvision Service com Device Gateway, valide principalmente 7661, 7091, 8180 e 8888. As demais portas devem ser liberadas quando estiverem habilitadas ou quando o cliente também usar vídeo, áudio, playback, alarmes ou streaming pelo Device Gateway.

Gateway Access Port

No código do serviço, se useSsl=false e deviceGatewayPort estiver vazio, a porta padrão usada para o WebService do Device Gateway é 8180.

NAT no Device Gateway

Quando os dispositivos ou o servidor do serviço estão fora da mesma rede do Device Gateway, pode ser necessário configurar NAT no próprio Hik Device Gateway e também no roteador/firewall do cliente.

No NAT, o endereço externo precisa ser o endereço realmente acessível pela origem da conexão:

• se o dispositivo está em outra rede, ele precisa alcançar o endereço externo do Device Gateway nas portas de conexão dos dispositivos;
• se o Insoft Hikvision Service está em outro servidor ou outra rede, ele precisa alcançar o endereço externo do Device Gateway na porta de acesso HTTP ou HTTPS;
• se o Device Gateway ou dispositivo precisa enviar eventos para o Insoft Hikvision Service, o endereço configurado em deviceGatewayEventListenerHost precisa apontar para um IP, hostname ou FQDN acessível por esse caminho.

Em instalações padrão, quando NAT é usado, normalmente as portas externas são mantidas iguais às internas: 7661, 7091, 7664, 7665, 7666, 7663, 7662, 15000-17000, 8180, 554 e 443. Se o cliente alterar qualquer porta externa, a configuração do Device Gateway, firewall, roteador e serviço precisa refletir a porta real.

Liberação apenas para redes confiáveis

Não é recomendado expor o Hik Device Gateway livremente para qualquer origem da internet.

As liberações de portas TCP/UDP devem ser feitas com allowlist de origens confiáveis. Em outras palavras: primeiro libera-se apenas quem pode acessar, depois bloqueia-se todo o restante.

Essa regra deve ser aplicada no firewall, roteador, security group, proxy reverso, appliance de borda ou solução equivalente do cliente. Se a versão instalada do Hik Device Gateway possuir tela de Access Network, ela pode ser usada como camada adicional de restrição, mas não substitui a regra de firewall da rede.

Exemplo conceitual:

Origem não confiável:

Os IPs e hostnames acima são apenas exemplos. Em produção, use os endereços reais das filiais, matriz, VPNs, servidores e dispositivos do cliente.

Boas práticas:

• prefira liberar IPs ou redes em formato CIDR, por exemplo /32 para um único IP ou /24 para uma faixa da filial;
• se o firewall aceitar regras por FQDN, valide a resolução DNS e o tempo de atualização dessas regras;
• se o hostname mudar de IP, atualize a allowlist antes da troca;
• evite regras abertas como 0.0.0.0/0 para as portas do Device Gateway;
• registre logs de conexões bloqueadas e permitidas;
• mantenha uma regra final de bloqueio para qualquer origem não prevista;
• documente quem solicitou, quem aprovou e qual filial ou servidor usa cada liberação.

Liberações típicas:

Configuração de HTTPS/SSL no Device Gateway

O manual da Hikvision orienta configurar HTTPS em:

Configuration -> Network Settings -> HTTPS

Antes de habilitar HTTPS, defina:

• o hostname ou FQDN que será usado para acessar o Device Gateway, por exemplo devicegateway.exemplo.com.br;
• se a porta HTTPS será 443 ou outra porta definida pelo cliente;
• se haverá NAT entre a origem e o Device Gateway;
• se o certificado será autoassinado, importado pronto ou gerado a partir de uma solicitação de certificado;
• se o Insoft Hikvision Service usará o Device Gateway por HTTPS.

Também confira:

Configuration -> Network Settings -> Port -> Gateway Access Port

A porta HTTPS precisa aparecer com status normal. Se a porta estiver ocupada, ajuste a porta no Device Gateway e libere a nova porta no firewall.

No Insoft Hikvision Service, para usar HTTPS, configure:

{
  "deviceGatewayEnabled": true,
  "deviceGatewayWebServiceHost": "devicegateway.exemplo.com.br",
  "useSsl": true,
  "deviceGatewayPort": 443
}

Recomenda-se preencher deviceGatewayPort explicitamente com 443, mesmo quando HTTPS usa a porta padrão. Isso deixa a configuração mais clara para implantação e suporte.

Certificado autoassinado

Use certificado autoassinado apenas em ambiente interno controlado, homologação ou quando a política do cliente permitir.

Passos:

1. Acesse Configuration -> Network Settings -> HTTPS.
2. Selecione Create self-signed certificate.
3. Preencha os campos obrigatórios:
   • Country: país;
   • Domain/IP: hostname, FQDN ou IP usado para acessar o Device Gateway;
   • Validity: validade em dias.
4. Preencha os demais campos conforme o padrão do cliente:
   • Password;
   • State or Province;
   • Locality;
   • Organization;
   • Organizational Unit;
   • Email.
5. Clique em Save.
6. Acesse o Device Gateway por https://HOST_DO_GATEWAY:443.
7. Valide se a porta HTTPS ficou normal em Gateway Access Port.

Ponto de atenção: certificado autoassinado normalmente gera aviso de segurança no navegador e pode ser recusado por clientes HTTP que validam cadeia de confiança. Em produção, prefira certificado assinado por autoridade confiável ou certificado emitido pela autoridade interna do cliente.

Importar certificado assinado existente

Use esta opção quando o cliente já possui um certificado válido para o hostname do Device Gateway.

Passos:

1. Acesse Configuration -> Network Settings -> HTTPS.
2. Selecione Signed certificate is available, start the installation now.
3. Clique em Browse.
4. Selecione o arquivo de certificado fornecido pelo cliente.
5. Clique em Install.
6. Valide o acesso pelo navegador usando https://HOST_DO_GATEWAY:443.
7. Confirme que o certificado apresentado pertence ao hostname usado pelo serviço.

O certificado precisa corresponder ao hostname usado em deviceGatewayWebServiceHost. Se o serviço acessa devicegateway.exemplo.com.br, esse nome precisa constar no certificado. Se o serviço acessa por IP, o certificado precisa conter esse IP como identificação válida, quando a autoridade emissora permitir.

Gerar solicitação de certificado

Use esta opção quando o cliente ainda não possui certificado, mas deseja emitir um certificado válido em uma autoridade confiável.

Passos:

1. Acesse Configuration -> Network Settings -> HTTPS.
2. Selecione Create the certificate request first and continue the installation.
3. Clique em Create.
4. Preencha os dados solicitados pelo Device Gateway.
5. Baixe a solicitação de certificado.
6. Envie a solicitação para a autoridade certificadora do cliente ou para a autoridade pública contratada.
7. Depois de receber o certificado assinado, volte à tela de HTTPS.
8. Em Install Generated Certificate, clique em Browse.
9. Selecione o certificado gerado.
10. Clique em Install.
11. Teste o acesso HTTPS e valide o certificado no navegador.

Segurança

A documentação da Hikvision recomenda atenção especial a dados sensíveis, como usuário, senha e chaves de conexão. Em produção, use rede protegida, credenciais próprias para integração e, quando possível, comunicação segura por HTTPS.

Configuração no Insoft Hikvision Service

Arquivo:

device-serviceConfig/application.json

Exemplo:

{
  "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:

• deviceGatewayEnabled: deve estar como true.
• deviceGatewayWebServiceHost: host ou IP do WebService do Device Gateway.
• deviceGatewayEventListenerHost: endereço informado aos dispositivos para envio de eventos.
• useSsl: quando true, o serviço monta URLs com https.
• deviceGatewayPort: porta do Device Gateway. Se estiver vazia e useSsl estiver false, o serviço usa 8180.
• deviceGatewayLogin: usuário do Device Gateway.
• deviceGatewayPassword: senha do Device Gateway.

Como o fluxo funciona

Quando o modo Device Gateway está habilitado, o serviço executa as seguintes etapas:

1. Lê os dispositivos cadastrados na API principal, seja Akita Soft ou Ponto Soft.
2. Autentica no Hik Device Gateway.
3. Envia ao Device Gateway o cadastro dos dispositivos que devem ser gerenciados.
4. Consulta a lista de dispositivos existentes no Device Gateway.
5. Relaciona cada dispositivo da API com o identificador interno criado pelo Device Gateway.
6. Usa esse identificador, chamado devIndex, para encaminhar chamadas ISAPI ao dispositivo correto.
7. Configura servidor de eventos, horários, leitores, cadastros e demais rotinas usando o Device Gateway como intermediário.
8. Recebe eventos pelo endpoint /eventRegistration e sincroniza com a API principal.

O devIndex é essencial. Sem ele, o Device Gateway não sabe para qual equipamento a chamada deve ser encaminhada.

Diferenças em relação ao modo direto

Mesmo com Device Gateway, o cadastro do equipamento na API principal continua obrigatório. É por esse cadastro que o serviço sabe quais equipamentos deve gerenciar, quais permissões usar e quais pessoas, cartões, faces, digitais ou placas devem ser sincronizados.

Rotina de cadastro no Device Gateway

Periodicamente, o serviço tenta garantir que os dispositivos da API principal estejam cadastrados no Device Gateway.

o Device Gateway recebe os dispositivos com protocolo ehomeV5. Depois, o serviço consulta a lista de dispositivos do Device Gateway e vincula o identificador retornado ao equipamento local.

Se o equipamento não aparecer online no Device Gateway, o serviço pode atualizar seu status como offline na API principal.

Eventos no modo Device Gateway

O serviço ainda precisa receber eventos de acesso, ponto ou veículo.

Para isso, ele configura nos dispositivos o servidor de eventos HTTP. A chamada recebida pelo serviço usa o endpoint:

/eventRegistration

O endereço informado ao equipamento vem de deviceGatewayEventListenerHost quando o Device Gateway está habilitado. Se esse endereço estiver incorreto, os eventos não chegarão ao serviço.

Captura remota de face no modo Device Gateway

No modo direto, a captura remota de face pode retornar os dados da imagem diretamente.

No modo Device Gateway, o fluxo pode usar uma URL temporária de armazenamento do Device Gateway. O serviço acompanha o progresso da captura e, quando a imagem fica disponível, baixa a imagem pelo endpoint de armazenamento do Device Gateway e envia a foto para a API principal.

Limitações e cuidados

• o Device Gateway precisa estar saudável para que os dispositivos sejam considerados online.
• O nome ou identificador do dispositivo no Device Gateway precisa bater com o código formatado usado pelo serviço.
• A primeira vinculação do dispositivo pode depender do próximo ciclo de sincronização do Device Gateway.
• Se houver dispositivos duplicados ou nomes inconsistentes no Device Gateway, o serviço pode não relacionar corretamente o equipamento.
• o Device Gateway não substitui a API principal. Akita Soft ou Ponto Soft continuam sendo a fonte dos cadastros e comandos.
• o Device Gateway não elimina a necessidade de receber eventos no Insoft Hikvision Service.

Problemas comuns

Erro 401 ao acessar o Device Gateway

Verifique deviceGatewayLogin, deviceGatewayPassword e permissões do usuário no Device Gateway.

Equipamento não aparece online

Verifique se o dispositivo está configurado para conectar no Device Gateway por ISUP/eHome, se o identificador e a chave estão corretos, e se a comunicação de rede entre dispositivo e Gateway está liberada.

Dispositivo não é vinculado ao cadastro da API

Confira se o código formatado do equipamento é o mesmo identificador configurado no dispositivo e no Device Gateway. O serviço usa o código do equipamento preenchido com zeros à esquerda até quatro dígitos.

Exemplo:

Código 7 -> 0007
Código 123 -> 0123

Cadastros não chegam ao dispositivo

Confirme se o Device Gateway está online, se o dispositivo está online dentro do Device Gateway e se o serviço já recebeu o devIndex do equipamento.

Eventos não chegam ao serviço

Verifique deviceGatewayEventListenerHost, eventServerPort, firewall e roteamento de rede. O endereço configurado precisa ser acessível pelo caminho que envia os eventos.

Captura remota de face falha

Verifique se o dispositivo suporta a captura remota pelo Device Gateway, se a sessão com o Device Gateway está válida e se o endpoint de armazenamento do Device Gateway está acessível.

Checklist de implantação com Gateway

• Hik Device Gateway instalado.
• Requisitos de infraestrutura validados em Infraestrutura e requisitos técnicos.
• Serviço consegue acessar o host e a porta do Device Gateway.
• Portas padrão do Device Gateway conferidas na tela Device Connection Port.
• Portas padrão do Device Gateway conferidas na tela Gateway Access Port.
• NAT configurado no Device Gateway, roteador e firewall, quando houver redes diferentes.
• Liberação por allowlist aplicada para IPs, redes ou hostnames confiáveis.
• Regra final de bloqueio aplicada para origens não autorizadas.
• HTTPS configurado no Device Gateway, se o ambiente exigir comunicação criptografada.
• useSsl e deviceGatewayPort configurados no Insoft Hikvision Service quando HTTPS estiver em uso.
• Usuário e senha do Device Gateway testados.
• deviceGatewayEnabled configurado como true.
• deviceGatewayWebServiceHost configurado corretamente.
• deviceGatewayEventListenerHost configurado com endereço acessível para eventos.
• eventServerPort liberada.
• Dispositivos configurados para ISUP/eHomeV5.
• Identificador do dispositivo compatível com o código formatado usado pelo serviço.
• Chave ISUP/eHome compatível com a senha cadastrada na API principal.
• Dispositivos aparecem online na lista do Device Gateway.
• devIndex vinculado ao equipamento.
• Envio de pessoa, cartão, face e digital testado.
• Eventos recebidos em /eventRegistration.