Integração NovoMétodo

A integração NovoMétodo conecta o ACCELERO ao sistema de matrículas do NovoMétodo. O NovoMétodo envia eventos de matrícula para o ACCELERO, que cria automaticamente as turmas (categorias de pessoas) e os vínculos entre alunos, responsáveis e a empresa correspondente. É voltada a instituições de ensino que usam o ACCELERO para controle de acesso e querem manter pessoas e turmas em sincronia com o sistema acadêmico.

Disponibilidade

Esta integração é disponibilizada como plugin (novometodo) e precisa ser instalada e habilitada pela equipe técnica da IONGRADE. Consulte o suporte para verificar a compatibilidade com a sua versão do ACCELERO.

Compatibilidade

Versão atual do plugin: 0.1.0 — compatível com ACCELERO 2.16.0, 2.16.1, 2.16.2 e 2.16.3.

Depende da integração Education

O NovoMétodo localiza alunos pelo identificador education.id e empresas pelo empCodigo, ambos preenchidos pelo sincronismo do plugin Education. Para o NovoMétodo funcionar, o plugin Education precisa estar instalado e os cadastros já sincronizados.

---

O que a integração faz

A integração não tem telas operacionais próprias: ela expõe uma API que o NovoMétodo chama para criar ou remover matrículas. Cada chamada provoca a criação/atualização de registros no ACCELERO.

Funcionalidade	O que acontece no ACCELERO
Criação/atualização de matrícula	Ao receber uma matrícula, o ACCELERO localiza o aluno, cria a turma (se ainda não existir), vincula o aluno à turma e cria o vínculo pessoa–empresa com o tipo de relacionamento informado
Criação automática de turma	Se não existir uma categoria de pessoa com o código da turma (idClass), ela é criada com a descrição da turma (className) e já habilitada
Vínculo aluno–empresa por tipo	O tipo de relacionamento enviado (className) é convertido em um tipo de vínculo do ACCELERO (Responsável, Irmão, Aluno, Outros)
Remoção de matrícula	Ao receber uma remoção, o ACCELERO desfaz o vínculo do aluno com a turma e o vínculo pessoa–empresa correspondente

Benefício principal

Mantém turmas e vínculos de alunos e responsáveis sincronizados automaticamente a partir do NovoMétodo, sem cadastro manual de categorias e relacionamentos no ACCELERO.

Origem dos cadastros de pessoa e empresa

A integração não cria pessoas nem empresas. O aluno precisa já existir no ACCELERO (com education.id preenchido) e ter uma empresa com empCodigo igual ao seu identificador no Education. Se o aluno ou a empresa não forem encontrados, a chamada retorna erro.

---

Configuração

Caminho de acesso: Configurações > Integrações - NovoMetodo

A tela possui uma única aba: Geral.

TODO: Adicionar Screenshot

Tela de configuração Configurações > Integrações - NovoMetodo, aba Geral, mostrando o campo Token Accelero.

Aba Geral

Campo	Descrição
Token Accelero	Token de autenticação que o NovoMétodo deve enviar nas chamadas à API (cabeçalho Authorization: Bearer <token>). Defina o mesmo valor configurado do lado do NovoMétodo

Botões da tela

Botão	Função
Voltar	Retorna sem salvar
Salvar	Persiste a configuração

Token obrigatório

Sem o Token Accelero preenchido, todas as chamadas à API são rejeitadas. O token enviado pelo NovoMétodo precisa ser idêntico ao configurado aqui.

---

API de matrículas

A integração disponibiliza dois endpoints, ambos protegidos por autenticação via token. São chamados pelo NovoMétodo — não há tela no ACCELERO para acioná-los manualmente.

Método	Endpoint	Ação
PUT	/external/novometodo/matricula	Cria ou atualiza a matrícula (upsert)
DELETE	/external/novometodo/matricula	Remove a matrícula

Autenticação

As chamadas precisam do cabeçalho Authorization: Bearer <token>, onde <token> é o valor do campo Token Accelero. Requisições sem token, com token inválido ou com a integração mal configurada são recusadas.

Dados da matrícula (payload)

Campo	Usado em	Descrição
idPerson	PUT e DELETE	Identificador do aluno no NovoMétodo/Education — usado para localizar a pessoa pelo education.id
idClass	PUT e DELETE	Código da turma — vira o código da categoria de pessoa (turma) no ACCELERO
className	PUT	Descrição/tipo da turma — usada como descrição da turma e para definir o tipo de vínculo

TODO: Adicionar Diagrama

Diagrama do fluxo de uma chamada de matrícula: NovoMétodo → PUT /external/novometodo/matricula → localização do aluno → criação/uso da turma → vínculo aluno–turma → vínculo pessoa–empresa.

---

Mapeamento de tipo de vínculo

Ao criar a matrícula, o valor de className é convertido em um tipo de vínculo pessoa–empresa do ACCELERO:

Valor recebido (className)	Tipo de vínculo no ACCELERO
MOTHER, FATHER, GRANDFATHER, GRANDMOTHER, RESPONSIBLE, ADOPTER	Responsável
SISTER, BROTHER	Irmão
ALUNO	Aluno
OTHER	Outros
Qualquer outro valor	O próprio texto recebido é usado como descrição do tipo de vínculo

