Skip to main content

​
Hik-Partner Pro

A integração Hik-Partner Pro conecta sites de controle de acesso Hikvision ao Portal através da OpenAPI de nuvem (/api/hpcgw/v1/*). Diferente da integração Hikvision (que fala direto com o controlador na LAN via ISAPI), esta roda 100% na nuvem: nenhum worker precisa estar na casa do cliente.
Se você já tem acesso direto ao controlador na rede local, use a integração Hikvision — ela é mais rápida e tem menos latência de abertura de porta. O Hik-Partner Pro é indicado para sites gerenciados por instaladores/parceiros, instalações sem IP fixo, ou cenários onde o Portal roda inteiramente na nuvem.

​
Pré-requisitos

  • Conta ativa no Hik-Partner Pro com pelo menos um site vinculado.
  • App Key e Secret Key da conta de desenvolvedor (self-service).
  • Dispositivos de controle de acesso online no site.

​
Como obter as credenciais

  1. Entre em https://{regiao}.hik-partner.com (ex: isa.hik-partner.com para América do Sul).
  2. Menu Serviço → Meu serviço → Integração da API → Conta de desenvolvedor.
  3. Clique em Adicionar nova aplicação e copie Chave (App Key) + Segredo (Secret Key).
Guarde a Secret Key — ela só é exibida uma vez. Se perder, revogue e crie outra pelo mesmo painel.

​
Regiões suportadas

Apenas isa está confirmada em produção pela equipe Unicontrol. As demais seguem o padrão de nomenclatura da API Hik-Connect — confirme com seu representante Hikvision antes de usar.

​
Configurar

1

Adicione a integração

Vá em Configurações → Integrações → Adicionar → Hik-Partner Pro.
2

Informe credenciais

Preencha nome do site, selecione a região, cole App Key e Secret Key.
3

Autenticação + descoberta

O Portal troca as credenciais por um accessToken (válido por 7 dias, renovado automaticamente), descobre as portas vinculadas ao systemGUID do site e cria uma entidade lock + binary_sensor para cada porta.

​
Recursos

  • lock — uma entidade por porta descoberta no site, com suporte a:
    • Abrir (momentâneo)
    • Trancar / Destrancar (estado persistente)
    • “Sempre aberto” (modo passagem livre)
  • binary_sensor — estado da porta (aberta/fechada) com device_class: "door".

​
Lock Manager

A integração se registra no painel Lock Manager com as seguintes capabilities:

​
Eventos em tempo real

O runtime assina a fila de alarmes (/alarm/v1/mq/subscribe) e faz polling a cada 500ms (/alarm/v1/mq/messages), seguindo o padrão recomendado pela OpenAPI HPP. Eventos de abertura de porta são projetados no binary_sensor correspondente.
A assinatura expira em 2 dias se não for consumida — o Portal renova automaticamente a cada ~36h. Mensagens ficam retidas 3 dias na fila.

​
Como Funciona

  • Transporte: HTTPS JSON (camelCase), rate-limit de 5 req/s por conta de desenvolvedor.
  • Autenticação: POST /api/hpcgw/v1/token/get com { appKey, secretKey } → { accessToken, expireTime, areaDomain }. O areaDomain retornado é usado como base de todas as chamadas subsequentes.
  • Reconfiguração: a entrada é identificada pelo systemGUID do site. Se você trocar credenciais, o Portal valida que o systemGUID continua o mesmo antes de salvar.
  • Falhas: respostas da HPP vêm no formato { errorCode: "0", data: {...} }. Qualquer errorCode != "0" lança erro visível no log do config-flow / runtime.

​
Limitações conhecidas

  • Agendas customizadas (LockSchedule.rules) ainda não são sincronizadas para templates HPP — a Fase 2 criará templates on-the-fly.
  • credentialCapture (botão “Capturar via leitor”) desligado no MVP porque a HPP não expõe endpoint dedicado; captura exige leitura via eventos.
  • Vídeo (JSDecoder / HPNetSDK) não é coberto por esta integração — use as integrações ONVIF ou RTSP para câmeras.