> For the complete documentation index, see [llms.txt](https://portal-integracao.intelbras.com.br/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://portal-integracao.intelbras.com.br/defense-ia-and-lite/dicas-de-implementacao/guia-de-implementacao-modulo-bridge.md). # Guia de implementação: Módulo Bridge Sincronização de eventos, integração com controle de acesso, autenticação, configuração, testes e referência rápida de APIs do Bridge. ## Defense IA: Bridge, guia de integração Este guia descreve como integrar sistemas de terceiros ao Defense IA por meio do Bridge: autenticação, sincronização de eventos, integração com controle de acesso, compatibilidade de versões e change-log. **Importante:** a configuração do Bridge exige perfil administrativo e uma licença para ser utilizada. Caso não possua este módulo, entre em contato com o comercial responsável. **Importante:** para o status do Bridge aparecer como conectado no cliente da plataforma, o heartbeat deve continuar sendo chamado após a autenticação. *** ### Compatibilidade de versões | Versão do Defense IA | Resumo | | --------------------- | ------------------------------------------------------------------- | | **3.0** | Primeira versão: sincronização de eventos | | **3.1** | Adiciona a integração com plataformas de controle de acesso | | **3.2 e posteriores** | Sincronização de eventos com obtenção de recursos de imagem e vídeo | #### Recursos por versão | Recurso | Defense 3.0 | Defense 3.1 | Defense 3.2+ | | ---------------------------------------------------------------------------- | :---------: | :---------: | :----------: | | Autenticação AK/SK, heartbeat e renovação de token | ✅ | ✅ | ✅ | | Sincronização de eventos | ✅ | ✅ | ✅ | | Integração com controle de acesso (dados básicos, portas, registros, status) | ❌ | ✅ | ✅ | | Envio de imagens e vídeos associados ao evento | ❌ | ❌ | ✅ | A versão do Defense IA define o que o Bridge pode fazer. Se a sua plataforma é anterior à 3.2, não use `/event/file/push/batch`. Se é anterior à 3.1, não há integração com controle de acesso. *** #### · Defense IA 3.2 e posteriores **Adicionado** * Sincronização de eventos: obtenção de recursos de imagem e vídeo associados ao evento. * Endpoint `POST /ecos/api/v1.1/bridge/event/file/push/batch` para enviar arquivos do evento (imagem, vídeo, áudio) por URL. * Campos `pictureCount` e `videoCount` no evento, para informar quantas mídias acompanham o evento. #### Defense IA 3.1 **Adicionado** * Integração de sistemas com plataformas de controle de acesso: * sincronização de organizações, dispositivos, grupos de pessoas e pessoas; * abrir e fechar portas a partir da plataforma; * extração e sincronização de registros de acesso e de alarme; * status offline de dispositivos e status de portas em tempo real. * Novo tipo de projeto no cliente: `Synthesis > System Integration`. #### Defense IA 3.0 **Primeira versão** * Autenticação por AK/SK com HMAC-SHA256, token, heartbeat e renovação de token. * Sincronização de eventos de sistemas de terceiros (`/event/push`), com vínculo de ação e de vídeo. * Projeto de sincronização de eventos no cliente: `Synthesis > Event Sync`. *** ### Visão geral O Bridge é uma estação de transferência de mensagens responsável por permitir comunicação em tempo real entre o Defense IA e sistemas de terceiros. Ele intermedia o envio de eventos, arquivos associados, sincronização de dados e comandos operacionais, desacoplando a lógica da plataforma da implementação específica de cada integrador. #### Capacidades suportadas * reporte de eventos de terceiros e acionamento de vínculos na plataforma; * envio assíncrono ou síncrono de eventos com imagens e vídeos *Defense 3.2+*; * integração com plataformas de controle de acesso *Defense 3.1+*; * sincronização de dispositivos, organizações, grupos de pessoas e pessoas; * extração de registros de acesso, status offline de dispositivos e status de portas. #### Cenários de aplicação | Cenário | O que faz | Interação com dados cadastrais | | ---------------------------- | --------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------- | | **Integração completa** | Dados e eventos são transferidos do sistema terceiro para o Defense IA, com possibilidade de comandos e vínculo operacional | Sim | | **Sincronização de eventos** | Apenas eventos, imagens e vídeos são encaminhados | Não há interação de dados cadastrais da plataforma de terceiros com o Defense IA | #### Arquitetura resumida ```mermaid %%{init: { "theme": "base", "themeVariables": { "primaryColor": "#00995D", "primaryTextColor": "#114B36", "primaryBorderColor": "#007A4C", "lineColor": "#006B43", "secondaryColor": "#DFF5EC", "tertiaryColor": "#BFE9D6", "background": "#F6FFFB", "mainBkg": "#EAF8F1", "secondBkg": "#DFF5EC", "tertiaryBkg": "#CFEEDD", "clusterBkg": "#F1FCF6", "clusterBorder": "#00995D", "defaultLinkColor": "#007A4C", "nodeBorder": "#007A4C", "fontFamily": "Arial", "textColor": "#114B36" } }}%% flowchart LR D[Defense IA] <-->|Authorize/Heartbeat/Data/Control| B[Bridge] B <-->|SDK/API/WebService/Data/Alarm/Control| T[Sistema terceiro] B --- P[Properties / Configurações] style D fill:#00995D,stroke:#007A4C,stroke-width:2px,color:#114B36 style B fill:#00A86B,stroke:#007A4C,stroke-width:2px,color:#114B36 style T fill:#E8FFF4,stroke:#00995D,stroke-width:2px,color:#114B36 style P fill:#DFF5EC,stroke:#00995D,stroke-width:2px,color:#114B36 linkStyle 0 stroke:#007A4C,stroke-width:2px linkStyle 1 stroke:#00995D,stroke-width:2px linkStyle 2 stroke:#5DAE8B,stroke-width:2px,stroke-dasharray: 5 5 ``` **Interpretação da arquitetura** * o Defense IA se comunica com o Bridge por interfaces padronizadas; * o Bridge adapta o protocolo, o payload e a lógica do sistema terceiro; * o sistema terceiro não precisa aderir nativamente ao formato interno do Defense IA; * o Bridge é o ponto central de normalização, roteamento e troubleshooting. *** ### Autenticação e manutenção de sessão O fluxo de autorização do Bridge com o Defense IA usa **AK/SK + HMAC-SHA256**. O Bridge envia `accessKey`, `timestamp` e `signature` para `/ecos/api/v1.1/account/authorize`. A assinatura é gerada por `HMAC_SHA256(timestamp, secretKey)`. Após a autenticação, a plataforma retorna um token (válido por 30 minutos) que deve ser incluído nas chamadas subsequentes por meio do header: ``` X-Subject-Token: {token} ``` #### Sequência operacional 1. **Authorize:** `POST /ecos/api/v1.1/account/authorize` com `accessKey`, `signature` e `timestamp`. 2. **Configuração (opcional):** `GET /ecos/api/v1.1/bridge/{id}/config` para obter parâmetros seguros de conexão do sistema terceiro. Os dados também podem ser definidos direto no arquivo de configuração do Bridge. 3. **Heartbeat:** `POST /ecos/api/v1.1/account/heartbeat` para manter o Bridge online na visão do cliente. 4. **Update token:** `POST /ecos/api/v1.1/account/token/update` antes do vencimento. Recomenda-se executar por volta de 25 minutos. O token anterior continua válido até expirar sozinho, o que evita perda de mensagens na troca. 5. **Fallback:** se o token expirar, repetir o authorize. #### Fluxo ```mermaid %%{init: { "theme": "base", "themeVariables": { "primaryColor": "#00995D", "primaryTextColor": "#114B36", "primaryBorderColor": "#007A4C", "lineColor": "#006B43", "secondaryColor": "#DFF5EC", "tertiaryColor": "#BFE9D6", "background": "#F6FFFB", "mainBkg": "#EAF8F1", "secondBkg": "#DFF5EC", "tertiaryBkg": "#CFEEDD", "actorBkg": "#DFF5EC", "actorBorder": "#00995D", "actorTextColor": "#114B36", "actorLineColor": "#006B43", "signalColor": "#007A4C", "signalTextColor": "#114B36", "labelBoxBkgColor": "#DFF5EC", "labelBoxBorderColor": "#00995D", "labelTextColor": "#114B36", "noteBkgColor": "#E8FFF4", "noteBorderColor": "#00A86B", "noteTextColor": "#114B36", "loopTextColor": "#114B36", "activationBorderColor": "#007A4C", "activationBkgColor": "#BFE9D6", "sequenceNumberColor": "#114B36", "textColor": "#114B36" } }}%% sequenceDiagram participant B as Bridge participant D as Defense IA participant T as Sistema terceiro B->>D: POST /ecos/api/v1.1/account/authorize Note over B,D: accessKey + timestamp + signature(HMAC-SHA256) D-->>B: token opt Obter configuração opcional B->>D: GET /ecos/api/v1.1/bridge/{id}/config D-->>B: parâmetros de conexão end loop a cada ~25s B->>D: POST /ecos/api/v1.1/account/heartbeat D-->>B: 200 OK end loop antes de ~30min B->>D: POST /ecos/api/v1.1/account/token/update D-->>B: novo token end alt token expirado ou inválido B->>D: POST /ecos/api/v1.1/account/authorize D-->>B: novo token end ``` #### Regra de assinatura ``` signature = HMAC_SHA256(timestamp, secretKey) headers["X-Subject-Token"] = token ``` #### Pontos de atenção * A regra de assinatura do Bridge precisa ser **idêntica** à da plataforma: `data` = timestamp e `key` = Secret Key. * No cliente, o Access Key aparece em texto puro, mas a Secret Key aparece cifrada. É preciso exibi-la em texto puro (informando a senha de login) para copiá-la para a configuração do Bridge. * O intervalo recomendado do heartbeat aparece com valores diferentes no manual (25 s em uma seção e 30 s em outra). Use **25 segundos**, que atende às duas recomendações. * O heartbeat é opcional para o envio de eventos, mas sem ele o Bridge não aparece como online no cliente. #### Resposta padrão Todas as respostas trazem `code` e `desc`. O código `1000` indica sucesso. ```json { "code": 1000, "desc": "Success" } ``` *** ### Implementação de referência: Defense Bridge Client Este projeto é um cliente de teste e homologação desenvolvido em Go para validar integrações com o Bridge do Defense IA. Seu objetivo é simplificar o processo de conexão e envio de eventos, oferecendo uma interface web para preenchimento dos parâmetros de acesso e abstraindo do operador as chamadas HTTP necessárias. {% embed url="" %} Ready to use {% endembed %} A aplicação realiza a autenticação no Bridge com `accessKey` e `secretKey` usando HMAC-SHA256, mantém a sessão ativa por heartbeat, executa renovação periódica do token, permite consultar a configuração de um Bridge por ID e enviar eventos customizados ao endpoint de event push. Internamente, a solução é dividida em duas camadas: | Camada | Pacote | Responsabilidade | | ---------- | ----------------- | ----------------------------------------------------------------------------------------------------------- | | Web | `internal/server` | Interface e API local | | Integração | `internal/bridge` | Ciclo de vida da sessão, consumo da API remota, envio de eventos e registro de logs operacionais em memória | Na prática, essa implementação funciona como uma referência útil para testes, homologação e troubleshooting de integrações com o Bridge, especialmente quando se deseja validar rapidamente autenticação, manutenção de sessão e publicação de eventos customizados. #### Endpoints do Defense consumidos pelo cliente | Função | Método | URI | | -------------------------------------------- | ------ | ------------------------------------- | | Autenticar | POST | `/ecos/api/v1.1/account/authorize` | | Consultar a configuração de um Bridge por ID | GET | `/ecos/api/v1.1/bridge/{id}/config` | | Heartbeat | POST | `/ecos/api/v1.1/account/heartbeat` | | Renovar o token | POST | `/ecos/api/v1.1/account/token/update` | | Enviar evento customizado | POST | `/ecos/api/v1.1/bridge/event/push` | *** ### Sincronização de eventos A sincronização de eventos é dividida em duas frentes: autenticação com o Defense IA e envio dos eventos convertidos pelo Bridge. O sistema terceiro publica o evento no Bridge. O Bridge converte o protocolo e envia o evento já compatibilizado para a plataforma. #### Responsabilidades do Bridge * receber eventos do sistema terceiro com confiabilidade; * converter o protocolo **sem descaracterizar o dado de origem**; * enviar eventos unitários ou em lote; * enviar imagens e vídeos associados quando existirem *(Bridge 1.1.1 / Defense 3.2+)*; * registrar logs em níveis adequados para suporte e troubleshooting (`debug` em desenvolvimento, `error` em operação). #### Fluxo simplificado de sincronização de eventos ```mermaid %%{init: { "theme": "base", "themeVariables": { "primaryColor": "#00995D", "primaryTextColor": "#114B36", "primaryBorderColor": "#007A4C", "lineColor": "#006B43", "secondaryColor": "#DFF5EC", "tertiaryColor": "#BFE9D6", "background": "#F6FFFB", "mainBkg": "#EAF8F1", "secondBkg": "#DFF5EC", "tertiaryBkg": "#CFEEDD", "actorBkg": "#DFF5EC", "actorBorder": "#00995D", "actorTextColor": "#114B36", "actorLineColor": "#006B43", "signalColor": "#007A4C", "signalTextColor": "#114B36", "labelBoxBkgColor": "#DFF5EC", "labelBoxBorderColor": "#00995D", "labelTextColor": "#114B36", "noteBkgColor": "#E8FFF4", "noteBorderColor": "#00A86B", "noteTextColor": "#114B36", "loopTextColor": "#114B36", "activationBorderColor": "#007A4C", "activationBkgColor": "#BFE9D6", "sequenceNumberColor": "#114B36", "textColor": "#114B36" } }}%% sequenceDiagram participant T as Sistema terceiro participant B as Bridge participant D as Defense IA T->>B: subscribe / push alarm Note over B: converte evento do formato terceiro para formato Defense IA B->>D: POST /ecos/api/v1.1/bridge/event/push D-->>B: 200 OK opt arquivos associados (Bridge 1.1.1) B->>D: POST /ecos/api/v1.1/bridge/event/file/push/batch D-->>B: 200 OK end opt alto volume B->>D: POST /ecos/api/v1.1/bridge/event/push/batch D-->>B: 200 OK end ``` #### APIs de evento | Função | Método | URI | | ------------------------------------------ | ------ | --------------------------------------------- | | Enviar evento | POST | `/ecos/api/v1.1/bridge/event/push` | | Enviar eventos em lote (alta concorrência) | POST | `/ecos/api/v1.1/bridge/event/push/batch` | | Enviar imagens e vídeos do evento | POST | `/ecos/api/v1.1/bridge/event/file/push/batch` | #### Estrutura mínima esperada no evento ```json { "eventId": "{UUID}", "eventTime": 1615248000, "eventSourceCode": "1000005$1$0$2", "eventSourceName": "Entrance Door", "eventTypeCode": "51", "eventTypeName": "Valid Swipe", "remark": "This is an event" } ``` #### Campos do evento | Campo | Obrigatório | Descrição | | ------------------- | :---------: | ----------------------------------------------------------------------------------------- | | `eventId` | Sim | Código do evento, único no sistema terceiro. Se o terceiro não tiver código, gere um UUID | | `eventTime` | Sim | Timestamp do evento, em segundos | | `eventSourceCode` | Sim | Código da origem do evento, igual ao cadastrado no projeto | | `eventTypeCode` | Sim | Código do tipo de evento, igual ao cadastrado no projeto | | `eventSourceName` | Não | Nome da origem. Se divergir do cadastro, **vale o cadastro** | | `eventTypeName` | Não | Nome do tipo. Se divergir do cadastro, **vale o cadastro** | | `eventSourceStatus` | Não | Status da origem do evento | | `pictureCount` | Não | Número de imagens do evento | | `videoCount` | Não | Número de vídeos do evento | | `userId` | Não | ID da pessoa | | `cardNo` | Não | Número do cartão | | `readerId` | Não | ID do leitor de cartão | | `remark` | Não | Observação | #### Envio de arquivos do evento *Defense 3.2+* O `associateId` precisa ser igual ao `eventId` do evento enviado. ```json { "associateId": "C6FF341F2B0D425BB78839E9E2606A", "files": [ { "fileUrl": "https://file.jpg", "fileType": "3", "recordTime": "", "fileTimeLength": "", "fileLength": "234" } ] } ``` | Campo | Obrigatório | Descrição | | ------------------------ | :---------: | ---------------------------------------------------------------------------------------------- | | `associateId` | Sim | Mesmo valor do `eventId` | | `files[].fileUrl` | Sim | Endereço externo do arquivo. Só há suporte a http(s), e a URL **não pode exigir autenticação** | | `files[].fileType` | Sim | `0` = desconhecido, `1` = vídeo, `2` = áudio, `3` = imagem | | `files[].recordTime` | Não | Início da gravação do vídeo, timestamp em segundos | | `files[].fileTimeLength` | Não | Duração do vídeo, em segundos | | `files[].fileLength` | Não | Tamanho do arquivo, em bytes | #### Processo de configuração na plataforma 1. Adicionar o projeto de Bridge na área de sincronização de eventos (`Synthesis > Event Sync > Add Now`). 2. Informar nome, IP, porta e protocolo de comunicação do Bridge. O padrão operacional é **HTTPS**. A plataforma gera o par de credenciais (AK/SK), que pode ser copiado e redefinido mediante a senha de login. 3. Cadastrar tipos de evento e fontes de evento que serão aceitos, um a um ou em lote. 4. Opcionalmente, cadastrar status e tipos das fontes de evento. 5. Configurar, no centro de eventos (`Event > Event Config > Add`), quais tipos e fontes terão armazenamento, notificação e vínculo de vídeo (**Linked Action** e **Linked Video**). 6. Homologar o recebimento em **Event History** ou na visão de eventos em tempo real (`Event Center > Real-time Event`). *** ### Integração com plataforma de controle de acesso Disponível a partir do **Defense IA 3.1**. Além da sincronização de eventos, o Bridge pode cobrir o ciclo completo de integração de controle de acesso: sincronização de dados básicos, envio de comandos de porta, reporte de registros, eventos, status de dispositivos e status de portas. Autenticação e push de eventos são **os mesmos** da sincronização de eventos. #### Fluxo resumido de integração com controle de acesso ```mermaid %%{init: { "theme": "base", "themeVariables": { "primaryColor": "#00995D", "primaryTextColor": "#114B36", "primaryBorderColor": "#007A4C", "lineColor": "#006B43", "secondaryColor": "#DFF5EC", "tertiaryColor": "#BFE9D6", "background": "#F6FFFB", "mainBkg": "#EAF8F1", "secondBkg": "#DFF5EC", "tertiaryBkg": "#CFEEDD", "clusterBkg": "#F1FCF6", "clusterBorder": "#00995D", "defaultLinkColor": "#007A4C", "nodeBorder": "#007A4C", "fontFamily": "Arial", "textColor": "#114B36" } }}%% flowchart TD D[Defense IA] B[Bridge] T[Sistema terceiro] D -->|POST /bridge/api/v1.1/task/data/sync| B B -->|coleta dados básicos| T B -->|POST /ecos/api/v1.1/organization/sync/batch| D B -->|PUT /ecos/api/v1.1/device/sync/batch| D B -->|PUT /ecos/api/v1.1/person-group/sync/batch| D B -->|PUT /ecos/api/v1.1/person/sync/batch| D D -->|POST /bridge/api/v1.1/device/door/control/batch| B B -->|comando de porta| T B -->|PUT /ecos/api/v1.1/device/door/control/report| D D -->|POST /bridge/api/v1.1/device/access-control/record/extract| B B -->|consulta registros| T B -->|POST /ecos/api/v1.1/device/access-control/record/report| D style D fill:#00995D,stroke:#007A4C,stroke-width:2px,color:#114B36 style B fill:#00A86B,stroke:#007A4C,stroke-width:2px,color:#114B36 style T fill:#E8FFF4,stroke:#00995D,stroke-width:2px,color:#114B36 ``` Neste guia, `/ecos/...` são endpoints **do Defense** (o Bridge chama) e `/bridge/...` são endpoints **que o Bridge precisa expor** (o Defense chama). #### Sincronização de dados básicos O Defense IA chama `/bridge/api/v1.1/task/data/sync` para disparar a coleta de dados do terceiro. Após isso, o Bridge deve sincronizar os **quatro** grupos de dados, **mesmo quando algum deles estiver vazio**. Só então a tarefa de sincronização é concluída. A sincronização pode ser manual (**Manually Collect**) ou automática (**Auto Collect Data**, todo dia às 00:00, horário configurável no projeto). **Fluxo de sincronização de dados** ```mermaid %%{init: { "theme": "base", "themeVariables": { "primaryColor": "#00995D", "primaryTextColor": "#114B36", "primaryBorderColor": "#007A4C", "lineColor": "#006B43", "secondaryColor": "#DFF5EC", "tertiaryColor": "#BFE9D6", "background": "#F6FFFB", "mainBkg": "#EAF8F1", "secondBkg": "#DFF5EC", "tertiaryBkg": "#CFEEDD", "actorBkg": "#DFF5EC", "actorBorder": "#00995D", "actorTextColor": "#114B36", "actorLineColor": "#006B43", "signalColor": "#007A4C", "signalTextColor": "#114B36", "labelBoxBkgColor": "#DFF5EC", "labelBoxBorderColor": "#00995D", "labelTextColor": "#114B36", "noteBkgColor": "#E8FFF4", "noteBorderColor": "#00A86B", "noteTextColor": "#114B36", "loopTextColor": "#114B36", "activationBorderColor": "#007A4C", "activationBkgColor": "#BFE9D6", "sequenceNumberColor": "#114B36", "textColor": "#114B36" } }}%% sequenceDiagram participant D as Defense IA participant B as Bridge participant T as Sistema terceiro D->>B: POST /bridge/api/v1.1/task/data/sync B->>T: solicitar dados básicos T-->>B: organizações, dispositivos, grupos, pessoas B->>D: POST /ecos/api/v1.1/organization/sync/batch D-->>B: 200 OK B->>D: PUT /ecos/api/v1.1/device/sync/batch D-->>B: 200 OK B->>D: PUT /ecos/api/v1.1/person-group/sync/batch D-->>B: 200 OK B->>D: PUT /ecos/api/v1.1/person/sync/batch D-->>B: 200 OK ``` **APIs de sincronização** | Função | Quem oferece | Método | URI | | ------------------------------------------- | ------------ | ------ | ---------------------------------------- | | Disparar a tarefa de sincronização de dados | Bridge | POST | `/bridge/api/v1.1/task/data/sync` | | Sincronizar organizações de dispositivos | Defense | POST | `/ecos/api/v1.1/organization/sync/batch` | | Sincronizar dispositivos | Defense | PUT | `/ecos/api/v1.1/device/sync/batch` | | Sincronizar grupos de pessoas | Defense | PUT | `/ecos/api/v1.1/person-group/sync/batch` | | Sincronizar pessoas | Defense | PUT | `/ecos/api/v1.1/person/sync/batch` | **Regras de ordem e comportamento** * Sincronize **primeiro as organizações e depois os dispositivos**, e **primeiro os grupos de pessoas e depois as pessoas**. * O módulo **Device** não exibe os dispositivos de terceiros. Eles aparecem em módulos como Monitoring Center e Access Control. * Dispositivos de acesso de terceiros **geram pontos de acesso automaticamente**, mas **não é possível configurar regras de acesso** para eles. * Pessoas de terceiros não podem ser movidas, ter o grupo removido nem ter dados básicos editados na plataforma. A informação delas **pode ser enviada** aos dispositivos do Defense IA. Para alterar dados básicos, altere no terceiro e sincronize pelo Bridge. * É possível arrastar o ponto de acesso para o mapa. Quando um alarme é reportado, o mapa pisca. **Campos principais de dispositivo** | Campo | Obrigatório | Descrição | | ------------------------ | :---------: | -------------------------------------------------------- | | `addType` | Sim | Forma de adição: `1` = endereço IP, `4` = registro ativo | | `deviceName` | Sim | Nome do dispositivo | | `deviceCategory` | Sim | Categoria do dispositivo | | `deviceType` | Sim | Subcategoria do dispositivo | | `associateId` | Sim | ID do dispositivo no terceiro | | `orgCode` | Sim | Código da organização do dispositivo | | `deviceIp`, `devicePort` | Não | IP e porta | | `registerId` | Não | Obrigatório quando o acesso é por P2P ou registro ativo | | `accessChannelCount` | Não | Número de canais de controle de acesso | #### Operações de porta * o Defense IA envia o comando ao Bridge por `/bridge/api/v1.1/device/door/control/batch`; * o Bridge encaminha o comando ao sistema terceiro e controla tentativas e timeout conforme a lógica do integrador; * o resultado deve ser devolvido à plataforma por `/ecos/api/v1.1/device/door/control/report`. Se o número de retransmissões passar do limite, ou não houver retorno de sucesso após o timeout, o comando **falha**. O Bridge deve registrar a operação em log para diagnóstico. **Fluxo de controle de porta** ```mermaid %%{init: { "theme": "base", "themeVariables": { "primaryColor": "#00995D", "primaryTextColor": "#114B36", "primaryBorderColor": "#007A4C", "lineColor": "#006B43", "secondaryColor": "#DFF5EC", "tertiaryColor": "#BFE9D6", "background": "#F6FFFB", "mainBkg": "#EAF8F1", "secondBkg": "#DFF5EC", "tertiaryBkg": "#CFEEDD", "actorBkg": "#DFF5EC", "actorBorder": "#00995D", "actorTextColor": "#114B36", "actorLineColor": "#006B43", "signalColor": "#007A4C", "signalTextColor": "#114B36", "labelBoxBkgColor": "#DFF5EC", "labelBoxBorderColor": "#00995D", "labelTextColor": "#114B36", "noteBkgColor": "#E8FFF4", "noteBorderColor": "#00A86B", "noteTextColor": "#114B36", "loopTextColor": "#114B36", "activationBorderColor": "#007A4C", "activationBkgColor": "#BFE9D6", "sequenceNumberColor": "#114B36", "textColor": "#114B36" } }}%% sequenceDiagram participant D as Defense IA participant B as Bridge participant T as Sistema terceiro D->>B: POST /bridge/api/v1.1/device/door/control/batch B->>T: abrir/fechar porta alt comando executado com sucesso T-->>B: resultado OK B->>D: PUT /ecos/api/v1.1/device/door/control/report D-->>B: 200 OK else timeout ou falha B->>T: retransmissão / nova tentativa T-->>B: erro ou sem retorno B->>D: PUT /ecos/api/v1.1/device/door/control/report end ``` **Valores de operação e de resultado** | Campo | Valores | | --------------- | ------------------------------------------------------------------------------------- | | `operateType` | `1` = abrir, `2` = fechar, `3` = sempre fechado, `4` = sempre aberto, `5` = restaurar | | `operateResult` | `1` = sucesso, `2` = falha | | `failedReason` | `1` = a plataforma de terceiros não suporta, `2` = falha ao enviar o comando | O campo `session`, recebido no comando, deve ser devolvido no reporte do resultado. #### Registros de acesso * o Bridge deve expor `/bridge/api/v1.1/device/access-control/record/extract` para que a plataforma solicite a extração; * após processar os registros, o retorno deve ser reportado em `/ecos/api/v1.1/device/access-control/record/report`; * o payload deve contemplar `taskId`, `extractType`, `completed`, `extractResult`, `extractIndex`, `errorMessage` e a coleção `records`. **Fluxo de extração de registros** ```mermaid %%{init: { "theme": "base", "themeVariables": { "primaryColor": "#00995D", "primaryTextColor": "#114B36", "primaryBorderColor": "#007A4C", "lineColor": "#006B43", "secondaryColor": "#DFF5EC", "tertiaryColor": "#BFE9D6", "background": "#F6FFFB", "mainBkg": "#EAF8F1", "secondBkg": "#DFF5EC", "tertiaryBkg": "#CFEEDD", "actorBkg": "#DFF5EC", "actorBorder": "#00995D", "actorTextColor": "#114B36", "actorLineColor": "#006B43", "signalColor": "#007A4C", "signalTextColor": "#114B36", "labelBoxBkgColor": "#DFF5EC", "labelBoxBorderColor": "#00995D", "labelTextColor": "#114B36", "noteBkgColor": "#E8FFF4", "noteBorderColor": "#00A86B", "noteTextColor": "#114B36", "loopTextColor": "#114B36", "activationBorderColor": "#007A4C", "activationBkgColor": "#BFE9D6", "sequenceNumberColor": "#114B36", "textColor": "#114B36" } }}%% sequenceDiagram participant D as Defense IA participant B as Bridge participant T as Sistema terceiro D->>B: POST /bridge/api/v1.1/device/access-control/record/extract Note over D,B: taskId, beginTime, endTime, deviceCodes, extractType, eventTypes B-->>D: 200 OK B->>T: consultar registros do período T-->>B: registros loop por lote (extractIndex = 1, 2, ...) B->>D: POST /ecos/api/v1.1/device/access-control/record/report Note over B,D: completed, extractResult, errorMessage, records D-->>B: 200 OK end ``` **Valores principais** | Campo | Valores | | --------------- | ---------------------------------------------------------------------------------------- | | `extractType` | `1` = registros de acesso, `2` = registros de alarme. Se vazio na extração, traz os dois | | `completed` | `0` = não concluída, `1` = concluída | | `extractResult` | `0` = falhou, `1` = sucesso | | `extractIndex` | Lote da extração, começando em `1` | A extração pode ser automática ou manual (`Access Management > Access Records > Acquire Records`, com **Extract by Range** para período, tipo e dispositivo). A plataforma pede a senha do Defense antes de obter os registros. #### Status de dispositivo e status de porta **APIs de status** | Função | Método | URI | | --------------------------------------------------------------------------------------------- | ------ | ------------------------------------------- | | Enviar o status online/offline do dispositivo | POST | `/ecos/api/v1.1/device/status/update/batch` | | Enviar o resultado de abertura/fechamento de porta (status da porta para eventos do terceiro) | PUT | `/ecos/api/v1.1/device/door/event/report` | **Exemplo de estrutura** ```json { "deviceStatus": [ { "deviceCodes": ["DEVICE001", "DEVICE002"], "status": "1", "offlineReason": "99" } ] } ``` `status`: `0` = offline, `1` = online. Para dispositivos offline, use `"0"`. *** ### Roteiro de homologação 1. criar o projeto de Bridge na plataforma com credenciais, IP, porta e protocolo corretos; 2. validar conectividade entre Defense IA, Bridge e sistema terceiro; 3. executar authorize, heartbeat e update token dentro da janela correta; 4. cadastrar tipos e fontes de evento necessários para o cenário; 5. para controle de acesso, validar sincronização de organizações, dispositivos, grupos e pessoas; 6. disparar eventos reais ou simulados no sistema terceiro; 7. confirmar recebimento dos eventos em tempo real, histórico, registros e estados de dispositivo; 8. analisar logs do Bridge sempre que houver falha de autenticação, timeout ou divergência de payload. Na plataforma, configure também o **esquema de evento** em `App Config > Event`: crie um esquema por evento disparado e, na **Linked Action**, marque **Notify User** para definir quem recebe o evento. Se a sincronização de dispositivos ou pessoas ficar incorreta, use **View List of Failures** no projeto (`Synthesis > System Integration`) para ver a causa. #### Fluxo de homologação ```mermaid %%{init: { "theme": "base", "themeVariables": { "primaryColor": "#00995D", "primaryTextColor": "#114B36", "primaryBorderColor": "#007A4C", "lineColor": "#006B43", "secondaryColor": "#DFF5EC", "tertiaryColor": "#BFE9D6", "background": "#F6FFFB", "mainBkg": "#EAF8F1", "secondBkg": "#DFF5EC", "tertiaryBkg": "#CFEEDD", "clusterBkg": "#F1FCF6", "clusterBorder": "#00995D", "defaultLinkColor": "#007A4C", "nodeBorder": "#007A4C", "fontFamily": "Arial", "textColor": "#114B36" } }}%% flowchart TD A[Criar projeto de Bridge] --> B[Validar conectividade] B --> C[Executar authorize] C --> D[Manter heartbeat] D --> E[Atualizar token] E --> F[Cadastrar tipos e fontes] F --> G[Sincronizar dados básicos] G --> H[Disparar eventos ou comandos] H --> I[Validar eventos, registros e status] I --> J[Analisar logs e corrigir divergências] style A fill:#E8FFF4,stroke:#00995D,stroke-width:2px,color:#114B36 style B fill:#DFF5EC,stroke:#00995D,stroke-width:2px,color:#114B36 style C fill:#DFF5EC,stroke:#00995D,stroke-width:2px,color:#114B36 style D fill:#DFF5EC,stroke:#00995D,stroke-width:2px,color:#114B36 style E fill:#DFF5EC,stroke:#00995D,stroke-width:2px,color:#114B36 style F fill:#DFF5EC,stroke:#00995D,stroke-width:2px,color:#114B36 style G fill:#DFF5EC,stroke:#00995D,stroke-width:2px,color:#114B36 style H fill:#DFF5EC,stroke:#00995D,stroke-width:2px,color:#114B36 style I fill:#DFF5EC,stroke:#00995D,stroke-width:2px,color:#114B36 style J fill:#00995D,stroke:#007A4C,stroke-width:2px,color:#114B36 ``` *** ### Referência rápida de APIs Todas as APIs do Defense usam o prefixo `/ecos/api/v1.1`. As APIs que o Bridge expõe usam `/bridge/api/v1.1`. #### Defense (o Bridge chama) | Função | Método | URI | | --------------------------------------------- | ------ | ---------------------------------------------------- | | Autenticar (AK/SK) | POST | `/ecos/api/v1.1/account/authorize` | | Renovar o token | POST | `/ecos/api/v1.1/account/token/update` | | Heartbeat | POST | `/ecos/api/v1.1/account/heartbeat` | | Obter a configuração do Bridge | GET | `/ecos/api/v1.1/bridge/{id}/config` | | Enviar evento | POST | `/ecos/api/v1.1/bridge/event/push` | | Enviar eventos em lote | POST | `/ecos/api/v1.1/bridge/event/push/batch` | | Enviar arquivos do evento | POST | `/ecos/api/v1.1/bridge/event/file/push/batch` | | Sincronizar organizações de dispositivos | POST | `/ecos/api/v1.1/organization/sync/batch` | | Sincronizar dispositivos | PUT | `/ecos/api/v1.1/device/sync/batch` | | Sincronizar grupos de pessoas | PUT | `/ecos/api/v1.1/person-group/sync/batch` | | Sincronizar pessoas | PUT | `/ecos/api/v1.1/person/sync/batch` | | Reportar o resultado de comando de porta | PUT | `/ecos/api/v1.1/device/door/control/report` | | Reportar registros de acesso ou alarme | POST | `/ecos/api/v1.1/device/access-control/record/report` | | Enviar status online/offline de dispositivo | POST | `/ecos/api/v1.1/device/status/update/batch` | | Enviar status de abertura/fechamento de porta | PUT | `/ecos/api/v1.1/device/door/event/report` | #### Bridge (o Defense chama, o Bridge precisa expor) | Função | Método | URI | | ----------------------------------------- | ------ | ------------------------------------------------------- | | Executar a sincronização de dados básicos | POST | `/bridge/api/v1.1/task/data/sync` | | Receber comandos de porta | POST | `/bridge/api/v1.1/device/door/control/batch` | | Extrair registros de acesso ou alarme | POST | `/bridge/api/v1.1/device/access-control/record/extract` | *** ### FAQ e diagnóstico rápido **Q: Não encontro o menu de sincronização / Synthesis no client.** A: A configuração do Bridge exige perfil administrativo e uma licença para ser utilizada. Caso não possua este módulo, entre em contato com o comercial responsável. Usuários comuns não têm permissão para ver ou alterar essa área. **Q: O Bridge permanece como desconectado.** A: Após a autenticação, o Bridge deve chamar continuamente o endpoint de heartbeat. Sem heartbeat, o cliente não apresentará o status online. **Q: O Bridge não fica online mesmo com heartbeat.** A: Revisar protocolo configurado, IP, porta, reachability e compatibilidade entre o protocolo configurado na plataforma e o protocolo efetivamente usado pelo Bridge. HTTPS é o padrão operacional. **Q: A autenticação do Bridge falha.** A: Confirmar que o Access Key e a Secret Key (em texto puro) foram copiados para a configuração do Bridge e que a assinatura usa `HMAC-SHA256(timestamp, secretKey)`. Depois de autenticar, chamar `/token/update` periodicamente, porque o token vale só 30 minutos. **Q: Os eventos não aparecem na plataforma.** A: Validar se o tipo e a fonte do evento foram cadastrados e vinculados ao projeto correto. Confirmar também se o payload do evento foi convertido para o formato aceito pela plataforma, e se o esquema de evento tem **Notify User** configurado. No Bridge, aumentar o nível de log e confirmar se o evento chegou do terceiro e foi enviado ao Defense IA. **Q: Imagens e vídeos do evento não aparecem.** A: Confirmar que a plataforma é Defense IA 3.2 ou posterior (Bridge 1.1.1), que o `associateId` é igual ao `eventId` e que a `fileUrl` é http(s) acessível **sem autenticação**. **Q: A vinculação de gravação está configurada, mas nenhum vídeo é gravado quando o evento ocorre.** A: Costuma ser diferença de horário entre o servidor do Bridge e o do Defense IA. Recomenda-se instalar o Bridge no mesmo servidor do Defense IA. **Q: Há problema com abertura/fechamento de portas.** A: Verificar timeout, retransmissão, resultado de comando no sistema terceiro e reporte do resultado em `/device/door/control/report`. **Q: Como sincronizar mudanças de dispositivos e pessoas feitas no terceiro?** A: Na página de integração do projeto, clicar em **Manual Collect**. Também há a coleta automática diária às 00:00. **Q: Como verificar se uma porta de rede está ocupada (Windows)?** A: Executar `netstat -ano | find "porta"`. Se houver resultado, a porta está em uso. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://portal-integracao.intelbras.com.br/defense-ia-and-lite/dicas-de-implementacao/guia-de-implementacao-modulo-bridge.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.