Integração AppToHome
A integração AppToHome conecta o ACCELERO à plataforma AppToHome, um aplicativo de gestão de condomínios e empreendimentos. Com o plugin ativo, o AppToHome passa a comandar cadastros de moradores, convites de visita e geração de QR Codes diretamente no ACCELERO, enquanto o ACCELERO devolve as movimentações de acesso (entradas e saídas) ao aplicativo.
A comunicação é bidirecional: o AppToHome chama a API do ACCELERO para criar e manter dados, e o ACCELERO notifica o AppToHome quando ocorre uma passagem física nas áreas monitoradas.
Esta integração é disponibilizada como plugin (apptohome) 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.0 — compatível com ACCELERO 2.17.0 ou superior.
O que a integração faz
O AppToHome atua como sistema de origem dos cadastros: ele envia os dados de moradores e convites para o ACCELERO via API, e o ACCELERO mantém pessoas, vínculos com unidades e eventos de visita sincronizados. Na direção inversa, o ACCELERO reporta cada acesso relevante de volta ao AppToHome.
| Funcionalidade | O que acontece no ACCELERO |
|---|---|
| Cadastro de morador | O AppToHome cria ou atualiza a pessoa no ACCELERO e a associa à unidade (empresa) correspondente |
| Desativação de morador | O AppToHome solicita o desligamento de uma pessoa, que é desabilitada no cadastro |
| Geração de QR Code | O ACCELERO gera o QR Code (estático ou dinâmico) da pessoa e devolve ao AppToHome |
| Convite de visita | O AppToHome cria um evento de visita vinculando visitante e morador visitado, e o ACCELERO emite um cartão virtual (QR Code) para o visitante |
| Cancelamento de convite | O AppToHome cancela o convite; o evento e o vínculo do visitante são cancelados no ACCELERO |
| Consulta de tipos de evento | O AppToHome lê a lista de tipos de evento configurados no ACCELERO |
| Consulta de unidades | O AppToHome lê a lista de empresas (unidades) cadastradas no ACCELERO |
| Notificação de acessos | Cada passagem física por uma área de entrada ou saída configurada é reportada ao AppToHome |
Centraliza no AppToHome a gestão de moradores e convites, enquanto o controle de acesso físico, a emissão de credenciais (QR Code) e o registro das passagens permanecem no ACCELERO.
Configuração
Caminho de acesso: Configurações > Integrações - AppToHome
A tela de configuração possui a aba Geral.
Tela Configurações > Integrações - AppToHome, aba Geral, mostrando os campos Operador, Token de autenticação, URL AppToHome, o switch "Sobrescrever dados de pessoas existentes", "Associação de novos moradores" e as listas "Áreas de entrada" e "Áreas de saída".
Aba Geral
| Campo | Descrição |
|---|---|
| Operador | Operador do ACCELERO em nome do qual as operações recebidas via API são executadas. As ações criadas pela integração (eventos, vínculos) ficam registradas sob este operador |
| Token de autenticação (Access Key) | Token usado para autenticar as chamadas que o AppToHome faz à API do ACCELERO. Deve ser enviado pelo AppToHome no cabeçalho Authorization de cada requisição |
| URL AppToHome | Endpoint do serviço AppToHome para onde o ACCELERO envia as notificações de acesso |
| Sobrescrever dados de pessoas existentes | Quando ativado, os dados (nome, documento, e-mail, telefone e foto) de uma pessoa já cadastrada são atualizados a cada cadastro recebido do AppToHome. Quando desativado, apenas pessoas novas têm os dados preenchidos |
| Associação de novos moradores | Tipo de associação (vínculo pessoa-empresa) aplicado ao vincular um novo morador à sua unidade |
| Áreas de entrada | Multi-seleção de áreas — passagens com destino a uma dessas áreas são reportadas ao AppToHome como entrada |
| Áreas de saída | Multi-seleção de áreas — passagens com destino a uma dessas áreas são reportadas ao AppToHome como saída |
O Token de autenticação (Access Key) protege a API exposta pelo plugin. Chamadas sem o token correto no cabeçalho Authorization são rejeitadas com erro de não autorizado. Compartilhe o token apenas com o serviço AppToHome.
Apenas passagens cujo destino seja uma área marcada em Áreas de entrada ou Áreas de saída geram notificação ao AppToHome. Passagens em outras áreas são ignoradas pela integração.
API exposta ao AppToHome
O plugin disponibiliza um conjunto de endpoints REST que o aplicativo AppToHome consome. Todas as chamadas exigem o Token de autenticação no cabeçalho Authorization; sem ele, a requisição é negada.
| Método e rota | Função |
|---|---|
GET external/apptohome/tiposeventos | Lista os tipos de evento do ACCELERO (código e descrição) |
GET external/apptohome/unidades | Lista as unidades/empresas do ACCELERO (código e descrição) |
POST external/apptohome/pessoas | Cadastra ou atualiza um morador e o associa a uma unidade |
DELETE external/apptohome/pessoas | Desabilita um morador a partir do documento |
POST external/apptohome/qrcode | Gera o QR Code (estático ou dinâmico) de uma pessoa |
POST external/apptohome/invite | Cria um convite de visita (evento com visitante e visitado) |
DELETE external/apptohome/invite | Cancela um convite de visita |
Estes endpoints são consumidos pelo serviço AppToHome, não por operadores na interface do ACCELERO. Os detalhes de payload são definidos no contrato de integração entre AppToHome e IONGRADE.
Cadastro de morador
O AppToHome envia nome, documento, e-mail, telefone, unidade e foto. O ACCELERO:
- Localiza a pessoa pelo documento. Se não existir (ou se Sobrescrever dados de pessoas existentes estiver ativo), grava nome, documento, e-mail, telefone e a foto.
- Associa a pessoa à unidade informada (empresa), usando o tipo de associação definido em Associação de novos moradores. O vínculo é criado como pré-autorizado e autorizante.
A unidade enviada deve corresponder a uma empresa já cadastrada no ACCELERO (campo código da empresa). Se a unidade não for encontrada, o cadastro é recusado.
Desativação de morador
O AppToHome envia o documento da pessoa. O ACCELERO localiza a pessoa e a marca como desabilitada. Pessoas desconhecidas geram erro de retorno.
Geração de QR Code
A partir do documento da pessoa, o ACCELERO gera o QR Code e o devolve ao AppToHome. O QR Code pode ser:
- Estático — código fixo da pessoa (comportamento padrão);
- Dinâmico — código rotativo, quando o AppToHome solicita o modo dinâmico.
Convite de visita
O AppToHome envia os dados do evento (identificador, datas de início e fim, tipo), do visitante (nome, documento, e-mail, telefone, foto) e do visitado (documento e unidade). O ACCELERO:
- Valida que a unidade existe, que o visitado existe e está associado à unidade, e que o tipo de evento existe;
- Cria o evento de visita com as datas informadas;
- Cria ou atualiza o cadastro do visitante;
- Vincula visitante e visitado ao evento e gera um cartão virtual (QR Code) identificado como
AppToHome <id>, válido durante o período da visita.
Diagrama de sequência do convite de visita: AppToHome → API ACCELERO (criar evento, upsert do visitante, vínculo evento-pessoa, emissão do cartão QR) → retorno do identificador do vínculo.
Cancelamento de convite
O AppToHome envia o identificador do convite. O ACCELERO localiza o vínculo correspondente, marca o evento como cancelado e o vínculo do visitante como cancelado — invalidando o cartão virtual emitido.
Notificação de acessos ao AppToHome
Sempre que ocorre uma passagem efetivamente realizada (acesso real) cujo destino é uma área configurada, o ACCELERO envia ao AppToHome uma notificação contendo o identificador do convite, o tipo (entrada ou saída) e o horário do acesso.
- Entrada — destino é uma das Áreas de entrada;
- Saída — destino é uma das Áreas de saída;
- Passagens em outras áreas não são notificadas.
Se a notificação ao AppToHome falhar (serviço indisponível ou retorno diferente de sucesso), o ACCELERO reenfileira o envio e tenta novamente após um intervalo, evitando perda de eventos.
Exemplo de evento de acesso de um visitante AppToHome nos Logs e Monitoramento, evidenciando a passagem que dispara a notificação.
Casos de uso
Habilitar a integração para um empreendimento
- Solicitar à IONGRADE a instalação do plugin
apptohome. - Em
Configurações > Integrações - AppToHome, definir o Operador da integração. - Informar o Token de autenticação combinado com o AppToHome e a URL AppToHome.
- Escolher o tipo de Associação de novos moradores e definir as Áreas de entrada e Áreas de saída.
- Salvar e validar com o AppToHome o cadastro de um morador de teste e a geração de QR Code.
Receber um novo morador do AppToHome
- O morador é cadastrado no AppToHome e vinculado a uma unidade.
- O AppToHome envia o cadastro ao ACCELERO, que cria a pessoa e a associa à empresa correspondente.
- O AppToHome solicita o QR Code da pessoa para uso como credencial de acesso.
Registrar um convite de visita
- O morador cria o convite de visita no AppToHome.
- O AppToHome envia o convite ao ACCELERO, que cria o evento de visita e emite o cartão virtual (QR Code) do visitante.
- O visitante usa o QR Code no acesso; a passagem é registrada e notificada de volta ao AppToHome.
Boas práticas
- Operador dedicado: crie um operador específico (ex: "Integração AppToHome") como responsável pelas operações da API, em vez de usar uma conta nominal.
- Token forte: use um token de autenticação longo e exclusivo para a integração e mantenha-o em sigilo.
- Áreas bem definidas: mapeie corretamente as Áreas de entrada e Áreas de saída para que as notificações de acesso reflitam a movimentação real.
- Decisão sobre sobrescrita: ative Sobrescrever dados de pessoas existentes apenas quando o AppToHome for a fonte autoritativa dos dados cadastrais; do contrário, mantenha desativado para preservar edições feitas no ACCELERO.
Troubleshooting
Chamadas do AppToHome retornam "Não autorizado"
Possíveis causas:
- Token de autenticação ausente ou incorreto no cabeçalho
Authorization. - Token configurado no ACCELERO diferente do usado pelo AppToHome.
Solução:
- Confirme o Token de autenticação (Access Key) em
Configurações > Integrações - AppToHome. - Garanta que o AppToHome envia exatamente esse token no cabeçalho
Authorization.
Cadastro de morador ou convite recusado por "Unidade desconhecida"
Possíveis causas:
- A unidade enviada não corresponde a nenhuma empresa cadastrada no ACCELERO.
Solução:
- Verifique o código da empresa em Empresas.
- Alinhe com o AppToHome qual código de unidade deve ser enviado.
Acessos não chegam ao AppToHome
Possíveis causas:
- A área de destino da passagem não está em Áreas de entrada nem em Áreas de saída.
- A URL AppToHome está incorreta ou o serviço está indisponível.
Solução:
- Revise as Áreas de entrada e Áreas de saída na configuração.
- Confirme a URL AppToHome e a conectividade do servidor ACCELERO até o serviço.
Integração com outros módulos
Pessoas
Os moradores e visitantes recebidos do AppToHome são gravados como Pessoas, identificados pelo documento.
Empresas
As unidades do AppToHome correspondem a Empresas no ACCELERO; o vínculo pessoa-unidade usa o Tipo de Associação definido na configuração.
Eventos
Os convites de visita criam Eventos de visita no ACCELERO, com visitante e visitado vinculados.
Áreas e Logs
As Áreas de entrada e saída determinam quais passagens são notificadas; consulte Logs e Monitoramento para acompanhar os acessos registrados.
Próximos Passos
- Pessoas — Entenda o cadastro recebido do AppToHome
- Empresas — Verifique os códigos de unidade
- Tipos de Associação — Configure a associação de novos moradores
- Eventos — Acompanhe os convites de visita
- Áreas — Defina as áreas de entrada e saída
- Plugins — Saiba mais sobre o sistema de plugins do ACCELERO