Integração QI Solution
A integração QI Solution conecta o ACCELERO ao ERP educacional da QI Solution. Ela importa automaticamente os cadastros do colégio (alunos, responsáveis e pessoas autorizadas) e envia de volta os dados de presença diária dos alunos, eliminando o cadastro duplicado entre a secretaria escolar e o controle de acesso.
Esta integração é disponibilizada como plugin (qisolution) e corresponde a um módulo licenciado do ACCELERO (categoria Integrações) — precisa ser instalada e habilitada pela equipe técnica da IONGRADE. Consulte o suporte para verificar a disponibilidade e a compatibilidade com a sua versão do ACCELERO.
Versão atual do plugin: 2.0.0 — compatível com ACCELERO 2.17.0 ou superior.
O que a integração faz
Com o plugin ativo, o ACCELERO consulta a base da QI Solution para manter os cadastros sincronizados e reporta a presença dos alunos de volta ao ERP. A sincronização roda automaticamente uma vez por dia (e pode ser disparada manualmente), enquanto o envio de presença ocorre diariamente e também pode ser feito manualmente para uma data específica.
| Funcionalidade | O que acontece no ACCELERO |
|---|---|
| Importação de cadastros de alunos | Cada aluno vira uma Pessoa, com a matrícula gravada no campo de código; também é criada uma Empresa que representa o aluno e os vínculos de turma |
| Importação de responsáveis | Pai, mãe e responsáveis pedagógico e financeiro são importados como Pessoas, identificados pelo CPF |
| Responsáveis pedagógicos e financeiros | Recebem categoria e tipo de associação padrão (configuráveis) e são vinculados às empresas dos alunos a que respondem |
| Importação de pessoas autorizadas | Pessoas autorizadas a retirar/acompanhar o aluno são importadas e vinculadas à empresa do aluno |
| Habilitar/desabilitar alunos por status | O aluno é habilitado ou desabilitado conforme o status de matrícula retornado pela QI Solution |
| Limpeza de vínculos obsoletos | Vínculos, categorias e empresas criados pela integração que não constam mais na base da QI Solution são removidos automaticamente |
| Envio de presença diária | A primeira entrada e a última saída de cada aluno no dia são apuradas a partir dos eventos de acesso e enviadas à QI Solution |
Mantém o cadastro do colégio (alunos, turmas e responsáveis) e a frequência sincronizados automaticamente, sem digitação duplicada entre a secretaria e o controle de acesso.
Configuração
Caminho de acesso: Avançado > Sistema > Integrações - QI Solution
O item só aparece na lista quando o módulo QI Solution está liberado na licença.
A tela de configuração possui três abas: Geral, Importação de cadastros e Relatório de presença.
Aba Geral
Dados de autenticação comuns a todas as operações da integração.
| Campo | Descrição |
|---|---|
| Token do colégio | Token que identifica o colégio na base da QI Solution |
| Autorização QI Solution | Valor do cabeçalho Authorization usado nas chamadas à API |
| Timeout da API | Tempo máximo, em segundos, para aguardar respostas da API |
O token e a autorização são fornecidos pela QI Solution / IONGRADE durante a implantação. Sem esses dados a integração não consegue consultar nem enviar informações.
Aba Importação de cadastros
Define a origem dos dados e os valores padrão aplicados às pessoas importadas.
| Campo | Descrição |
|---|---|
| Endereço da API | URL base da API da QI Solution usada para buscar os cadastros |
| Etapas a sincronizar | Anos letivos / etapas a importar, separados por vírgula (ex: 2025, 2026). Se vazio, usa o ano atual |
| Status que devem habilitar o cadastro do aluno | Multi-seleção dos status de matrícula que mantêm o aluno habilitado no ACCELERO. Demais status deixam o aluno desabilitado |
| Operador da sincronização | Operador do ACCELERO sob o qual a sincronização é executada (responsável pelas alterações de cadastro) |
Status de matrícula disponíveis
O campo Status que devem habilitar o cadastro do aluno oferece os seguintes valores (retornados pela QI Solution):
| Código | Descrição |
|---|---|
| 0 | Não matriculado |
| 1 | Matriculado |
| 2 | Cursando |
| 3 | Matrícula Cancelada |
| 4 | Desistente |
| 5 | Transferido de Escola |
| 6 | Matrícula Trancada |
| 7 | Transferido de Turma |
| 10 | Promovido |
| 14 | Aprovado pelo conselho |
| 21 | Recuperação final |
| 24 | Retido |
Registros com status 7 - Transferido de Turma são ignorados na importação — eles representam um histórico de movimentação, não o vínculo atual do aluno.
Valores padrão para responsáveis pedagógicos importados
| Campo | Descrição |
|---|---|
| Categoria padrão | Categoria atribuída às pessoas importadas como responsável pedagógico |
| Tipo de associação padrão | Tipo de associação (vínculo pessoa↔empresa) usado para ligar o responsável pedagógico à empresa do aluno |
Valores padrão para responsáveis financeiros importados
| Campo | Descrição |
|---|---|
| Categoria padrão | Categoria atribuída às pessoas importadas como responsável financeiro |
| Tipo de associação padrão | Tipo de associação usado para ligar o responsável financeiro à empresa do aluno |
Valores padrão para pessoas autorizadas importadas
| Campo | Descrição |
|---|---|
| Categoria padrão | Categoria atribuída às pessoas importadas como pessoa autorizada |
Botões da aba
| Botão | Função |
|---|---|
| Testar sincronização | Consulta a base da QI Solution e verifica se todas as Categorias (turmas) necessárias já existem no ACCELERO, sem alterar dados. Em caso de divergência, lista as categorias ausentes |
| Sincronizar agora | Dispara a sincronização completa imediatamente, em segundo plano |
Ao acionar Sincronizar agora, o sistema avisa que o processo pode levar algum tempo e gerar instabilidade enquanto os dados são processados. Prefira executá-la fora do horário de pico.
Aba Relatório de presença
Configura o envio dos dados de presença diária dos alunos de volta à QI Solution.
| Campo | Descrição |
|---|---|
| Endereço da API | URL do endpoint da QI Solution que recebe os dados de presença |
| Áreas que significam "dentro" | Multi-seleção de áreas cuja passagem é interpretada como entrada do aluno |
| Áreas que significam "fora" | Multi-seleção de áreas cuja passagem é interpretada como saída do aluno |
Botões e envio manual
| Botão | Função |
|---|---|
| Testar envio de dados | Envia uma requisição de teste (sem dados de presença) para validar o endpoint e a autorização |
| Enviar dados manualmente | No bloco Envio manual de dados, informe a Data a ser enviada e dispare o envio da presença daquele dia específico |
Use Enviar dados manualmente para reenviar a presença de um dia em que o envio automático falhou ou para repor dados após um ajuste de configuração.
Entidades criadas e atualizadas
A integração não adiciona campos a formulários — ela cria e mantém registros nas entidades existentes do ACCELERO.
Pessoa
Cada aluno, responsável e pessoa autorizada vira uma Pessoa:
- Alunos são identificados pela matrícula, gravada no campo de código da pessoa (
pesCodigo). Nome e e-mail vêm da QI Solution e o cadastro é habilitado ou não conforme o status de matrícula. - Responsáveis (pai, mãe, pedagógico, financeiro) são identificados pelo CPF (documento da pessoa).
- Pessoas autorizadas são marcadas internamente como originárias da QI Solution e recebem a categoria padrão configurada.
Empresa
Para cada aluno é criada/mantida uma Empresa cuja descrição combina matrícula e nome do aluno. Essa empresa serve de ponto de ligação para vincular os responsáveis e as pessoas autorizadas àquele aluno.
Categorias (turmas) e Tipos de associação
- As turmas retornadas pela QI Solution correspondem a Categorias no ACCELERO. O aluno é vinculado às categorias das suas turmas.
- Os Tipos de associação (vínculo pessoa↔empresa) representam o papel de cada responsável.
A sincronização não cria automaticamente as categorias de turma — ela apenas vincula os alunos a categorias já cadastradas. Use Testar sincronização para descobrir quais turmas estão faltando e crie-as em Categorias antes de rodar a importação completa.
Como a integração se comporta
Sincronização de cadastros
Ao sincronizar, o ACCELERO:
- Busca os alunos de cada etapa configurada na API da QI Solution.
- Garante que as empresas dos alunos e os tipos de associação necessários existam (criando-os quando preciso).
- Cria ou atualiza as Pessoas dos alunos, responsáveis, pedagógicos e financeiros, com seus vínculos de turma, empresa e categoria.
- Remove vínculos, categorias e empresas criados pela própria integração que não constam mais nos dados da QI Solution (limpeza de registros obsoletos).
A integração só remove registros que ela mesma criou (marcados internamente como originados da QI Solution). Cadastros e vínculos feitos manualmente no ACCELERO não são afetados pela limpeza.
Quando a sincronização é disparada
- Automaticamente: a integração se reagenda para rodar diariamente (por padrão, na madrugada). A cada execução são disparados, em sequência, a sincronização de cadastros, o envio de presença e a importação de pessoas autorizadas.
- Manualmente: pelo botão Sincronizar agora na aba Importação de cadastros.
Enquanto uma sincronização está em andamento, uma nova execução manual fica bloqueada por alguns minutos para evitar processos simultâneos. Aguarde o término antes de disparar novamente.
Notificações do processo
O Operador da sincronização (ou quem disparou manualmente) recebe notificações no ACCELERO informando o início, o término (com o tempo gasto) e eventuais erros do processo.
Apuração e envio de presença
- Para a data processada, o sistema lê os eventos de acesso real das pessoas que possuem matrícula.
- A primeira passagem por uma área marcada como "dentro" é registrada como Entrada; a passagem por uma área marcada como "fora" é registrada como Saída.
- Os dados são enviados à QI Solution identificando cada aluno pela matrícula (RA).
- No envio automático, é processada a presença do dia anterior.
Sem áreas marcadas como "dentro" e "fora", nenhuma presença é apurada. Apenas eventos nessas áreas entram no relatório enviado à QI Solution.
Casos de uso
Implantar a integração em um colégio
- Solicitar à IONGRADE a instalação do plugin
qisolution. - Em
Avançado > Sistema > Integrações - QI Solution > Geral, preencher Token do colégio, Autorização e Timeout da API. - Na aba Importação de cadastros, informar o Endereço da API, as Etapas a sincronizar, os status que habilitam o aluno e o Operador da sincronização.
- Definir as categorias e tipos de associação padrão para pedagógicos, financeiros e pessoas autorizadas.
- Clicar em Testar sincronização e cadastrar em Categorias as turmas que aparecerem como ausentes.
- Clicar em Sincronizar agora e acompanhar as notificações.
Configurar o envio de presença
- Na aba Relatório de presença, informar o Endereço da API de presença.
- Selecionar as Áreas que significam "dentro" e as Áreas que significam "fora".
- Usar Testar envio de dados para validar a conexão.
- Deixar o envio automático diário ativo, ou usar Enviar dados manualmente para datas específicas.
Corrigir um aluno que não aparece no controle de acesso
- Conferir, no Testar sincronização, se a turma do aluno existe como Categoria.
- Verificar se o status de matrícula do aluno está entre os configurados para habilitar o cadastro.
- Disparar Sincronizar agora e acompanhar as notificações de término/erro.
Boas práticas
- Cadastre as turmas antes: rode Testar sincronização e crie as categorias de turma ausentes antes da primeira importação completa.
- Use um operador dedicado: configure um operador específico (ex: "Integração QI Solution") como Operador da sincronização, em vez de uma conta nominal.
- Sincronize fora do pico: o processo pode causar instabilidade temporária; prefira a janela automática da madrugada para grandes volumes.
- Revise os status habilitantes: mantenha em Status que devem habilitar o cadastro do aluno apenas os status que de fato devem liberar acesso (ex: Matriculado, Cursando).
- Não edite manualmente registros importados: alterações manuais em alunos, empresas e vínculos criados pela integração podem ser desfeitas na próxima sincronização.
Troubleshooting
"Testar sincronização" acusa categorias ausentes
Causa: as turmas retornadas pela QI Solution ainda não existem como Categorias no ACCELERO.
Solução:
- Anote as categorias listadas pela mensagem de teste.
- Cadastre-as em Categorias com a mesma descrição.
- Rode Testar sincronização novamente até não haver pendências.
Erro ao consultar a API / sincronização falha
Possíveis causas:
- Token, autorização ou endereço da API incorretos.
- API da QI Solution indisponível ou lenta (timeout).
- Bloqueio de saída no firewall do servidor ACCELERO.
Solução:
- Revise os campos da aba Geral e o Endereço da API da aba Importação de cadastros.
- Aumente o Timeout da API se a base for grande.
- Teste a conectividade do servidor ACCELERO até o endpoint da QI Solution.
- Persistindo, contate o suporte IONGRADE.
Falhas por timeout da API da QI Solution são registradas apenas como log de depuração, não como erro. A sincronização tenta novamente o consumo dos dados algumas vezes antes de desistir.
Aluno importado, mas sem acesso
Possíveis causas:
- Status de matrícula do aluno fora da lista de status que habilitam o cadastro.
- Turma (categoria) do aluno não cadastrada.
Solução:
- Confirme o status do aluno na QI Solution e na configuração de status habilitantes.
- Garanta que a categoria da turma existe.
- Rode Sincronizar agora.
Presença não chega à QI Solution
Possíveis causas:
- Endereço da API de presença não configurado.
- Nenhuma área marcada como "dentro" ou "fora".
- Sem eventos de acesso na data processada.
Solução:
- Verifique o Endereço da API na aba Relatório de presença.
- Confirme as Áreas que significam "dentro"/"fora".
- Use Testar envio de dados e, se necessário, Enviar dados manualmente para a data desejada.
Integração com outros módulos
Pessoas
A integração cria e mantém os cadastros de alunos, responsáveis e pessoas autorizadas. Ver Pessoas.
Empresas
Cada aluno é representado por uma Empresa (matrícula + nome) usada para vincular responsáveis e pessoas autorizadas. Ver Empresas.
Categorias
As turmas correspondem a categorias; as categorias padrão dos responsáveis também são configuradas aqui. Ver Categorias.
Tipos de associação
Definem o vínculo entre responsável e a empresa do aluno. Ver Tipos de associação.
Áreas
As áreas "dentro" e "fora" determinam como entradas e saídas são apuradas para o relatório de presença. Ver Áreas.
Logs e Eventos
A presença é apurada a partir dos eventos de acesso real registrados pelo sistema. Ver Logs e Monitoramento.
Próximos Passos
- Pessoas — Entenda o cadastro de pessoas mantido pela integração
- Empresas — Veja como cada aluno é representado por uma empresa
- Categorias — Cadastre as turmas antes de sincronizar
- Tipos de associação — Configure os vínculos dos responsáveis
- Áreas — Defina as áreas de entrada e saída para a presença
- Plugins — Saiba mais sobre o sistema de plugins do ACCELERO