Desenvolvedores · Documentação da API

Integração Moodle

Como o EduPay e o Moodle se integram: plugin, login único, bloco do aluno, coortes, bloqueio por atraso e rotas do plugin.

O EduPay e o Moodle conversam nos dois sentidos:

  • Do Moodle para o EduPay, pelo plugin instalado no Moodle: o aluno entra no Moodle com o login do EduPay, vê a situação financeira num bloco e abre o portal do aluno sem digitar senha.
  • Do EduPay para o Moodle, pelo serviço web do Moodle: quando a matrícula é feita, o EduPay cria o usuário no Moodle e o coloca na coorte da turma. Se o aluno atrasa, o EduPay o tira da coorte; quando ele paga, devolve.

Esta página descreve a integração como ela funciona hoje, para quem instala o plugin e para quem dá suporte à escola.

As peças

Peça Onde fica Para quê
Plugin auth_edupay (Edupay SSO) Moodle, em auth/edupay Botão "Entrar com edupay" na tela de login do Moodle
Plugin block_edupay (Portal Financeiro edupay) Moodle, em blocks/edupay Bloco com o resumo financeiro e o botão do portal do aluno
Integração Moodle do EduPay Painel do EduPay, em Integrações → Plataformas LMS Endereço do Moodle e o token do serviço web, para o EduPay matricular, bloquear e liberar

Os dois plugins funcionam no Moodle 4.1 ou mais novo e estão em português, inglês e espanhol.

O que o aluno vê

  • No login do Moodle, o botão Entrar com edupay. Ele entra com o mesmo e-mail (ou CPF) e a mesma senha do portal do aluno do EduPay.
  • No Moodle, o bloco Portal Financeiro edupay com "Bem-vindo, nome", quantas parcelas estão em aberto, a situação do contrato e o botão Acessar portal financeiro, que abre o portal do aluno numa aba nova, já conectado.
  • No portal do aluno do EduPay, o botão para o sistema acadêmico, que abre o Moodle já conectado (depois que o aluno foi sincronizado com o Moodle pelo menos uma vez).
  • Nos cursos, ele entra sozinho quando a matrícula é feita, sai se atrasar o pagamento além do prazo da escola e volta quando paga.

Instalar no Moodle

Quem instala é um administrador do Moodle.

  1. Peça à equipe do EduPay os arquivos auth_edupay.zip e block_edupay.zip.
  2. Em Administração do site → Plugins → Instalar plugins, envie os dois (ou copie as pastas edupay para auth/ e blocks/) e conclua a atualização do Moodle.
  3. Em Administração do site → Plugins → Autenticação → Gerenciar autenticação, habilite Edupay SSO.
  4. Em Administração do site → Recursos avançados, ligue os serviços web, e em Plugins → Serviços web → Gerenciar protocolos, ligue o REST. O plugin não liga isso sozinho.

Instale os dois plugins, mesmo que a escola só queira o bloco: os usuários que o EduPay cria no Moodle usam o método de autenticação do auth_edupay.

Na instalação, o bloco cria no Moodle o serviço externo Edupay Integration (edupay_integration), com as seis funções que o EduPay usa (veja "Do EduPay para o Moodle", abaixo).

Configurar

1. No EduPay: as chaves dos plugins

Em Integrações → Tokens de API, crie a chave com um dos pacotes do Moodle:

Pacote Permissões Onde usar
Moodle (completo) moodle:auth, moodle:student, moodle:portal Nos dois plugins
Moodle (somente SSO) moodle:auth No auth_edupay
Moodle (somente bloco) moodle:student, moodle:portal No block_edupay

A chave do Moodle funciona com a API pública ligada ou desligada. Ao rotacionar, a chave antiga vale só mais 24 horas: troque nos dois plugins dentro desse prazo.

2. No Moodle: os plugins

auth_edupay (Administração do site → Plugins → Autenticação → Edupay SSO):

