> 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/defense-ia-english/implementation-tips/implementation-guide-bridge-module.md). # Implementation guide: Bridge module Bridge event synchronization, access-control integration, authentication, configuration, testing, and API quick reference. {% hint style="warning" %} **Bridge configuration requires an administrator profile and a license. If you do not have this module, contact the responsible sales representative.** {% endhint %} > **Important**\ > To show Bridge as connected in the platform client, continue calling **heartbeat** after authentication. ## Overview **Bridge** is a message-transfer service that enables real-time communication between **Defense IA** and third-party systems. It mediates event delivery, associated files, data synchronization, and operational commands. This decouples platform logic from each integrator's implementation. ### Supported capabilities * Reporting third-party events and triggering associations in the platform. * Sending events with images and videos asynchronously or synchronously. * Integrating with access-control platforms. * Synchronizing devices, organizations, person groups, and people. * Extracting access records, device offline statuses, and door statuses. ### Application scenarios **Full integration:** data and events transfer from the third-party system to Defense IA. Commands and operational associations are available. **Event synchronization:** only events, images, and videos are forwarded. Third-party registration data does not interact with Defense IA. ### Architecture at a glance ```mermaid %%{init: { "theme": "base", "themeVariables": { "primaryColor": "#00995D", "primaryTextColor": "#FFFFFF", "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" } }}%% flowchart LR D[Defense IA] <-->|Authorize/Heartbeat/Data/Control| B[Bridge] B <-->|SDK/API/WebService/Data/Alarm/Control| T[Third-party system] B --- P[Properties / Configuration] 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 ``` #### Architecture overview * **Defense IA** communicates with **Bridge** through standardized interfaces. * **Bridge** adapts the third-party system's protocol, payload, and logic. * The **third-party system** does not need to support Defense IA's internal format. * **Bridge** centralizes normalization, routing, and troubleshooting. ## Authentication and session maintenance The Bridge authorization flow with Defense IA uses **AK/SK + HMAC-SHA256**. Bridge sends `accessKey`, `timestamp`, and `signature` to `/ecos/api/v1.1/account/authorize`. The signature uses `HMAC_SHA256(timestamp, secretKey)`. After authentication, the platform returns a **token**. Include it in subsequent calls through this header: ``` X-Subject-Token: {token} ``` ### Operational sequence * **Authorize:** `POST /ecos/api/v1.1/account/authorize` with `accessKey`, `signature`, and `timestamp`. * **Optional configuration:** `GET /ecos/api/v1.1/bridge/{id}/config` retrieves secure third-party system connection parameters. * **Heartbeat:** `POST /ecos/api/v1.1/account/heartbeat` keeps Bridge online in the client. * **Update token:** call `POST /ecos/api/v1.1/account/token/update` before expiry. Run it at about 25 minutes. * **Fallback:** repeat `authorize` if the token expires. ### Flow ```mermaid %%{init: { "theme": "base", "themeVariables": { "primaryColor": "#00995D", "primaryTextColor": "#FFFFFF", "primaryBorderColor": "#007A4C", "lineColor": "#006B43", "secondaryColor": "#DFF5EC", "tertiaryColor": "#BFE9D6", "background": "#F6FFFB", "mainBkg": "#EAF8F1", "secondBkg": "#DFF5EC", "tertiaryBkg": "#CFEEDD", "actorBkg": "#00995D", "actorBorder": "#007A4C", "actorTextColor": "#FFFFFF", "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": "#FFFFFF" } }}%% sequenceDiagram participant B as Bridge participant D as Defense IA participant T as Third-party system B->>D: POST /ecos/api/v1.1/account/authorize Note over B,D: accessKey + timestamp + signature(HMAC-SHA256) D-->>B: token opt Retrieve optional configuration B->>D: GET /ecos/api/v1.1/bridge/{id}/config D-->>B: connection parameters end loop every ~25s B->>D: POST /ecos/api/v1.1/account/heartbeat D-->>B: 200 OK end loop before ~30min B->>D: POST /ecos/api/v1.1/account/token/update D-->>B: new token end alt token expired or invalid B->>D: POST /ecos/api/v1.1/account/authorize D-->>B: new token end ``` ### Reference implementation: Defense Bridge Client {% embed url="" %} This project is a Go client for testing and validating Defense IA Bridge integrations. It simplifies connection and event delivery. A web interface captures access parameters and abstracts the required HTTP calls. The application authenticates Bridge with `accessKey` and `secretKey` using `HMAC-SHA256`. It keeps the session active through `heartbeat`, periodically renews the token, retrieves a Bridge configuration by ID, and sends custom events to the event-push endpoint. Internally, the solution has a web layer (`internal/server`) for the interface and local API. Its integration layer (`internal/bridge`) manages session lifecycle, remote API use, event delivery, and in-memory operational logs. This implementation supports testing, validation, and troubleshooting of Bridge integrations. It is especially useful for quickly validating authentication, session maintenance, and custom event publishing. ### Main endpoints | Function | URI | Method | | ----------------- | ------------------------------------- | ------ | | Authentication | `/ecos/api/v1.1/account/authorize` | POST | | Get Bridge config | `/ecos/api/v1.1/bridge/{id}/config` | GET | | Update token | `/ecos/api/v1.1/account/token/update` | POST | | Heartbeat | `/ecos/api/v1.1/account/heartbeat` | POST | ### Signature rule ``` signature = HMAC_SHA256(timestamp, secretKey) headers["X-Subject-Token"] = token ``` ## Event synchronization Event synchronization has two parts: authentication with Defense IA and delivery of events converted by Bridge. The third-party system publishes an event to Bridge. Bridge converts its protocol and sends the compatible event to the platform. ### Bridge responsibilities * Reliably receive events from the third-party system. * Convert the protocol without changing the source data. * Send individual events or batches. * Send associated images and videos when available. * Record logs at suitable levels for support and troubleshooting. ### Simplified event synchronization flow ```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 Third-party system participant B as Bridge participant D as Defense IA T->>B: subscribe / push alarm Note over B: converts the event from the third-party format to the Defense IA format B->>D: POST /ecos/api/v1.1/bridge/event/push D-->>B: 200 OK opt associated files B->>D: POST /ecos/api/v1.1/bridge/event/file/push/batch D-->>B: 200 OK end opt high volume B->>D: POST /ecos/api/v1.1/bridge/event/push/batch D-->>B: 200 OK end ``` ### Event APIs | Function | URI | Method | | -------------------- | --------------------------------------------- | ------ | | Event push | `/ecos/api/v1.1/bridge/event/push` | POST | | Batch event push | `/ecos/api/v1.1/bridge/event/push/batch` | POST | | Image and video push | `/ecos/api/v1.1/bridge/event/file/push/batch` | POST | ### Minimum expected event structure ```json { "eventId": "{UUID}", "eventTime": 1615248000, "eventSourceCode": "1000005$1$0$2", "eventSourceName": "Entrance Door", "eventTypeCode": "51", "eventTypeName": "Valid Swipe", "remark": "This is an event" } ``` ### Platform configuration process * Add the Bridge project in the event-synchronization area. * Enter Bridge's name, IP address, port, and communication protocol. **HTTPS** is the operational standard. * Register the accepted event types and event sources. * Optionally register event-source statuses and types. * In the event center, configure types and sources for storage, notification, and video association. * Validate receipt in **Event History** or the real-time event view. ## Access-control platform integration Beyond event synchronization, Bridge can cover the full access-control integration lifecycle. This includes basic data synchronization, door commands, record reporting, events, device statuses, and door statuses. ### Access-control integration flow at a glance ```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[Third-party system] D -->|POST /bridge/api/v1.1/task/data/sync| B B -->|collects basic data| 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 -->|door command| 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 -->|queries records| 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 ``` ### Basic data synchronization Defense IA calls `/bridge/api/v1.1/task/data/sync` to trigger third-party data collection. Bridge must then synchronize all four data groups, even if one is empty. #### Data synchronization flow ```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 Third-party system D->>B: POST /bridge/api/v1.1/task/data/sync B->>T: request basic data T-->>B: organizations, devices, groups, people 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 ``` #### Synchronization APIs | Group | URI | Method | | ------------- | ---------------------------------------- | ------ | | Organizations | `/ecos/api/v1.1/organization/sync/batch` | POST | | Devices | `/ecos/api/v1.1/device/sync/batch` | PUT | | Person groups | `/ecos/api/v1.1/person-group/sync/batch` | PUT | | People | `/ecos/api/v1.1/person/sync/batch` | PUT | ### Door operations * Defense IA sends the command to Bridge through `/bridge/api/v1.1/device/door/control/batch`. * Bridge forwards the command to the third-party system. It controls retries and timeouts according to the integrator's logic. * Return the result to the platform through `/ecos/api/v1.1/device/door/control/report`. #### Door-control flow ```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 Third-party system D->>B: POST /bridge/api/v1.1/device/door/control/batch B->>T: open/close door alt command completed successfully T-->>B: OK result B->>D: PUT /ecos/api/v1.1/device/door/control/report D-->>B: 200 OK else timeout or failure B->>T: retransmission / retry T-->>B: error or no response B->>D: PUT /ecos/api/v1.1/device/door/control/report end ``` ### Access records * Bridge must expose `/bridge/api/v1.1/device/access-control/record/extract` for platform extraction requests. * After processing records, report the result through `/ecos/api/v1.1/device/access-control/record/report`. * The payload must include `taskId`, `extractType`, `completed`, `extractResult`, `extractIndex`, `errorMessage`, and the `records` collection. #### Record extraction flow ```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 Third-party system D->>B: POST /bridge/api/v1.1/device/door/control/batch B->>T: open/close door alt command completed successfully T-->>B: OK result B->>D: PUT /ecos/api/v1.1/device/door/control/report D-->>B: 200 OK else timeout or failure B->>T: retransmission / retry T-->>B: error or no response B->>D: PUT /ecos/api/v1.1/device/door/control/report end ``` ### Device and door statuses #### Status APIs | Function | URI | Method | | ------------------------------ | ------------------------------------------- | ------ | | Update device offline status | `/ecos/api/v1.1/device/status/update/batch` | POST | | Report door / operation status | `/ecos/api/v1.1/device/door/event/report` | PUT | #### Structure example ```json { "deviceStatus": [ { "deviceCodes": ["DEVICE001", "DEVICE002"], "status": "1", "offlineReason": "99" } ] } ``` ## Validation checklist 1. Create the Bridge project with the correct credentials, IP address, port, and protocol. 2. Validate connectivity between Defense IA, Bridge, and the third-party system. 3. Run `authorize`, `heartbeat`, and `update token` within the proper interval. 4. Register the event types and sources required for the scenario. 5. For access control, validate synchronization of organizations, devices, groups, and people. 6. Trigger real or simulated events in the third-party system. 7. Confirm events, history, records, and device states are received. 8. Review Bridge logs after authentication failures, timeouts, or payload mismatches. #### Validation flow ```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[Create Bridge project] --> B[Validate connectivity] B --> C[Run authorize] C --> D[Maintain heartbeat] D --> E[Update token] E --> F[Register types and sources] F --> G[Synchronize basic data] G --> H[Trigger events or commands] H --> I[Validate events, records, and statuses] I --> J[Review logs and correct mismatches] 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 ``` ## API quick reference
CategoryURIMethodNotes
Authentication/ecos/api/v1.1/account/authorizePOSTCreates the initial token
Session/ecos/api/v1.1/account/heartbeatPOSTKeeps Bridge online
Session/ecos/api/v1.1/account/token/updatePOSTRenews the token before expiry
Events/ecos/api/v1.1/bridge/event/pushPOSTIndividual event
Events/ecos/api/v1.1/bridge/event/push/batchPOSTBatch events
Event files/ecos/api/v1.1/bridge/event/file/push/batchPOSTImages and videos
Configuration/ecos/api/v1.1/bridge/{id}/configGETOptional third-party configuration
Data sync/bridge/api/v1.1/task/data/syncPOSTInterface provided by Bridge
Organization sync/ecos/api/v1.1/organization/sync/batchPOSTOrganizations
Device sync/ecos/api/v1.1/device/sync/batchPUTDevices
Group sync/ecos/api/v1.1/person-group/sync/batchPUTPerson groups
Person sync/ecos/api/v1.1/person/sync/batchPUTPeople
Door/bridge/api/v1.1/device/door/control/batchPOSTInterface provided by Bridge
Door/ecos/api/v1.1/device/door/control/reportPUTCommand result
Records/bridge/api/v1.1/device/access-control/record/extractPOSTRecord extraction
Records/ecos/api/v1.1/device/access-control/record/reportPOSTRecord reporting
Status/ecos/api/v1.1/device/status/update/batchPOSTOffline/online
Status/ecos/api/v1.1/device/door/event/reportPUTDoor status
## FAQ and quick diagnosis **Q: I cannot find the synchronization / synthesis menu in the client.**\ **A: Bridge configuration requires an administrator profile and a license. If you do not have this module, contact the responsible sales representative. Standard users cannot view or change this area.** **Q: Bridge remains disconnected.**\ **A:** After authentication, Bridge must continuously call the `heartbeat` endpoint. Without heartbeat, the client will not show an online status. **Q: Bridge does not go online even with heartbeat.**\ **A:** Review the configured protocol, IP address, port, reachability, and compatibility. The platform protocol must match the protocol Bridge uses. **HTTPS** is the operational standard. **Q: Events do not appear in the platform.**\ **A:** Validate that the event type and source are registered and associated with the correct project. Also confirm that the event payload uses the platform's accepted format. **Q: Door opening or closing has an issue.**\ **A:** Check the timeout, retransmission, command result in the third-party system, and result reporting at `/device/door/control/report`. *** --- # 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/defense-ia-english/implementation-tips/implementation-guide-bridge-module.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.