APRESENTAÇÃO

O Accelero tem uma integração com o ERP escolar Gennera. Esse sistema faz o controle de alunos, matrículas, grades curriculares, etc... A integração consiste em duas partes:

1. trazer para o Accelero cadastros de pessoas (alunos e responsáveis, basicamente) e suas características (aluno de qual sala? responsável de qual aluno?);
2. enviar para o Gennera a informação de "quem esteve na escola durante o dia, de quando até quando".

ARQUITETURA

O Gennera tem um sistema de webhooks que pode ser configurado pra enviar eventos para um endpoint (Accelero). A Iongrade não tem acesso a essa configuração, mas sabemos que:

• cada escola pode ter webhooks específicos;
• existem diversos eventos que podem ser configurados (por exemplo, cadastro de aluno, alteração de aluno, nova matrícula, etc...);
• o payload dos webhooks é razoavelmente configurável (eles oferecem um objeto JS e você pode criar um script pra montar o payload do jeito que quiser -- orientamos a mandar o "objetão" inteiro, e fazemos o parse do nosso lado).

A Gennera também tem uma API extensa que pode ser usada pra buscar dados quando necessário (https://api2.gennera.com.br/docs/).

Para o envio de dados de frequência de alunos, é tudo feito pela API. Esse envio acontece todos os dias de madrugada durante o daily_schedule (sempre enviamos os dados "de ontem"). Para receber dados/cadastros, usamos uma mistura de webhooks + API (às vezes é necessário complementar dados recebidos pela API).

Existe um token de autenticação (Header: Authorization) que é usado em todos os requests (usamos o mesmo token na API e no webhook).

As entidades dos dois sistemas são bem diferentes, então existem algumas adaptações pra fazer a coisa toda funcionar. Por exemplo, não existem no Accelero os conceitos de "turma" ou "responsável", coisas que são básicas e importantes para o Gennera. Mais à frente será detalhada essa "adaptação de entidades"

WEBHOOKS

Pelo que sabemos, os webhooks do Gennera são disparados "de hora em hora" (não é em tempo real). A seguir, a listagem de todos (vide rotas Gennera).

upsertPerson

Cria ou atualiza uma pessoa (aluno, responsável, amigo, parente... qualquer coisa...). Buscamos no DB alguém cujo "ID Gennera" (pesMetadata -- $gennera.idPerson) seja igual ao recebido no request... se não achar, tentamos buscar pelo CPF... se não achar, é pessoa nova.

deactivatePerson

Desabilita uma pessoa pelo $gennera.idPerson.

upsertTurma

Não faz nada.

deleteTurma

Não faz nada.

upsertRelationship

Primeiro o Gennera envia pro Accelero o cadastro de pessoas (request upsertPerson). Depois, ele pode fazer requests "associando" duas pessoas, dizendo que "<A> é <relação> de <B>". Por exemplo, "João ID123 é PAI de Mariazinha ID456".

Esse tratamento faz o seguinte:

• garante que existe uma Empresa cujo código/descrição é igual ao idPerson da pessoa-base (campo target do request, geralmente o aluno).
• associa a pessoa owner (é um idPerson, campo recebido no request) a essa empresa com o "Tipo de associação" recebido no request (relationshipType, é feito um mini-tratamento pra normalizar, vide GenneraDTOFactory).

Com isso, teremos "uma empresa por aluno", e os responsáveis desse aluno associados a essa empresa. Em outro request o aluno também será associado a essa empresa, de modo que no final toda a família (pai, mãe, aluno, responsáveis) estarão associados nessa "empresa/família", cada um com seu "papel" (fulano é pai, ciclana é mãe...).

deleteRelationship

Exclui um relacionamento criado por um upsertRelationship.

upsertMatricula

Esse request diz que "Joãozinho é da classe 1a. B". Classes (className) com nome muito pequeno (menos que 3 caracteres) são ignoradas porque foi combinado dessa forma.

O request envia a pessoa, a turma e um status de matrícula. Pode enviar também o "ID do responsável acadêmico".

Esse request é tratado assim:

• garante que a pessoa existe no banco de dados (cria na hora, se for necessário);
• garante que existe uma categoria cujo código é igual ao ID da turma (idClass);
• garante que existe uma empresa com código/descriçào igual ao idPerson do aluno (igual upsertRelationship);
• associa o aluno a essa empresa com o "Tipo de associação" igual ao nome da turma (criando na hora, se necessário, o "Tipo de associação");
• se foi enviado um responsável acadêmico
  • garante que essa pessoa existe no banco de dados (se necessário, consulta a API da Gennera);
  • associa essa pessoa à categoria que foi definida nas configurações globais da integração;
• consulta na API da Gennera todos os relationships do aluno e faz o cadastro de tudo (basicamente um upsertRelationship ao contrário, a gente consultando a API);
• associa (ou desassocia, dependendo do status recebido) o aluno à turma;

changeMatricula

Request especial pra "troca de sala". Basicamente é um wrapper para "upsertMatricula desabilitando turma antiga" + "upsertMatricula habilitando turma nova". Isso Existe porque, por algum motivo, esse é um evento específico no Gennera.

PROBLEMAS DO MUNDO REAL QUE PRETENDEMOS RESOLVER COM A INTEGRAÇÃO

Categorias de acesso

Como as turmas recebidas do Gennera são cadastradas como categorias no Accelero, fica intuitivo pro usuário final configurar as políticas de acesso. Algo como "Alunos da categoria '3a. série' podem entrar em horário XYZ e sair em horário ABC".

Como é possível configurar categorias a serem atribuídas automaticamente para responsáveis, fica automático "liberar acesso" pra que os pais tenham acesso ao colégio pra poder buscar os filhos.

Como a "família" está toda agrupada dentro da mesma Empresa, é possível usar o "Monitor de chegadas" pra fazer um sistema de pré-chamada: o pai chega pra buscar a criança, o Accelero verifica "quem são os alunos que compartilham a(s) mesma(s) família(s) desse pai" e mostra em tela para o inspetor de alunos, que pode já ir "buscando o menino". Mais ainda, o monitor de chegadas permite o uso de "Ações rápidas", o que possibilita configurar cenários como: o menino não tem permissão pra sair do colégio em nenhum horário. Quando o monitor de chegadas identifica que "chegou o pai do Joãozinho", é possível ali mesmo atribuir uma categoria temporária (SAÍDA AUTORIZADA, por exemplo) durante um período curto (10 minutos? Configurável) para o aluno, de modo que apenas naquela janela de tempo ele terá autorização pra sair.

Como o cadastro de alunos e responsáveis é sincronizado automaticamente, o colégio pode centralizar seus cadastros em um único sistema.

Como o Accelero devolve pro Gennera a informação de "quem entrou, e quando", o Gennera pode automaticamente "dar presença" pros alunos na aula de matemática, inglês e português, porque essas eram as matérias que teve aula durante o período que o aluno esteve na escola.