Integração Unimestre
A integração Unimestre conecta o ACCELERO ao sistema acadêmico Unimestre, importando automaticamente os cadastros mantidos na plataforma educacional. Alunos, familiares e responsáveis cadastrados no Unimestre passam a existir como pessoas no ACCELERO, com suas empresas (núcleos familiares), categorias, fotos e vínculos de responsável (escort) sincronizados periodicamente.
Esta integração é disponibilizada como plugin (unimestre) 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.2 — compatível com ACCELERO 2.17.0 ou superior.
O que a integração faz
Com o plugin ativo, o Unimestre passa a ser a fonte dos cadastros: o ACCELERO consulta a API da instituição, agrupa os dados por pessoa e mantém o cadastro local atualizado a cada sincronização — criando, atualizando e removendo vínculos conforme o que o Unimestre retorna.
| Funcionalidade | O que acontece no ACCELERO |
|---|---|
| Sincronização de pessoas | Cada pessoa retornada pela API é criada ou atualizada (nome, CPF, e-mail, código). O vínculo com o registro de origem fica guardado nos metadados |
| Empresas (núcleos familiares) | Para cada aluno é criada/atualizada uma empresa "FAMÍLIA DE {nome}", e os familiares são vinculados a ela com o tipo de associação informado pelo Unimestre |
| Categorias por bind | Papéis e turmas vindos do Unimestre são convertidos em categorias do ACCELERO conforme os binds configurados, com início e fim de validade no ano do semestre |
| Fotos | A foto de cada pessoa é baixada do Unimestre e atualizada quando houver mudança no registro de origem |
| Responsável (escort) | Pessoas de categorias marcadas como "que exigem escort" passam a exigir responsável, e os responsáveis da família são vinculados como escort automaticamente |
| Remoção de vínculos obsoletos | Empresas e categorias criadas pela integração que não aparecem mais no retorno da API são removidas da pessoa |
| Sincronização diária e manual | A sincronização roda automaticamente toda madrugada e também pode ser disparada manualmente pela tela de configuração |
Elimina o recadastro manual de alunos, familiares e responsáveis no ACCELERO — o cadastro acadêmico do Unimestre vira a fonte única.
Configuração
Caminho de acesso: Configurações > Plugins - Unimestre
A tela de configuração possui três abas: Geral, Configuração API e Binds de categorias.
Tela de configuração da integração Unimestre mostrando as três abas (Geral, Configuração API, Binds de categorias) e os botões da base (Voltar, Salvar, Sincronizar agora).
Aba Geral
| Campo | Descrição |
|---|---|
| Semestres a sincronizar (separar com vírgula) | Lista de semestres a consultar na API, separados por vírgula. Cada semestre é enviado à API como parâmetro anosemestre |
| Operador da sincronização | Operador do ACCELERO usado como usuário logado durante a sincronização (responsável pelas operações executadas pelo plugin) |
| Listar categorias que exigem escort | Multi-seleção de categorias do ACCELERO. Pessoas vinculadas a uma dessas categorias passam a exigir escort, e seus responsáveis são vinculados automaticamente |
| Qual tipo de associação se torna responsável (escort)? | Multi-seleção de tipos de associação (de linkpessoasempresastipos). As pessoas da família vinculadas por um desses tipos são tratadas como responsáveis (escort) do aluno |
Aba Configuração API
Dados de conexão com a API do Unimestre:
| Campo | Descrição |
|---|---|
| Endereço da API | URL do endpoint da API do Unimestre — fornecida pela instituição |
| Username API | Usuário para autenticação na API (autenticação básica) |
| Token API | Token/senha correspondente (campo protegido) |
| Timeout da API | Tempo limite, em segundos, para a resposta da API |
Se a API estiver indisponível (erro de conexão, DNS ou status diferente de 200), a sincronização daquele semestre é abortada. Isso é proposital: um retorno vazio por falha faria o ACCELERO remover em massa as empresas e categorias da integração. Confira o Endereço da API, Username e Token antes de disparar uma nova sincronização.
Aba Binds de categorias
Tabela que relaciona papéis e turmas do Unimestre com categorias do ACCELERO.
| Coluna | Descrição |
|---|---|
| Tipo de Entidade | Identificador do papel ou turma vindo do Unimestre (ex.: nome do papel ou do curso) |
| Categoria | Categoria do ACCELERO que será aplicada à pessoa quando o papel/turma corresponder |
Use o botão Adicionar para incluir novas linhas e o botão de remoção (✕) para excluir um bind.
Somente os papéis/turmas que tiverem um bind cadastrado nesta aba geram categoria na pessoa. Papéis sem bind correspondente são ignorados na sincronização.
Aba Binds de categorias mostrando a tabela de relacionamento Tipo de Entidade → Categoria e o botão Adicionar.
Botões da tela
| Botão | Função |
|---|---|
| Voltar | Retorna sem salvar |
| Salvar | Persiste a configuração |
| Sincronizar agora | Dispara imediatamente uma sincronização manual (pede confirmação com captcha) |
Ao acionar Sincronizar agora, o sistema exibe o aviso: "Esse processo pode levar algum tempo e o sistema poderá apresentar instabilidade enquanto os dados são sincronizados." Prefira executar a sincronização manual fora dos horários de pico.
Como a sincronização funciona
A sincronização percorre, para cada semestre configurado, todos os registros retornados pela API e mantém o cadastro local alinhado ao Unimestre.
Quando a sincronização ocorre
- Automática: todos os dias por volta da 1h da manhã (reagendada a cada execução).
- Manual: pelo botão Sincronizar agora na tela de configuração.
Ao iniciar, a sincronização aplica uma trava temporária. Se você acionar Sincronizar agora enquanto outra sincronização ainda está em andamento, o sistema informa que deve aguardar a disponibilidade.
Notificações de progresso
Quando disparada manualmente, a integração notifica o operador que iniciou o processo:
- Início: "Processo de sincronização Unimestre iniciado..."
- Progresso: mensagens de "
{n}/{total}cadastros importados..." ao longo da importação. - Conclusão: "Processo de sincronização Unimestre finalizado! Processo levou
{n}segundos!" - Erro: "Erro no processo de sincronização Unimestre!"
Notificação de progresso da sincronização Unimestre exibida ao operador (título "Sincronização Unimestre"), com as mensagens de início, progresso e conclusão.
O que cada sincronização faz
- Busca os dados de cada semestre na API.
- Agrupa por pessoa, identificando alunos (quem tem turma), familiares e os vínculos de parentesco entre eles.
- Cria ou atualiza a pessoa (nome, CPF, e-mail, código), guardando o identificador de origem nos metadados.
- Cria/atualiza a empresa familiar dos alunos e vincula os familiares com o tipo de associação informado.
- Aplica as categorias conforme os binds, com validade do ano do semestre.
- Remove vínculos obsoletos de empresa e categoria que não vieram mais no retorno.
- Atualiza os responsáveis (escort) e as fotos.
A integração localiza a pessoa primeiro pelo CPF (documento) e, se não encontrar, pelo identificador do Unimestre guardado nos metadados. CPFs zerados (00000000000) são tratados como ausentes.
Empresas e núcleos familiares
Para cada aluno, a integração cria (se ainda não existir) uma empresa cujo nome segue o padrão "FAMÍLIA DE {nome do aluno}" e vincula:
- o próprio aluno, com o tipo de associação Estudante;
- cada familiar/responsável, com o tipo de associação informado pelo Unimestre.
Os vínculos criados são marcados como pré-autorizados e autorizantes. Tipos de associação que ainda não existem no ACCELERO são criados automaticamente.
Empresas, categorias e vínculos criados pela integração ficam marcados nos metadados como originados do Unimestre. Essa marcação é o que permite, na sincronização seguinte, identificar e remover os vínculos que deixaram de existir no sistema de origem — sem afetar vínculos cadastrados manualmente.
Responsável (escort)
Quando uma pessoa pertence a uma das categorias que exigem escort (configuradas na aba Geral), a integração:
- Marca a pessoa para exigir escort.
- Localiza, dentro da empresa familiar, as pessoas vinculadas pelos tipos de associação definidos como responsável (campo "Qual tipo de associação se torna responsável (escort)?").
- Vincula essas pessoas como escort do aluno.
Se a pessoa deixar de pertencer a uma categoria que exige escort, a marcação é removida e os vínculos de escort criados pela integração são desfeitos.
Cadastro de pessoa (aluno) sincronizado, mostrando o indicador "exigir escort" ativo e a lista de responsáveis (escort) vinculados pela integração.
Fotos
A integração baixa a foto de cada pessoa diretamente do Unimestre e a grava no cadastro.
- A foto é atualizada quando o registro de origem teve alteração desde a última sincronização (ou quando a pessoa ainda não tem foto cadastrada).
- Se o Unimestre não tiver foto real para a pessoa, a integração não grava a imagem padrão "sem foto".
Casos de uso
Configurar a integração pela primeira vez
- Solicitar à IONGRADE a instalação do plugin
unimestre. - Em
Configurações > Plugins - Unimestre, aba Configuração API, preencher endereço, username, token e timeout. - Na aba Geral, informar os semestres a sincronizar e o operador da sincronização.
- Na aba Binds de categorias, mapear os papéis/turmas do Unimestre para as categorias do ACCELERO.
- Definir as categorias que exigem escort e os tipos de associação que se tornam responsável, se a instituição usar controle de responsável.
- Clicar em Salvar e depois em Sincronizar agora para a primeira carga.
- Acompanhar as notificações de progresso e conferir alguns cadastros importados.
Adicionar um novo semestre
- Abrir
Configurações > Plugins - Unimestre, aba Geral. - Acrescentar o novo semestre ao campo Semestres a sincronizar, separado por vírgula.
- Salvar e, se quiser efetivar imediatamente, clicar em Sincronizar agora.
Mapear um novo papel para uma categoria
- Abrir a aba Binds de categorias.
- Clicar em Adicionar, informar o Tipo de Entidade (papel/turma do Unimestre) e selecionar a Categoria do ACCELERO.
- Salvar. Na próxima sincronização, as pessoas com esse papel passam a receber a categoria.
Boas práticas
- Categorias específicas nos binds: mapeie cada papel/turma para uma categoria dedicada ao público acadêmico, evitando categorias genéricas.
- Operador dedicado: use um operador específico para a sincronização (ex.: "Integração Unimestre") em vez de uma conta nominal.
- Sincronização fora de pico: a carga manual pode causar instabilidade — prefira horários de baixo uso; a automática já roda de madrugada.
- Confira a API antes de re-sincronizar: se a sincronização falhar, valide endereço, username e token. A integração aborta a remoção em massa quando o retorno vem vazio por falha, mas o cadastro só volta a atualizar com a API respondendo.
Troubleshooting
"Erro ao consultar API" ou sincronização não conclui
Possíveis causas:
- Endereço da API incorreto.
- Username ou token inválidos.
- API do Unimestre indisponível ou timeout muito baixo.
Solução:
- Em
Configurações > Plugins - Unimestre > Configuração API, confira endereço, username e token. - Aumente o Timeout da API se a base for grande.
- Teste a conectividade do servidor ACCELERO até a URL da API.
Pessoas importadas sem categoria
Possíveis causas:
- Não há bind cadastrado para o papel/turma da pessoa.
- O semestre da pessoa não está na lista de Semestres a sincronizar.
Solução:
- Verifique a aba Binds de categorias e cadastre o bind do papel/turma.
- Confirme que o semestre da pessoa está configurado.
- Rode Sincronizar agora.
Empresas ou categorias da integração foram removidas inesperadamente
Possíveis causas:
- O registro deixou de aparecer no retorno da API (remoção legítima).
Solução:
- Confirme no Unimestre se o vínculo ainda existe.
- Verifique se a sincronização anterior concluiu com sucesso (uma sincronização abortada por falha não remove vínculos — apenas os concluídos com retorno válido removem os obsoletos).
"Sincronizar agora" pede para aguardar
Causa: outra sincronização ainda está em andamento (trava de concorrência ativa).
Solução: aguarde a conclusão da sincronização atual e tente novamente.
Integração com outros módulos
Pessoas
A integração cria e atualiza Pessoas a partir do Unimestre, incluindo CPF, e-mail, foto e código. O CPF é o principal identificador de correspondência.
Empresas
Os núcleos familiares são representados como Empresas ("FAMÍLIA DE..."), com os familiares vinculados pelos tipos de associação.
Categorias
As Categorias são aplicadas conforme os binds, com validade no ano do semestre sincronizado.
Escort (Responsável)
A integração alimenta o controle de Escort, marcando alunos que exigem responsável e vinculando os responsáveis da família.
Próximos Passos
- Pessoas — Entenda o cadastro de pessoas alimentado pela integração
- Empresas — Veja como os núcleos familiares são representados
- Categorias — Configure as categorias usadas nos binds
- Escort — Entenda o controle de responsáveis
- Plugins — Saiba mais sobre o sistema de plugins do ACCELERO