Integração EducatION (Sistemas de Gestão Escolar)
A integração EducatION conecta o ACCELERO a sistemas de gestão escolar. Periodicamente o ACCELERO consulta uma API externa do sistema acadêmico e sincroniza, na base local, alunos, seus responsáveis (financeiro e pedagógico) e as pessoas autorizadas a retirar os alunos — criando pessoas, empresas e categorias automaticamente. Opcionalmente, o plugin também integra com o TOTVS RM para enviar o controle de frequência (registros de ausência) dos alunos.
Esta integração é disponibilizada como plugin (education) 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.16.8 ou superior.
O EducatION cuida da sincronização de cadastros (alunos/responsáveis/autorizados) e da frequência a partir do sistema acadêmico. Para os recursos de aplicativo voltados ao ambiente escolar, consulte a integração Accelero Edu. Os plugins têm escopos distintos e não devem ser confundidos.
O que a integração faz
Com o plugin ativo, o ACCELERO passa a refletir automaticamente o cadastro do sistema acadêmico: basta configurar o endereço da API e os parâmetros de funcionamento para que os alunos e seus vínculos sejam mantidos sincronizados, sem cadastro manual.
| Funcionalidade | O que acontece no ACCELERO |
|---|---|
| Sincronização de alunos | Cada aluno retornado pela API é cadastrado como pessoa, com nome, documento e foto (quando informada) |
| Categorias por turma | O aluno é associado a categorias cujos nomes correspondem às turmas em que está matriculado |
| Empresa por aluno | É criada uma empresa cujo código/descrição é o ID do aluno; o aluno é vinculado a ela |
| Responsáveis | Responsáveis financeiro e pedagógico são cadastrados, recebem categorias configuradas e são vinculados à empresa do aluno |
| Pessoas autorizadas | Pessoas autorizadas a retirar o aluno são cadastradas, recebem categoria configurada e são vinculadas à empresa do aluno |
| Múltiplas etapas/anos | É possível sincronizar mais de uma etapa/ano por execução (útil na virada de ano letivo) |
| Controle de frequência (TOTVS RM) | Compara a grade horária do dia com os acessos registrados e envia ao TOTVS os registros de ausência dos alunos |
| Logs de integração | Toda execução (sincronização e frequência) é registrada com status e mensagem para auditoria |
Mantém o cadastro de alunos, responsáveis e autorizados sempre alinhado ao sistema acadêmico, eliminando o cadastro manual e os vínculos entre eles.
Configuração
Caminho de acesso: Avançado > Sistema > Plugins - EducatION
A tela possui as abas: API, Configurações, Frequência e Logs. Uma aba adicional Sincronização parcial aparece apenas quando o módulo de desenvolvimento (dev) está habilitado.
Aba API
Dados de conexão com a API do sistema acadêmico.
Aba API da tela de configuração do EducatION, mostrando os campos Host, Tipo autenticação, Username / Bearer token, Password API, Timeout API e Usuário da integração, além dos botões Salvar e Sincronizar.
| Campo | Descrição |
|---|---|
| Host | Endereço da API externa. O ano/etapa a sincronizar pode ser informado como placeholder {{year}} na URL (ex.: https://servidor.com.br/api/alunos/{{year}}) |
| Tipo autenticação | Sistema de autenticação da API: Nenhuma, Basic auth ou Bearer token |
| Username / Bearer token | Nome de usuário (para Basic auth) ou o token (para Bearer token) |
| Password API | Senha — usada apenas quando o tipo é Basic auth |
| Timeout API | Tempo limite (em segundos) das chamadas à API |
| Usuário da integração | Operador do ACCELERO em cujo nome as alterações de dados feitas pela integração aparecem nos logs do sistema |
Aba Configurações
Define quais etapas/anos sincronizar e as categorias e tipos de associação padrão aplicados a responsáveis e autorizados.
Aba Configurações do EducatION, mostrando o campo Etapas a sincronizar e os blocos Responsáveis financeiros, Responsáveis pedagógicos e Pessoas autorizadas, cada um com Categoria e Tipo de associação.
| Campo | Descrição |
|---|---|
| Etapas a sincronizar (separe com vírgula) | Uma ou mais etapas/anos a processar. Cada valor substitui o placeholder {{year}} da URL. Quando vazio, usa o ano corrente |
| Responsáveis financeiros — Categoria | Categoria atribuída aos responsáveis financeiros sincronizados |
| Responsáveis financeiros — Tipo de associação | Tipo de associação (vínculo pessoa-empresa) aplicado aos responsáveis financeiros |
| Responsáveis pedagógicos — Categoria | Categoria atribuída aos responsáveis pedagógicos sincronizados |
| Responsáveis pedagógicos — Tipo de associação | Tipo de associação aplicado aos responsáveis pedagógicos |
| Pessoas autorizadas — Categoria | Categoria atribuída às pessoas autorizadas sincronizadas |
| Pessoas autorizadas — Tipo de associação | Tipo de associação aplicado às pessoas autorizadas |
As categorias dos alunos não são definidas aqui: o aluno é associado automaticamente a categorias cujos nomes correspondem às suas turmas (ver Como os dados são organizados).
Aba Frequência
Configura a integração de controle de frequência (ausências) com o TOTVS RM. Esta aba é opcional e só é utilizada quando a frequência está habilitada.
Aba Frequência do EducatION, mostrando os campos de Configuração de Frequência, Filtros, Janelas de horário, os botões Sincronizar frequência e o bloco Testar / Reprocessar data específica.
| Campo | Descrição |
|---|---|
| Habilitar frequência | Liga/desliga o processamento de frequência (Não / Sim) |
| Hora da execução automática | Hora do dia (0–23) para o processamento automático diário (padrão: 3) |
| Host TOTVS RM | URL base da API do TOTVS RM |
| Nome da consulta SQL | Nome da consulta REST configurada no TOTVS (padrão: ACCELERO_FREQUEN) |
| Categorias de alunos | Multi-seleção de categorias usadas para filtrar os alunos no cálculo de frequência |
| Áreas de entrada | Multi-seleção de áreas cuja passagem é considerada entrada |
| Áreas de saída | Multi-seleção de áreas cuja passagem é considerada saída |
| Entrada a partir de / Entrada até | Janela de horário considerada para a entrada (opcional) |
| Saída a partir de / Saída até | Janela de horário considerada para a saída (opcional) |
As credenciais usadas no envio ao TOTVS RM (usuário e senha) são as mesmas configuradas na aba API.
O aluno é considerado presente se registrar entrada dentro da janela de entrada ou saída dentro da janela de saída. Deixe as janelas em branco para não aplicar filtro de horário.
Aba Logs
Exibe os Logs de Integração das execuções do plugin (ver Logs de Integração).
Botões da tela
| Botão | Aba | Função |
|---|---|---|
| Salvar | API / Configurações / Frequência | Persiste a configuração |
| Sincronizar | API | Inicia uma sincronização imediata de alunos/responsáveis/autorizados. O processo pode levar vários minutos |
| Sincronizar frequência | Frequência | Processa e envia a frequência do dia anterior ao TOTVS |
| Testar (sem enviar) | Frequência | Executa o cálculo de frequência de uma data específica em modo de teste (dry-run), sem enviar nada ao TOTVS |
| Enviar ao TOTVS | Frequência | Processa e envia a frequência de uma data específica ao TOTVS |
Como os dados são organizados
A sincronização cria e mantém os seguintes vínculos a partir dos dados recebidos da API:
- Aluno → cadastrado como pessoa; recebe categorias com o nome de cada turma em que está matriculado; é vinculado a uma empresa própria.
- Empresa do aluno → criada com código e descrição iguais ao ID do aluno. Serve para agrupar o aluno e todos que se relacionam a ele.
- Responsável financeiro / pedagógico → cadastrado como pessoa, recebe a categoria e o tipo de associação configurados, e é vinculado à empresa do aluno do qual é responsável.
- Pessoa autorizada → cadastrada como pessoa, recebe a categoria e o tipo de associação configurados, e é vinculada à empresa do aluno.
Cada pessoa sincronizada guarda o seu identificador de origem (education.id) no metadata, usado para reconciliar registros entre execuções e para o cálculo de frequência.
Formato da API externa
O ACCELERO faz uma requisição GET à URL configurada e espera um código HTTP 200 com um array JSON de objetos. A estrutura básica é a mesma para alunos e responsáveis (id, nome, documento, foto).
| Campo | Obrigatório | Descrição |
|---|---|---|
id | Sim | Identificador do aluno na origem |
nome | Sim | Nome (máx. 50 caracteres) |
documento | Sim | CPF/RG (máx. 50 caracteres) |
foto | Não | URL da foto |
responsavelPedagogico | Não | Objeto com id, nome, documento, foto |
responsavelFinanceiro | Não | Objeto com id, nome, documento, foto |
autorizados | Não | Array de objetos com id, nome, documento, foto |
turmas | Não | Array com os nomes das turmas do aluno |
É possível enviar o mesmo aluno em mais de uma posição do array para representar matrícula em diversas turmas. As categorias correspondentes às turmas são criadas/associadas conforme necessário.
Diagrama do fluxo de sincronização: API externa → ACCELERO (criação de empresa, categorias por turma, pessoa do aluno, responsáveis e autorizados, e seus vínculos).
Logs de Integração
Caminho de acesso: Avançado > Sistema > Plugins - EducatION > aba Logs
Cada execução do plugin é registrada na tabela de logs de integração, permitindo auditar resultados e diagnosticar falhas.
Aba Logs com o filtro Filtrar por tipo e a tabela de logs (colunas Data, Tipo, Status, Mensagem, Execução).
Filtro
| Filtro | Opções |
|---|---|
| Filtrar por tipo | Todos / Sincronização de usuários / Frequência |
Colunas
| Coluna | Conteúdo |
|---|---|
| Data | Data e hora do registro |
| Tipo | Tipo da execução (sincronização de usuários ou frequência) |
| Status | Resultado do registro: success, error, warning ou info |
| Mensagem | Descrição do que ocorreu (ex.: "Sincronização finalizada. Total: N registros processados") |
| Execução | Identificador único da execução, usado para agrupar os registros de uma mesma rodada |
Controle de frequência (TOTVS RM)
Quando habilitada, a frequência compara a grade horária do dia (obtida via REST no TOTVS RM) com os acessos registrados no ACCELERO, identifica os alunos ausentes e envia esses registros ao TOTVS via SOAP.
Diagrama do fluxo de frequência: TOTVS RM (REST, grade horária) → ACCELERO (consulta logs de acesso e calcula ausências) → TOTVS RM (SOAP, envio de ausências).
Como funciona
- Buscar a grade horária do dia no TOTVS RM, usando a consulta SQL configurada e o dia da semana (segunda a sexta; finais de semana não são processados).
- Buscar os acessos do dia no ACCELERO, considerando apenas alunos das categorias configuradas que possuem identificador de origem (
education.id). - Detectar presença: o aluno é considerado presente se registrou entrada (e/ou saída) nas áreas e janelas de horário configuradas. Alunos previstos na grade que não constam como presentes são marcados como ausentes.
- Enviar as ausências ao TOTVS RM, agrupadas por turma.
- Registrar o resultado nos Logs de Integração (tipo Frequência).
Disparo
| Forma | Como |
|---|---|
| Automático | Diariamente, na hora configurada em Hora da execução automática, processando o dia anterior |
| Manual | Botão Sincronizar frequência (processa o dia anterior) |
| Por data | Botões Testar (sem enviar) e Enviar ao TOTVS no bloco Testar / Reprocessar data específica |
Use Testar (sem enviar) para validar a configuração (categorias, áreas, janelas e conexão com o TOTVS) de uma data específica antes de enviar os dados reais.
Sincronização parcial (módulo dev)
Quando o módulo de desenvolvimento (dev) está habilitado, a aba Sincronização parcial permite colar um JSON parcial (um array no mesmo formato da API externa) e processá-lo manualmente, sem consultar a API.
A sincronização parcial é uma ferramenta de apoio técnico/diagnóstico, disponível apenas com o módulo dev habilitado. Não faz parte da operação cotidiana.
Quando os envios são disparados
Sincronização de cadastros
- Automaticamente, em execução agendada (job de fila), reprocessando todas as etapas configuradas a cada período.
- Manualmente, pelo botão Sincronizar na aba API.
Um mecanismo de bloqueio (semáforo) impede que duas sincronizações rodem ao mesmo tempo; se já houver uma em andamento, a nova execução é interrompida.
Frequência
Disparada automaticamente no horário configurado, ou manualmente pelos botões da aba Frequência (ver Disparo).
Casos de uso
Habilitar a sincronização de alunos
- Solicitar à IONGRADE a instalação do plugin
education. - Em
Avançado > Sistema > Plugins - EducatION, na aba API, preencher Host, tipo de autenticação e credenciais, e selecionar o Usuário da integração. - Na aba Configurações, informar as etapas a sincronizar e definir categoria e tipo de associação de responsáveis e autorizados.
- Clicar em Salvar e depois em Sincronizar para a primeira carga.
- Acompanhar o resultado na aba Logs.
Habilitar o controle de frequência
- Na aba Frequência, definir Habilitar frequência = Sim.
- Preencher Host TOTVS RM e Nome da consulta SQL.
- Selecionar Categorias de alunos, Áreas de entrada e Áreas de saída e, se desejar, as janelas de horário.
- Salvar e usar Testar (sem enviar) para uma data conhecida, conferindo o diagnóstico.
- Quando validado, deixar a execução automática ativa (ou usar Enviar ao TOTVS para datas específicas).
Investigar uma sincronização com erro
- Acessar a aba Logs e filtrar por Sincronização de usuários.
- Localizar a execução com status error e ler a Mensagem.
- Corrigir o problema na origem (API) ou na configuração e executar Sincronizar novamente.
Boas práticas
- Etapas corretas na virada de ano: durante a transição de ano letivo, informe as duas etapas em Etapas a sincronizar para manter os dois períodos atualizados.
- Categorias e associações dedicadas: crie categorias e tipos de associação específicos para responsáveis e autorizados, evitando misturar com outros públicos.
- Usuário de integração dedicado: configure um usuário ACCELERO específico (ex.: "Integração EducatION") como responsável das alterações nos logs.
- Teste a frequência antes de enviar: sempre rode Testar (sem enviar) ao alterar áreas, janelas ou a consulta SQL do TOTVS.
- Acompanhe os logs: verifique a aba Logs após cada carga relevante para identificar registros com erro.
Troubleshooting
A sincronização não cria/atualiza pessoas
Possíveis causas:
- API externa inacessível, com autenticação incorreta ou retornando código diferente de 200
- Configuração incompleta (Host, tipo de autenticação, usuário da integração, categorias/associações)
- Já existe uma sincronização em andamento (bloqueio por semáforo)
Solução:
- Confira os campos da aba API (Host, autenticação, credenciais, timeout).
- Confira na aba Configurações as categorias e tipos de associação obrigatórios.
- Veja a aba Logs (filtro Sincronização de usuários) e leia a mensagem de erro.
- Aguarde a conclusão de uma sincronização em andamento antes de iniciar outra.
A frequência não envia ausências ao TOTVS
Possíveis causas:
- Frequência desabilitada
- Host TOTVS RM ou Nome da consulta SQL incorretos
- Áreas de entrada/saída ou categorias de alunos não configuradas
- Alunos sem o identificador de origem (
education.id) — não foram sincronizados pelo plugin
Solução:
- Confirme Habilitar frequência = Sim.
- Rode Testar (sem enviar) para uma data conhecida e analise o diagnóstico.
- Verifique áreas, categorias e janelas de horário.
- Garanta que os alunos foram criados pela sincronização (aba API → Sincronizar).
- Consulte a aba Logs (filtro Frequência).
O cálculo de frequência depende de alunos sincronizados pelo próprio plugin (com education.id no metadata) e de acessos registrados nas áreas configuradas. Cadastros manuais que não passaram pela integração não entram nesse cálculo.
Integração com outros módulos
Pessoas e Empresas
A integração cria e mantém o cadastro de Pessoas (alunos, responsáveis e autorizados) e de Empresas (uma por aluno), além dos vínculos entre elas.
Categorias
Os alunos são associados a categorias correspondentes às suas turmas, e responsáveis/autorizados às categorias configuradas. Consulte Pessoas para entender o uso de categorias.
Áreas e Logs de acesso
O controle de frequência usa as Áreas configuradas como entrada e saída e os acessos registrados — consulte Logs e Monitoramento.
Accelero Edu
Para os recursos de aplicativo do ambiente escolar, veja a integração Accelero Edu — escopo distinto do EducatION.
Próximos Passos
- Pessoas — Entenda o cadastro de alunos, responsáveis e autorizados
- Empresas — Veja como as empresas por aluno são usadas
- Áreas — Configure as áreas de entrada e saída para a frequência
- Logs e Monitoramento — Entenda os acessos usados no cálculo de frequência
- Accelero Edu — Recursos de aplicativo para o ambiente escolar
- Plugins — Saiba mais sobre o sistema de plugins do ACCELERO