> ## Documentation Index
> Fetch the complete documentation index at: https://docs.unicontrol.me/llms.txt
> Use this file to discover all available pages before exploring further.

# Hik-Partner Pro

> Integre controle de acesso Hikvision via nuvem Hik-Partner Pro (sem precisar expor o equipamento na LAN)

# 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](./hikvision) (que fala direto com o controlador na LAN via ISAPI), esta roda **100% na nuvem**: nenhum worker precisa estar na casa do cliente.

<Info>
  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.
</Info>

## 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)**.

<Warning>
  Guarde a Secret Key — ela só é exibida uma vez. Se perder, revogue e crie outra pelo mesmo painel.
</Warning>

## Regiões suportadas

| Região | Host |
| - | - |
| América do Sul | `isa.hik-partner.com` |
| América do Norte | `ius.hik-partner.com` |
| Europa | `ieu.hik-partner.com` |
| Singapura / Índia | `isgp.hik-partner.com` |
| Rússia | `hikpartnerru.com` |

<Info>
  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.
</Info>

## Configurar

<Steps>
  <Step title="Adicione a integração">
    Vá em **Configurações → Integrações → Adicionar → Hik-Partner Pro**.
  </Step>

  <Step title="Informe credenciais">
    Preencha nome do site, selecione a região, cole App Key e Secret Key.
  </Step>

  <Step title="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.
  </Step>
</Steps>

## 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:

| Capability | Suporte | Observação |
| - | - | - |
| Pessoas (CRUD) | ✅ | Via `/person/v1/persons/add/update/delete` |
| Cartão | ✅ | `/person/v1/persons/updatecards` |
| PIN | ✅ | `/person/v1/persons/updatepincode` |
| Face | ✅ | `/person/v1/persons/photo` (base64) |
| Digital | ✅ | `/person/v1/persons/updatefingers` (base64) |
| QR Code | ❌ | HPP não expõe canonicamente |
| Grupos de acesso | ✅ | `/acspm/v1/accesslevel/add` + `person/add` |
| Agendas | ⚠️ | Apenas IDs de templates pré-cadastrados no HPP |
| Captura de credencial | ❌ | Fase 2 — depende de polling de eventos |

### 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.

<Info>
  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.
</Info>

## 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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.