API BAS-IP Link: Como integrar o controlo de acesso e entrada de portas

Um novo residente é primeiramente configurado no sistema que a equipa de gestão já utiliza para os apartamentos, residentes e detalhes de contacto. Em seguida, a mesma pessoa é criada novamente, desta vez no sistema de intercomunicador (controlo de acessos). Os direitos de acesso mudam — dois sistemas precisam de ser atualizados. O residente muda-se — o registo tem de ser removido duas vezes.

Num único local, isso é simplesmente administração extra. Num portefólio de propriedades com mudanças regulares, alterações de acesso e passes temporários, torna-se um processo de gestão separado que ninguém realmente queria em primeiro lugar.

O que são o BAS-IP Link e a Link API?

O BAS-IP Link é a plataforma centralizada da BAS-IP para gerir locais, utilizadores, direitos de acesso e infraestruturas conectadas.

A BAS-IP Link API é uma API HTTP REST que permite que um sistema de servidor de terceiros interaja com o Link de forma programática: transmitindo dados de utilizadores, gerindo direitos e credenciais de acesso e recuperando dados da plataforma.

O objetivo não é dar à equipa mais um sistema para trabalhar. Muito pelo contrário: a plataforma existente do cliente pode continuar a ser a interface operacional principal, enquanto o BAS-IP passa a fazer parte dos processos que já são lá geridos.

Como é que isto funciona na prática? Adicionar um novo residente

A empresa de gestão já conhece o nome do residente, o apartamento, os detalhes de contacto e outras informações relevantes. Esses dados já existem no seu próprio sistema.

Sem uma integração, um membro da equipa tem de abrir o BAS-IP Link e criar o mesmo utilizador novamente.

Com a Link API, este segundo passo pode ser automatizado. O sistema principal passa os dados necessários para o Link, o utilizador é colocado no local e apartamento adequados, e o BAS-IP Link trabalha então com a infraestrutura de acesso e intercomunicador conectada.

O valor prático não é simplesmente que dois sistemas possam trocar dados. É que o pessoal não tem de mudar a forma como já trabalha.

Se as mudanças, as alterações aos detalhes dos residentes e as saídas já são geridas na plataforma principal, as mesmas ações não precisam de ser repetidas manualmente no sistema de controlo de acessos.

Por que usar a Link API quando os dispositivos BAS-IP têm a sua própria API?

A BAS-IP também suporta a integração direta com equipamentos através da BAS-IP Device API.

Para um projeto local, essa pode ser a abordagem certa. Se um sistema precisar de funcionar com um ou vários modelos de dispositivos conhecidos e exigir apenas um conjunto limitado de funções, uma camada de servidor adicional pode não ser necessária.

O requisito muda à medida que o projeto ganha escala.

Diferentes edifícios podem usar diferentes painéis de entrada, monitores interiores e outros dispositivos. Novos modelos e versões de firmware são introduzidos ao longo do tempo. Com uma integração direta de dispositivos, a equipa de desenvolvimento de terceiros precisa de levar em conta as características do equipamento com o qual se está a integrar.

O BAS-IP Link adiciona uma camada de software centralizada entre a plataforma de terceiros e a infraestrutura de controlo de acessos.

Em vez de construir a sua lógica de negócio em torno de um painel de entrada em particular, a plataforma externa trabalha com o modelo central do Link de utilizadores, locais, apartamentos, direitos de acesso e outras entidades.

Esse é geralmente um modelo mais natural para uma plataforma de gestão de propriedades residenciais. Normalmente não precisa de saber qual é exatamente o painel de entrada instalado numa porta específica. Precisa de saber que um determinado residente pertence a um determinado apartamento e deve ter acesso às áreas apropriadas.

O BAS-IP Link liga essa lógica de negócio à infraestrutura física de controlo de acesso e intercomunicador.

O que pode fazer através da BAS-IP Link API?

Uma integração em particular utilizará normalmente apenas uma parte da funcionalidade disponível no Link.

Através da API, um sistema de terceiros pode trabalhar com:

• utilizadores e estrutura do local;
• direitos de acesso;
• credenciais de acesso permanentes e temporárias, incluindo cartões, porta-chaves, códigos PIN, códigos QR, Face ID, UKEY e números de matrícula de veículos;
• acesso de convidados e visitantes;
• mensagens e inquéritos;
• números virtuais e reencaminhamento de chamadas;
• configuração remota de dispositivos;
• eventos e registos (logs).