Configuração O que é Padrão
URL do edupay O endereço do EduPay (https://edupay.estudiosite.com) vazio
Token de API A chave edp_... com moodle:auth vazio
Texto do botão O texto do botão na tela de login Entrar com edupay
Criar usuários automaticamente Cria o usuário no Moodle no primeiro login, se ainda não existir ligado
Atualizar usuário no login A cada login, atualiza nome e sobrenome com os do EduPay ligado

block_edupay (Administração do site → Plugins → Blocos → Portal Financeiro edupay):

Configuração O que é
URL do edupay O endereço do EduPay
Token de API A chave edp_... com moodle:student e moodle:portal
Token REST do Moodle Botão Gerar: cria o token que o EduPay usa para chamar o Moodle (veja o passo 3)

Depois, adicione o bloco no painel (Dashboard) ou nas páginas dos cursos. Em cada bloco dá para esconder o resumo e trocar o texto do botão.

3. No EduPay: a integração com o Moodle

  1. No Moodle, nas configurações do bloco, clique em Gerar no Token REST do Moodle e copie o token. Ele é do administrador que clicou, não vence e serve só ao serviço Edupay Integration. Regenerar apaga os tokens anteriores do serviço.
  2. No EduPay, em Integrações → Plataformas LMS → Moodle, preencha a URL base do Moodle (com https://, exatamente o endereço do site Moodle), cole o Token REST, ligue a integração e salve.
  3. Clique em Testar conexão.

4. Turmas e cursos

O EduPay coloca o aluno numa coorte do Moodle. Quem leva a coorte para dentro dos cursos é o próprio Moodle:

  1. Cada turma do EduPay se liga a uma coorte. Ao criar a turma, marque Criar também no Moodle; numa turma que já existe, use o botão Criar coorte no Moodle na página da turma. A coorte é criada no site todo, e os alunos já matriculados na turma são enviados ao Moodle. Também dá para informar à mão o ID da coorte no Moodle — é o número interno da coorte (o id que aparece no endereço da coorte), não o campo "ID number".
  2. Em cada curso do Moodle, adicione o método de inscrição Sincronização de coorte com essa coorte.

Login único: como funciona

  1. O aluno clica em Entrar com edupay no Moodle.
  2. O Moodle o leva a https://edupay.estudiosite.com/moodle/sso, informando o endereço do próprio Moodle. O EduPay acha a escola por esse endereço: ele precisa ser igual à URL base cadastrada na integração.
  3. Se o aluno já está conectado no portal do EduPay, segue direto. Senão, entra com o login e a senha do portal.
  4. O EduPay devolve o aluno ao Moodle com um código de uso único, que vale 5 minutos.
  5. O plugin troca o código pelos dados do aluno (nome e e-mail), acha o usuário do Moodle pelo e-mail — ou cria, se "Criar usuários automaticamente" estiver ligado — e conecta o aluno.

O login normal do Moodle continua para quem não usa o botão. Usuários com o método edupay só entram pelo botão: a senha do Moodle não vale para eles, nem a troca de senha do Moodle.

Do EduPay para o Moodle

O EduPay chama o serviço web do Moodle (/webservice/rest/server.php) com o token REST:

Função do Moodle Quando
core_webservice_get_site_info Testar conexão
core_user_get_users Achar o usuário do aluno pelo e-mail
core_user_create_users Criar o usuário, se não existir (login = e-mail, método edupay)
core_cohort_create_cohorts Criar a coorte da turma
core_cohort_add_cohort_members Colocar o aluno na coorte (matrícula e liberação)
core_cohort_delete_cohort_members Tirar o aluno da coorte (bloqueio e cancelamento)

Quando o aluno entra, sai e volta:

Momento O que acontece no Moodle
Matrícula feita pela escola (painel ou API) Entra na coorte na hora
Compra pela página de vendas Entra quando o primeiro pagamento é confirmado (na hora, se não houver nada a pagar)
Parcela vencida há mais dias que o prazo da escola Sai da coorte (rotina diária, de madrugada)
Pagamento que zera o atraso Volta para a coorte
Matrícula cancelada Sai da coorte

O prazo de bloqueio é o campo Dias para marcar como vencida em Configurações (padrão: 30). Apesar do nome, a parcela vira vencida no dia seguinte ao vencimento; esse número só decide quantos dias de atraso tiram o aluno do Moodle.

Quando uma chamada ao Moodle falha, a matrícula fica com a sincronização "falhou" e o erro aparece na integração. Na tela da matrícula, o botão Resincronizar tenta de novo.

Pontos de atenção

  • Tudo se liga pelo e-mail. O aluno do EduPay e o usuário do Moodle são o mesmo quando o e-mail é o mesmo. Aluno sem e-mail não vai para o Moodle.
  • "Atualizar usuário no login" troca o método de autenticação de um usuário do Moodle que já existia com o mesmo e-mail para edupay. Depois disso, a senha antiga dele no Moodle para de funcionar. Para professores e administradores com e-mail igual ao de um aluno, desligue essa opção.
  • Alteração de nome ou e-mail no EduPay não chega ao Moodle sozinha. O nome é atualizado no próximo login pelo botão, se a opção estiver ligada.
  • Concluir a matrícula não tira o aluno do Moodle. Só o cancelamento e o bloqueio por atraso tiram.
  • Sair da coorte tem no curso o efeito configurado na inscrição por coorte do Moodle. No padrão do Moodle, o aluno é desinscrito do curso.
  • Professores e administradores que não são alunos no EduPay veem no bloco "Não foi possível carregar dados". É esperado.
  • O bloco guarda o resumo por 5 minutos na sessão do Moodle. Um pagamento novo aparece no bloco depois disso, ou no próximo login.

Rotas usadas pelos plugins

As rotas abaixo são só dos plugins. Elas estão congeladas: não mudam com as versões da API pública, para o plugin instalado nas escolas continuar funcionando sem atualização. Para integrar outros sistemas, use a API pública.

Rota Permissão Resposta de sucesso
GET /api/moodle/auth/verify?token= moodle:auth {"name", "email", "student_id"}
GET /api/moodle/student/summary?email= moodle:student {"student_name", "open_installments", "contract_status", "contract_status_label"}
POST /api/moodle/auth/portal-token (corpo {"email"}) moodle:portal {"url", "expires_in": 300}
  • Chave no cabeçalho Authorization: Bearer edp_..., a mesma das chaves da API pública. A escola é a da chave.
  • Erros no formato antigo, {"error": "..."}: 401 "Unauthorized", 403 "Forbidden — insufficient scope", 404 "Not found" (ou "Invalid or expired token" e "Student not found" no verify) e 422 "Portal not configured".
  • Limite de 60 chamadas por minuto por chave, separado dos limites da API pública.
  • Não dependem do interruptor da API pública.

O Moodle na API pública

Para acompanhar a sincronização de outro sistema:

  • GET /students/{id} traz moodle_user_id, o número do usuário no Moodle.
  • GET /enrollments traz moodle_sync_status: null (ainda não foi para o Moodle), synced, suspended (fora da coorte por atraso), removed (fora por cancelamento) ou failed.
  • GET /cohorts traz moodle_cohort_id, e GET /offerings, moodle_course_id.
  • Os avisos enrollment.suspended e enrollment.reactivated chegam quando o aluno sai da coorte por atraso e quando volta. Veja Avisos automáticos.
  • POST /students/{id}/portal-link gera o mesmo link de entrada no portal que o bloco usa, para qualquer sistema.