Integração Deskbee (BeeBadge)
A integração Deskbee conecta o ACCELERO ao agente BeeBadge da plataforma de gestão de espaços e reservas Deskbee. O agente roda on-premises, na mesma rede do servidor ACCELERO, e consome um conjunto de endpoints REST expostos por este plugin para sincronizar colaboradores e reservas confirmadas com o controle de acesso físico — criando pessoas, abrindo janelas de acesso e emitindo credenciais (RFID e QR Code) automaticamente.
Esta integração é disponibilizada como plugin (deskbee) e precisa ser instalada e habilitada pela equipe técnica da IONGRADE. Consulte o suporte para verificar compatibilidade com a sua versão do ACCELERO.
Versão atual do plugin: 1.0.3 — compatível com ACCELERO 2.17.0 ou superior.
O que a integração faz
O plugin não tem telas operacionais próprias: ele expõe uma API REST que o agente BeeBadge da Deskbee chama. O fluxo é sempre da Deskbee para o ACCELERO (a Deskbee é a origem das reservas e colaboradores), exceto a consulta de logs, em que a Deskbee lê os acessos registrados no ACCELERO.
| Funcionalidade | O que acontece no ACCELERO |
|---|---|
| Sincronização de usuários | Cria, atualiza ou desabilita a Pessoa correspondente ao colaborador/visitante da Deskbee, incluindo foto facial |
| Liberação de acesso (Grant) | Cria/atualiza um Evento com a janela de validade da reserva e vincula a pessoa; emite credenciais quando informadas |
| Emissão de credenciais | Gera Cartões RFID e/ou QR Code a partir dos dados da reserva, com validade própria por reserva |
| Revogação de acesso (Revoke) | Cancela o vínculo do evento, encurta a janela de acesso e desabilita as credenciais Deskbee da pessoa |
| Consulta de logs de acesso | Retorna os eventos de passagem das pessoas a partir de um horário informado |
| Health Check | Permite ao agente BeeBadge verificar se a integração está disponível e autenticada |
A reserva de espaço feita na Deskbee vira automaticamente liberação de acesso físico no ACCELERO — sem cadastro manual de pessoas, eventos ou cartões.
Configuração
Caminho de acesso: Configurações > Integrações - Deskbee
A tela possui três abas: Configurações, Credenciais e Avançado.
Tela de configuração da integração Deskbee, mostrando as três abas (Configurações, Credenciais e Avançado) e o título "Integração Deskbee".
Aba Configurações
| Campo | Descrição |
|---|---|
| Token Bearer (compartilhado com o agente BeeBadge) | Token usado para autenticar todas as chamadas da Deskbee à API (Authorization: Bearer <token>). Deve ser o mesmo valor configurado no agente BeeBadge |
| Tipo de Evento padrão | Tipo de evento (EventoTipo) usado ao criar o evento de acesso de cada reserva |
| Empresa (unidade) padrão | Empresa/unidade onde o evento é registrado. Também é usada como host (visitado) do vínculo e como empresa padrão da pessoa em Sync User |
| Categoria padrão (Sync User) | Categoria (PessoaCategoria) atribuída à pessoa quando ela é sincronizada. Campo opcional |
| Usuário da integração | Usuário do ACCELERO registrado como executor das operações do plugin (gravado nos eventos). Campo opcional |
O Token Bearer é o único mecanismo de autenticação da integração. Mantenha-o secreto e use um valor longo e aleatório. Sem o token correto, todas as chamadas retornam erro de autenticação.
Aba Credenciais
| Campo | Descrição |
|---|---|
| Tipo de cartão para RFID | Tipo de cartão (CartaoTipo) usado nas credenciais RFID. Padrão: CARTAO_VISIT (99) |
| Tipo de cartão para QR Code | Tipo de cartão usado nas credenciais de QR Code. Padrão: CARTAO_QR (98) |
Quando o payload Deskbee traz credential.facility_code + credential.card_number, o plugin grava o número do cartão como a concatenação facility_code + card_number e mantém os valores originais para auditoria.
Aba Avançado
| Campo | Descrição |
|---|---|
| Slot da foto facial (1–3) | Slot de foto da pessoa onde a imagem recebida da Deskbee é gravada. Padrão: 1 |
| Timeout download foto (ms) | Tempo máximo (em milissegundos) para baixar a foto da URL informada. Padrão: 8000 |
| Área padrão (opcional) | Área associada ao acesso. Quando vazio, não há filtro de área |
Se a foto não puder ser baixada dentro do timeout, a pessoa é salva mesmo assim (sem foto) e um aviso é registrado no log. O Grant não retorna erro por causa disso.
Botões da tela
| Botão | Função |
|---|---|
| Salvar | Persiste a configuração |
| Voltar | Retorna à listagem de configurações |
API REST
Todos os endpoints são chamados pelo agente BeeBadge e exigem o cabeçalho Authorization: Bearer <token> com o Token Bearer configurado.
| Operação | Método | Rota |
|---|---|---|
| Health Check | GET | /api/deskbee/health |
| Liberação de acesso (Grant) | POST | /api/deskbee/access/grant |
| Revogação de acesso (Revoke) | POST | /api/deskbee/access/revoke |
| Sincronização de usuário (Sync User) | POST | /api/deskbee/users/sync |
| Logs de acesso | GET | /api/deskbee/access/logs?since=<ISO8601> |
Códigos de status
| Código | Significado |
|---|---|
200 | Sucesso |
400 | Payload inválido (JSON, schema ou datas) |
401 | Token ausente/inválido ou configuração faltando |
404 | Pessoa não encontrada (apenas em Revoke) |
500 | Erro interno (registrado no log da aplicação) |
A configuração do endpoint, do token e o agendamento das chamadas são feitos no lado do agente BeeBadge da Deskbee. No ACCELERO, basta habilitar o plugin e preencher a tela de configuração. A especificação completa do contrato é definida em conjunto pela IONGRADE e pela Deskbee.
Como os dados são mapeados
O plugin traduz os conceitos da Deskbee para as entidades do ACCELERO.
| Conceito Deskbee | Entidade no ACCELERO |
|---|---|
| Colaborador / visitante | Pessoa |
Identificador (identifier, UUID) | Guardado nos metadados da pessoa — chave estável de correspondência |
Matrícula (enrollment) | Código da pessoa (pesCodigo) |
| Reserva confirmada (Grant) | Evento + vínculo da pessoa, com a janela de validade da reserva |
| Empresa padrão da pessoa | Vínculo pessoa–empresa pré-autorizado (criado apenas no Sync User) |
| Credencial RFID | Cartão do tipo configurado para RFID |
| QR Code | Cartão do tipo configurado para QR Code |
| Foto facial | Foto da pessoa no slot configurado |
Correspondência de pessoas
Ao receber um colaborador da Deskbee, o plugin procura uma pessoa já existente nesta ordem de prioridade:
- Identificador Deskbee (UUID) — chave estável e preferencial
- Matrícula (
enrollment/pesCodigo) - E-mail (
pesEmail)
Se nenhum critério corresponder, uma nova pessoa é criada.
O identificador (UUID) da Deskbee não muda mesmo que o nome, e-mail ou matrícula da pessoa sejam alterados. Usá-lo como chave principal evita duplicidades quando esses dados são atualizados.
Sincronização de usuários (Sync User)
Mantém o cadastro de pessoas do ACCELERO alinhado com os colaboradores da Deskbee. A operação recebe uma ação: criado, atualizado ou removido.
| Ação | Efeito no ACCELERO |
|---|---|
| Criado / Atualizado | Cria ou atualiza a pessoa (nome, e-mail, matrícula, foto), atribui a categoria padrão configurada e cria o vínculo com a empresa padrão |
| Removido | Desabilita a pessoa — os registros e credenciais não são apagados, apenas inativados |
Cadastro de uma pessoa criada pela Deskbee (Pessoas > Editar), evidenciando o nome, a matrícula (código), o e-mail e a foto facial sincronizados pela integração.
Liberação de acesso (Grant)
Cada reserva confirmada na Deskbee dispara um Grant, que cria ou atualiza o Evento de acesso da pessoa com a janela de validade da reserva (startDate / endDate).
A mesma rota atende a dois cenários, conforme os campos preenchidos no payload:
| Cenário | Campos enviados | O que o plugin faz |
|---|---|---|
| Colaborador (host) | Dados da pessoa + janela de validade | Cria/atualiza a pessoa e abre a janela de acesso. Foto e credenciais normalmente já vieram antes via Sync User |
| Visitante (guest) | Idem, mais QR Code e/ou credencial RFID | Idem, e ainda cria/atualiza os cartões (RFID e/ou QR Code) |
Um evento por pessoa, várias credenciais
- Evento único: cada pessoa tem um único evento ativo. Grants repetidos da mesma reserva atualizam o mesmo evento (a operação é idempotente — re-disparos não criam duplicatas, apenas ajustam a janela).
- Múltiplas credenciais simultâneas: uma pessoa pode acumular vários cartões ativos ao mesmo tempo (ex.: visitante com duas reservas distintas, cada uma com seu QR Code). Reenviar o mesmo número de cartão atualiza o cartão existente; um número diferente cria um novo, preservando os anteriores. Cada cartão tem sua própria validade, herdada da reserva que o originou.
Evento criado pela integração Deskbee (tela de Eventos/Visitas) mostrando a pessoa vinculada, a janela de validade e as credenciais associadas.
Revogação de acesso (Revoke)
Quando uma reserva é cancelada na Deskbee, o Revoke:
- Cancela o vínculo da pessoa com o evento;
- Encurta a janela do evento para o momento atual (encerrando o acesso);
- Desabilita todas as credenciais Deskbee da pessoa.
Hoje a revogação desabilita todas as credenciais Deskbee da pessoa de uma vez — não há revogação seletiva por cartão ou por reserva específica. Se a pessoa possui mais de uma reserva ativa, o Revoke encerra o acesso como um todo.
Logs de acesso
O endpoint de logs permite que a Deskbee consulte as passagens registradas no ACCELERO a partir de um horário informado (since, no formato ISO 8601).
Cada evento retornado traz: nome da pessoa, identificador interno, matrícula, e-mail, identificador Deskbee, data/hora do evento, tipo do evento (acesso liberado ou negado) e nome do dispositivo (canal) onde ocorreu.
A consulta retorna eventos de passagem de todas as pessoas a partir do horário informado, com limite de 500 registros por chamada. O identificador Deskbee só vem preenchido para pessoas sincronizadas pela integração; para as demais, vem em branco.
Casos de uso
Habilitar a integração para uma unidade
- Solicitar à IONGRADE a instalação do plugin
deskbee. - Gerar um Token Bearer longo e aleatório e configurá-lo nos dois lados (ACCELERO e agente BeeBadge).
- Em
Configurações > Integrações - Deskbee, na aba Configurações, preencher o token, o Tipo de Evento padrão e a Empresa (unidade) padrão. - Se necessário, ajustar os tipos de cartão na aba Credenciais e os parâmetros de foto na aba Avançado.
- Validar o canal com uma chamada de Health Check a partir do agente BeeBadge.
Liberar acesso para uma reserva
- O colaborador faz uma reserva na Deskbee.
- Ao confirmar, o agente BeeBadge chama o Grant.
- O ACCELERO cria/atualiza a pessoa, abre o evento com a janela da reserva e emite as credenciais informadas.
- A pessoa passa a ter acesso físico durante a validade da reserva.
Cancelar uma reserva
- A reserva é cancelada na Deskbee.
- O agente BeeBadge chama o Revoke.
- O ACCELERO encerra a janela do evento e desabilita as credenciais Deskbee da pessoa.
Boas práticas
- Token forte e secreto: use um token longo e aleatório, exclusivo desta integração, e troque-o se houver suspeita de vazamento.
- Empresa e tipo de evento dedicados: crie um Tipo de Evento e use uma unidade específicos para os acessos da Deskbee, facilitando a identificação e auditoria.
- Usuário de integração dedicado: configure um usuário do ACCELERO específico (ex.: "Integração Deskbee") como executor, em vez de uma conta nominal.
- Sincronizar antes de liberar: garanta que os colaboradores sejam sincronizados (Sync User) antes das reservas, para que foto e dados cadastrais já estejam presentes no momento do Grant.
Troubleshooting
Todas as chamadas retornam erro de autenticação (401)
Possíveis causas:
- Token do agente BeeBadge diferente do configurado no ACCELERO.
- Campo Token Bearer vazio ou configuração da integração incompleta.
Solução:
- Confirme que o token é idêntico nos dois lados (sem espaços extras).
- Verifique a aba Configurações da tela
Configurações > Integrações - Deskbee.
Pessoa duplicada após sincronização
Possíveis causas:
- O colaborador foi enviado sem identificador Deskbee, e a matrícula ou o e-mail mudaram entre as chamadas.
Solução:
- Garanta que o agente envie sempre o identificador (UUID) da Deskbee.
- Padronize matrícula e e-mail no cadastro de origem.
Pessoa criada sem foto
Possíveis causas:
- A URL da foto ficou indisponível ou o download estourou o tempo limite.
Solução:
- Aumente o Timeout download foto (ms) na aba Avançado.
- Verifique se o servidor ACCELERO alcança a URL da foto.
- Reenvie o Sync User da pessoa após corrigir o acesso à imagem.
Acesso continua ativo após cancelar reserva
Possíveis causas:
- O Revoke não foi disparado pelo agente, ou a pessoa não foi encontrada (404).
Solução:
- Confirme que o agente BeeBadge chamou o Revoke.
- Verifique se o identificador/matrícula/e-mail enviados correspondem a uma pessoa existente.
Integração com outros módulos
Pessoas e Categorias
A integração cria e atualiza Pessoas e pode atribuir uma categoria padrão a cada uma. O cadastro é mantido em sincronia com a Deskbee a cada operação.
Cartões / Credenciais
As credenciais RFID e QR Code são emitidas como cartões. Consulte Identificadores para entender os tipos de cartão usados pela integração.
Eventos
Cada reserva vira um Evento com a janela de validade da reserva.
Logs e Monitoramento
As passagens reportadas pelo endpoint de logs correspondem aos eventos registrados em Logs e Monitoramento.
Próximos Passos
- Pessoas — Entenda o cadastro mantido pela integração
- Identificadores — Saiba como funcionam os cartões emitidos
- Eventos — Veja como as reservas viram eventos de acesso
- Logs e Monitoramento — Entenda os eventos consultados pela Deskbee
- Plugins — Saiba mais sobre o sistema de plugins do ACCELERO