No entanto, um projeto de integração é geralmente melhor definido por uma pergunta diferente de “Que métodos API estão disponíveis?”.

Que tarefas são realizadas manualmente hoje, e quais devem acontecer automaticamente após a integração dos sistemas?

Para uma plataforma, o principal caso de uso pode ser a gestão de residentes. Para outra, pode ser o acesso temporário a empreiteiros. Uma terceira pode precisar principalmente de dados de eventos.

Gerir todo o ciclo de vida do utilizador, não apenas a criação do utilizador

A criação de um utilizador é apenas o primeiro passo.

Uma vez adicionado um residente, os direitos de acesso e as credenciais apropriadas podem ser atribuídos. Se o residente se mudar para outro apartamento, mudar de veículo, receber permissões adicionais ou perder o acesso, essas alterações também podem fazer parte do fluxo de trabalho na plataforma principal.

O mesmo princípio aplica-se a utilizadores temporários.

Se um sistema existente já gere visitantes, empreiteiros ou pessoal de serviço, não há necessidade de criar um processo administrativo separado puramente para a BAS-IP.

Por exemplo, a plataforma principal pode determinar que um empreiteiro deve ser capaz de entrar num edifício na terça-feira entre as 10:00 e as 14:00. Nesse cenário, o BAS-IP torna-se a camada de acesso que executa um processo já definido noutro local.

O intercomunicador e o controlo de acesso tornam-se, assim, parte do modelo operacional mais amplo do edifício, em vez de um sistema separado que tem de ser administrado de forma independente.

E se o site já estiver ativo e tiver uma grande base de utilizadores?

Uma integração não começa necessariamente com uma base de dados vazia.

Se um sistema existente já contiver centenas ou milhares de residentes, eles não têm de ser introduzidos no BAS-IP Link manualmente um a um.

Ao usar a BAS-IP Link API, o método de criação de utilizadores pode adicionar vários utilizadores num único pedido.

Não são atualmente especificados um número máximo garantido de registos por operação e a frequência permitida de pedidos consecutivos. Para uma migração de grande escala, estes parâmetros devem, portanto, ser validados no ambiente de teste do projeto antes de migrar a base de utilizadores completa.

Os detalhes de implementação para o método da API são fornecidos aos parceiros de integração na documentação técnica.

Existe também uma opção integrada para a criação de utilizadores em massa sem o desenvolvimento de uma integração API.

O BAS-IP Link pode exportar a estrutura do local para um ficheiro XLS. Os detalhes do utilizador e da licença são depois preenchidos na folha de cálculo e importados novamente para o Link. Uma vez importados, os utilizadores são atribuídos automaticamente aos grupos de locais especificados. Onde vários utilizadores pertençam ao mesmo apartamento ou a outro grupo do local, linhas separadas podem usar o mesmo identificador de grupo.

Para uma implementação residencial inicial, não é necessário recolher um endereço de e-mail para todos os membros do agregado familiar. Um endereço de e-mail por apartamento é suficiente: o utilizador convidado recebe um e-mail, completa o registo e pode depois adicionar os membros da família de forma autónoma.

Para um desenvolvimento existente, a equipa do projeto pode assim escolher entre uma migração API automatizada e o processo integrado de carregamento em massa do Link, dependendo da arquitetura do sistema e de onde se encontra a base de dados de utilizadores de origem.

Os eventos BAS-IP podem ser usados num outro sistema?

Sim. Os dados e eventos mantidos no Link podem ser usados por um sistema de terceiros.

Por exemplo, uma equipa de segurança pode já trabalhar a partir de uma interface única que reúne informações de controlo de acessos, CCTV e outros sistemas do edifício. Os dados da BAS-IP podem fazer parte do mesmo fluxo de trabalho operacional.

Existe, no entanto, uma distinção técnica importante.

O BAS-IP Link não fornece atualmente webhooks para enviar eventos para sistemas de terceiros. O sistema externo recupera os dados necessários fazendo pedidos à Link API.

Se um projeto exigir que eventos específicos sejam entregues diretamente do equipamento através de webhooks, este cenário está disponível em painéis de entrada baseados em Android suportados através da BAS-IP Device API.

Um projeto pode, portanto, combinar a integração centralizada através do Link com a interação direta com dispositivos selecionados, quando necessário.

Qual o sistema que deve ser a fonte da verdade?