Se o tipo de vínculo correspondente ainda não existir no ACCELERO, ele é criado automaticamente.

---

Como o fluxo funciona

Criação/atualização de matrícula (PUT)

1. O ACCELERO localiza o aluno pela pessoa cujo education.id seja igual a idPerson. Se não encontrar, retorna erro Aluno não encontrado.
2. Procura a turma (categoria de pessoa) pelo código idClass. Se não existir, cria a turma com a descrição className, já habilitada.
3. Vincula o aluno à turma (se ainda não estiver vinculado) e habilita a pessoa.
4. Localiza a empresa pelo empCodigo igual a idPerson. Se não encontrar, retorna erro Empresa não encontrada.
5. Determina o tipo de vínculo a partir de className (ver mapeamento acima) e cria o vínculo pessoa–empresa (se ainda não existir).

Remoção de matrícula (DELETE)

1. Localiza o aluno pelo education.id. Se não encontrar, retorna erro Aluno não encontrado.
2. Localiza a turma pelo código idClass. Se não existir, retorna erro Turma não encontrada.
3. Remove o vínculo do aluno com a turma.
4. Remove o vínculo pessoa–empresa correspondente ao tipo derivado de className.

Erros retornam à API

Quando algo impede a operação (aluno, empresa ou turma não encontrados, dados inválidos, falha ao salvar/remover), a chamada retorna um erro com a mensagem correspondente. O NovoMétodo é o responsável por tratar e reprocessar esses erros.

---

Casos de uso

Habilitar a integração para uma instituição

1. Solicitar à IONGRADE a instalação do plugin novometodo.
2. Garantir que o plugin Education esteja instalado e que pessoas e empresas já tenham sido sincronizadas.
3. Em Configurações > Integrações - NovoMetodo, preencher o Token Accelero.
4. Informar o mesmo token e a URL da API ao responsável pela configuração no NovoMétodo.
5. Realizar uma matrícula de teste e conferir, no ACCELERO, a criação da turma e dos vínculos.

Matrícula de um aluno com responsável

1. O NovoMétodo envia uma matrícula com className = ALUNO para o aluno.
2. O NovoMétodo envia outra matrícula com className = MOTHER (ou outro responsável) para o mesmo idClass.
3. No ACCELERO, a turma é criada uma vez; o aluno fica com vínculo Aluno e o responsável com vínculo Responsável, ambos ligados à empresa do aluno.

---

Boas práticas

• Sincronize o Education primeiro: pessoas sem education.id e empresas sem empCodigo não são localizadas — confirme o sincronismo do Education antes de acionar matrículas.
• Token forte e idêntico nos dois lados: use um token longo e mantenha exatamente o mesmo valor no ACCELERO e no NovoMétodo.
• Use um valor de teste antes de produção: valide uma matrícula de teste e confira a turma e os vínculos criados antes de liberar o fluxo completo.

---

Troubleshooting

As chamadas retornam erro de token

Possíveis causas:

• Campo Token Accelero vazio na configuração.
• Token enviado pelo NovoMétodo diferente do configurado no ACCELERO.
• Cabeçalho Authorization ausente na requisição.

Solução:

1. Confirme o valor em Configurações > Integrações - NovoMetodo.
2. Garanta que o NovoMétodo envia Authorization: Bearer <token> com o mesmo valor.

Erro "Aluno não encontrado"

Possíveis causas:

• A pessoa correspondente ao idPerson não existe no ACCELERO.
• A pessoa existe, mas está sem o education.id preenchido.

Solução:

1. Verifique se o aluno foi sincronizado pelo plugin Education.
2. Reforce o sincronismo do Education e reenvie a matrícula.

Erro "Empresa não encontrada"

Possíveis causas:

• Não existe empresa com empCodigo igual ao idPerson do aluno.

Solução:

1. Confirme que o sincronismo do Education criou a empresa do aluno com o empCodigo correto.

Erro "Turma não encontrada" (na remoção)

Possíveis causas:

• A turma (idClass) nunca foi criada — não houve matrícula anterior, ou a categoria foi removida manualmente.

Solução:

1. Confirme que a matrícula correspondente existe antes de enviar a remoção.

---

Integração com outros módulos

Pessoas

A integração localiza alunos no cadastro de Pessoas pelo identificador do Education e os habilita ao vinculá-los a uma turma.

Empresas

Os vínculos são criados contra Empresas localizadas pelo empCodigo correspondente ao aluno.

Categorias (turmas)

Cada turma do NovoMétodo é representada por uma categoria de pessoa no ACCELERO, criada automaticamente quando necessário.

Education

A integração depende do sincronismo do plugin Education para que pessoas e empresas existam e estejam corretamente identificadas.

---

Próximos Passos

• Education — Entenda o sincronismo que alimenta pessoas e empresas usadas por esta integração
• Pessoas — Veja como os alunos são cadastrados e habilitados
• Empresas — Entenda os vínculos pessoa–empresa criados pela integração
• Plugins — Saiba mais sobre o sistema de plugins do ACCELERO