Uma das principais decisões numa integração é determinar qual o sistema responsável por cada tipo de dados.

Se o mesmo utilizador puder ser alterado independentemente, quer na plataforma de gestão de propriedades, quer no BAS-IP Link, os registos podem eventualmente tornar-se inconsistentes.

Por exemplo, a plataforma de gestão de propriedades pode permanecer responsável por residentes e apartamentos, o BAS-IP Link pode aplicar essas informações ao controlo de acesso e entrada, enquanto uma plataforma de segurança separada consome os dados dos eventos necessários para os operadores.

Um outro projeto poderá dividir as responsabilidades de forma diferente.

O ponto importante não é que a BAS-IP ou a plataforma de terceiros devam ser sempre o sistema “mestre”. É que a fonte autoritativa de cada entidade e a direção da sincronização devem ser claramente definidas.

É isso que elimina a duplicação na administração, e não apenas ligar duas bases de dados.

Onde é que a Link API é mais útil?

A Link API é particularmente relevante onde o BAS-IP precisa de fazer parte de um ecossistema de software já existente.

Alguns exemplos típicos incluem:

• plataformas de gestão de condomínios e imóveis residenciais;
• grandes sistemas de controlo de acesso;
• plataformas BMS e de edifícios inteligentes;
• produtos PropTech;
• plataformas de software dos próprios integradores;
• plataformas de gestão de vários edifícios ou locais.

Quantos mais utilizadores, edifícios e mudanças regulares de acesso um projeto tiver, mais a administração é duplicada quando os sistemas permanecen separados.

O valor da Link API não é, portanto, definido normalmente pelo número de métodos de API disponíveis, mas sim pelo número de processos operacionais separados que podem ser reunidos num só.

Segurança e permissões de integração

Um sistema de terceiros não precisa de acesso administrativo irrestrito ao Link.

No BAS-IP Link Self-Hosted, uma conta de integração dedicada pode ser criada e as suas permissões restringidas, quer por função, quer por local individual.

Por exemplo, uma integração usada por um determinado operador de imóveis pode ser limitada aos edifícios geridos por essa organização.

A autenticação usa tokens de acesso e a comunicação com a API decorre através de HTTPS.

O fluxo detalhado de autenticação e as estruturas de pedidos são abordados na documentação técnica da Link API.

BAS-IP Link Self-Hosted e Link Cloud

No momento da publicação, as integrações de lado de servidor (server-side) por terceiros através da BAS-IP Link API são suportadas no BAS-IP Link Self-Hosted.

A BAS-IP encontra-se a desenvolver um gateway de API separado para o BAS-IP Link Cloud.

Se um projeto requerer especificamente uma integração de terceiros com o Link Cloud, a arquitetura proposta deve ser discutida com a BAS-IP antes de se iniciar o desenvolvimento.

Como iniciar uma integração

Um projeto com a Link API começa pelo caso de uso em vez de uma lista de chamadas de API.

Por exemplo:

“Quando criamos um residente na nossa plataforma, queremos que o utilizador seja criado de forma automática no local BAS-IP correto.”

Isto basta para começar a debater a arquitetura.

Assim que o cenário de integração estiver estipulado, o parceiro assina um NDA e recebe os materiais técnicos relevantes.

A integração em si é, por norma, desenvolvida pela equipa do parceiro. Um projeto típico precisará geralmente de um programador back-end ou full-stack. Implementações maiores poderão também requerer a experiência em DevOps.

Para desenvolvimento e testes, o BAS-IP Link Self-Hosted pode ser implementado no próprio ambiente do parceiro. Neste momento, não existe nenhuma sandbox pública partilhada para a Link API. As licenças para teste e os preparativos de hardware são acordados conforme as exigências do projeto em causa.

A BAS-IP fornece a documentação, responde a questões técnicas sobre os seus próprios produtos e ajuda a investigar os casos em que uma implementação baseada na documentação não se comporte como se espera.

Se um projeto exigir funcionalidade não disponível neste momento no produto, esse requisito pode ser debatido com a equipa do produto. O trabalho envolvido e o seu enquadramento no plano de desenvolvimento são avaliados primeiro. Uma avaliação desse tipo não constitui, só por si, o compromisso com uma dada data de lançamento.

Quanto tempo demora uma integração com a Link API?

Não há apenas um intervalo de tempo único que se aplique a cada projeto.

Para uma integração relativamente padrão, usar cerca de um mês de desenvolvimento focado serve como orientação geral, ainda que a duração no calendário seja frequentemente maior.

A equipa de desenvolvimento do parceiro precisa de tempo para compreender o modelo de dados do Link, implementar a sua parte da integração, testá-la e enquadrar o trabalho no seu próprio cronograma de desenvolvimento.

Uma estimativa com sentido só pode assim ser feita depois de o cenário de integração real ter sido estipulado.

Existe algum custo adicional para a BAS-IP Link API?

A BAS-IP, regra geral, não cobra qualquer taxa separada pelo acesso às ferramentas de documentação e integração.

O próprio BAS-IP Link é licenciado sob o modelo padrão de licenciamento do produto. O parceiro desenvolve a sua própria parte da integração, enquanto o trabalho de desenvolvimento não padronizado da BAS-IP ou os pedidos de alteração da prioridade desse tipo de trabalho podem ser debatidos em separado sempre que necessário.

Por esse motivo, classificar a integração em si de “gratuita” pode gerar confusão.

O que é mais correto afirmar é que, regra geral, não se aplica uma tarifa em separado ao acesso às ferramentas de integração da BAS-IP.

Quando é que a Link API não é a abordagem certa?

A Link API destina-se principalmente à integração (server-side) com o BAS-IP Link.

Se o requisito for trabalhar diretamente com o equipamento específico, ou receber eventos diretamente de um painel de entrada, a BAS-IP Device API poderá ser a melhor escolha. A documentação sobre a integração dos dispositivos está disponível no portal público de programadores da BAS-IP.

Se uma dada organização tiver a sua própria aplicação para dispositivos móveis e quiser adicionar a possibilidade de receber chamadas do intercomunicador, obter um vídeo e abrir a porta com ela, será nesse momento que o BAS-IP Mobile SDK irá ser utilizado.

E quando bastar a interoperabilidade padrão através de SIP, RTSP ou Wiegand, poderá não ser de todo exigida uma integração personalizada do software.

As diferentes abordagens são explicadas em maior pormenorização na secção “Integração do intercomunicador IP BAS-IP IP aos sistemas de edifícios já existentes”.

Perguntas frequentes

A BAS-IP Link API é uma API REST?

Sim. A BAS-IP Link API é uma API REST HTTP que permite que o sistema servidor de uma parte terceira possa fazer uma interação de forma programática com o BAS-IP Link.

Preciso do BAS-IP Link para usar a Link API?

Sim. A Link API é a interface do programador no que concerne à plataforma do BAS-IP Link.

A BAS-IP Link API funciona com o Link Cloud?

No momento desta publicação, as integrações por terceiros na componente de servidor (server-side) com a Link API têm o seu suporte no BAS-IP Link Self-Hosted. A BAS-IP encontra-se a desenvolver um gateway API separado para o Link Cloud.

Como posso obter a documentação? É preciso um NDA?

O caso do uso da integração é estipulado primeiro. Depois disso, o parceiro deverá assinar um NDA antes de ser feita a entrega dos materiais e ferramentas a ele associadas.

Qual a diferença entre a Link API e a Mobile SDK?

A Link API tem como objetivo a integração de servidor com o BAS-IP Link, sendo onde se englobam utilizadores, sites, os devidos acessos, bem como as próprias entidades inerentes.

No entanto, a Mobile SDK do BAS-IP serve para um objetivo bem diferente, a qual consiste em dar mais funcionalidades ao intercomunicador tendo como base a plataforma para dispositivos móveis que seja utilizada.

No final de contas, quer um como o outro podem ser usados num único projeto, caso este o exija.

Quer integrar a sua plataforma com o BAS-IP Link?

Não há a necessidade de haver o preparativo de nenhuma funcionalidade detalhada inerente à API para ser feita a primeira abordagem.

Como princípio, e como deve ser feito, primeiro terá de haver uma apresentação com alguma profundidade do sistema e do seu mecanismo e o que se pretende automatizar.

Como exemplos:

“Temos como plataforma a criação de residentes e queremos que estes possam ser inseridos na BAS-IP de forma muito automatizada.”

Ou ainda:

“Temos um sistema próprio onde fazemos a gestão do acesso ao visitante e como seria óbvio pretendíamos ligá-lo com a BAS-IP”.

No que concerne à vertente de ajuda, a equipa da BAS-IP irá de facto ajudar a perceber, se no seu caso a Link API é a devida aproximação, assim como as funcionalidades e arquitetura.