Integrar Moodle com Outros Sistemas: Web Services e OAuth 2

Integrar Moodle com outros sistemas é o que separa um AVA que dá trabalho de um AVA que trabalha sozinho. Quando a matrícula nasce no ERP acadêmico, o lead vem do CRM e a mensalidade cai no gateway de pagamento, cada sistema isolado vira planilha, retrabalho e aluno sem acesso. Este guia mostra como fazer essa ponte com web services, quanto ela custa para manter e o que o Moodle 5.3 mudou na autenticação.

TL;DR

• O jeito oficial de integrar Moodle com outros sistemas são os web services: um token, um conjunto de funções liberadas e chamadas REST em webservice/rest/server.php.
• O Moodle 5.3, lançado em 5 de outubro de 2026 e com suporte de segurança até 1º de outubro de 2029, trouxe OAuth 2 e tokens pessoais para a nova REST API do Moodle.
• A nova API ainda cobre poucas partes do Moodle. Para matrícula, usuários e notas, os web services clássicos continuam sendo o caminho em 2026.
• O custo real não está em escrever a integração. Está em mantê-la viva a cada atualização semestral do Moodle.
• Nem toda integração vale a pena: abaixo de algumas dezenas de matrículas por mês, um processo manual bem desenhado sai mais barato.

Por que integrar Moodle com outros sistemas (e quando não vale)

O Moodle é excelente em uma coisa: entregar e registrar aprendizagem. Ele não foi feito para ser ERP, CRM nem sistema de cobrança. Toda instituição que cresce acaba com três ou quatro sistemas em volta dele, e a pergunta deixa de ser "se" e passa a ser "como" eles conversam. Na prática, integrar Moodle com outros sistemas significa decidir quem manda em cada dado e automatizar o caminho entre eles.

Nos projetos que atendemos na Agathas Web, os sintomas de que falta integração se repetem:

• Matrícula manual: alguém da secretaria exporta CSV do sistema acadêmico e importa no Moodle toda semana. Um erro de digitação e o aluno fica sem acesso no primeiro dia de aula.
• Inadimplência sem efeito: o aluno deixa de pagar e continua com acesso, porque ninguém avisou o Moodle.
• Funil cego: o comercial não sabe quem do CRM de fato começou o curso, então não consegue medir de onde vem o aluno que conclui.
• Nota digitada duas vezes: o professor lança no Moodle e a secretaria redigita no diário oficial.

Quando NÃO integrar

Integração é software. Software exige manutenção. Se a sua operação matricula poucas dezenas de alunos por mês, em turmas fechadas e com pagamento à vista, a automação completa pode custar mais do que economiza. Nesses casos, recomendo começar pela inscrição em massa via CSV do próprio Moodle, com uma rotina documentada. Quando o volume ou o número de pessoas envolvidas crescer, aí sim vale integrar Moodle com outros sistemas de forma automática.

Outro caso em que eu seguro o cliente: quando os dados de origem estão bagunçados. Integrar um cadastro com CPFs duplicados só espalha a bagunça mais rápido. Primeiro saneia, depois conecta.

Os três caminhos para integrar Moodle com outros sistemas

Existem três formas técnicas de fazer o Moodle conversar com o mundo. Escolher a errada é a armadilha mais cara que eu vejo.

1. Web services clássicos (a API que todo mundo usa)

É a API histórica do Moodle e, hoje, a forma mais madura de integrar Moodle com outros sistemas sem mexer no core. Você habilita os web services, ativa o protocolo REST, cria um serviço externo com só as funções necessárias e gera um token para um usuário técnico. A partir daí, o outro sistema chama URLs como:

https://seumoodle.com.br/webservice/rest/server.php?wstoken=TOKEN&wsfunction=core_user_create_users&moodlewsrestformat=json

Funções que aparecem em quase toda integração:

• core_user_create_users e core_user_update_users para cadastro
• enrol_manual_enrol_users e enrol_manual_unenrol_users para liberar e retirar acesso
• core_course_get_courses para sincronizar o catálogo
• core_completion_get_course_completion_status para saber quem concluiu

2. A nova REST API do Moodle (onde entra o OAuth 2)

Desde as versões recentes, o Moodle vem construindo uma API REST "de verdade", com URLs orientadas a recurso e documentação OpenAPI navegável em Administração do site > Desenvolvimento > Moodle REST API UI. É nela que o 5.3 colocou o OAuth 2. Detalho isso na próxima seção.

3. Plugin local (quando a lógica precisa morar dentro do Moodle)

O core do Moodle não dispara webhooks nativamente. Se você precisa que o Moodle avise outro sistema quando algo acontece (aluno concluiu, nota foi lançada), o caminho é um plugin local com um observer de eventos que chama a API do outro lado. É também onde mora a lógica de pagamento: o Moodle traz só o PayPal como gateway padrão, e o resto vem de plugins.

Caminho	Direção	Bom para	Cuidado
Web services clássicos	Sistema externo → Moodle	Matrícula, usuários, notas, catálogo	Token de longa duração; exige escopo mínimo
Nova REST API (5.3)	Sistema externo → Moodle	Apps e integrações novas com OAuth 2	Cobertura ainda parcial de funções
Plugin local com eventos	Moodle → sistema externo	Avisar CRM, WhatsApp, ERP em tempo real	É código seu: precisa acompanhar cada versão

O que muda com o OAuth 2 nos web services do Moodle 5.3

O Moodle 5.3 saiu em 5 de outubro de 2026 e é uma versão LTS (suporte estendido): suporte geral até 4 de outubro de 2027 e correções de segurança até 1º de outubro de 2029, segundo as notas oficiais de versão. Na lista de novidades para desenvolvedores, o destaque de integração é o suporte a OAuth 2 nos web services roteados: servidor OAuth 2 no backend, gerenciador de clientes, endpoints de revogação de token e telas para administrar tudo isso (release notes do 5.3).

Na prática, o 5.3 oferece duas formas novas de obter token para a REST API, conforme a documentação de REST API tokens:

Tokens pessoais de acesso

O próprio usuário cria o token em Preferências, escolhe os escopos (o que o token pode fazer) e a validade: 7 dias, 1 mês (padrão), 2 meses, 3 meses ou 1 ano. O token aparece uma única vez e pode ser revogado na hora (documentação de tokens pessoais). Serve para scripts e automações pontuais.

Clientes OAuth 2

O administrador registra o aplicativo em Administração do site > Servidor > OAuth 2 clients. Os números que importam para quem vai integrar, de acordo com a documentação de clientes OAuth 2:

• Authorization Code para quando o usuário entra e autoriza o app; clientes públicos (app mobile) sempre usam PKCE
• Client Credentials para integração máquina a máquina, só em clientes confidenciais
• Access token dura 1 hora; o refresh token do fluxo Authorization Code dura 1 mês
• Client Credentials não recebe refresh token: o sistema pede um novo token quando o anterior expira
• Segredos expiram em 1 ano, com até dois ativos ao mesmo tempo para permitir rotação sem parada
• Desativar um cliente corta tokens e segredos imediatamente

Um alerta da própria documentação que vale repetir: no fluxo Client Credentials, o app age como o administrador principal do site, limitado apenas pelos escopos. Escopo largo nesse fluxo é uma chave mestra.

Por que isso é melhor que o token clássico

O token dos web services clássicos costuma ser criado uma vez e esquecido por anos, colado em um arquivo de configuração do ERP. Se vazar, vale até alguém lembrar de revogá-lo. Com OAuth 2, o token de acesso morre em uma hora, o segredo tem validade e a revogação é instantânea. Para quem passa por auditoria de LGPD e precisa integrar Moodle com outros sistemas sem deixar chave eterna espalhada, isso muda a conversa.

O limite que ninguém conta: a nova API ainda é parcial

Aqui está o ponto que os anúncios de lançamento pulam. A própria documentação do Moodle 5.3 diz que apenas algumas partes do Moodle estão disponíveis pela nova REST API, e que mais virão em versões futuras. Tokens da REST API não funcionam com as funções dos web services clássicos, e vice-versa. São sistemas separados.

O que isso significa para quem quer integrar Moodle com outros sistemas agora:

1. Matrícula, cadastro e notas continuam nos web services clássicos. É lá que estão as funções que o ERP e o gateway precisam.
2. OAuth 2 já vale para projetos novos que caibam nos escopos disponíveis, especialmente apps e painéis que só leem dados do próprio usuário.
3. Desenhe a integração com uma camada intermediária. Se o seu código de negócio não chama o Moodle diretamente, trocar o token clássico pelo OAuth 2 quando a função migrar vira ajuste de um módulo, não reescrita.

Outro detalhe operacional: os clientes OAuth 2 só aparecem se as dependências do Composer do site estiverem instaladas. Em hospedagem compartilhada ou em instalações feitas por "descompactar o zip", essa tela simplesmente não existe. Também pesa o upgrade em si: o 5.3 exige PHP 8.3 ou superior, MariaDB 11.4, MySQL 8.4 ou PostgreSQL 17, e só aceita atualização a partir do Moodle 4.4. Detalhei esses requisitos de servidor no guia de hospedagem Moodle: requisitos e custos.

ERP acadêmico, CRM e pagamento: como cada integração funciona

Cada tipo de sistema tem um fluxo típico na hora de integrar Moodle com outros sistemas e pede uma definição clara: quem é o "dono" de cada dado. Isso evita a maioria dos conflitos.

ERP ou sistema acadêmico

O ERP é o dono do cadastro e da matrícula. O fluxo padrão: aluno matriculado no ERP → chamada ao Moodle para criar o usuário (se não existir) → inscrição no curso ou grupo certo → no fim do período, o Moodle devolve conclusão e notas. A chave de ligação deve ser um identificador estável, como o campo idnumber do usuário, e nunca o e-mail, que o aluno troca. Descrevemos esse desenho em detalhe no guia técnico do SGA conectado ao Moodle.

CRM

O CRM é o dono do lead e da venda. A integração mais útil é de mão dupla: venda fechada no CRM gera matrícula no Moodle, e o Moodle devolve marcos (primeiro acesso, 50% do curso, conclusão) para o CRM disparar régua de relacionamento. O segundo sentido exige o plugin com eventos, porque o Moodle não avisa ninguém sozinho.

Gateway de pagamento

Aqui há duas escolhas:

• Pagamento dentro do Moodle, com a inscrição mediante pagamento e um plugin de gateway. Funciona bem para venda avulsa de curso.
• Pagamento fora do Moodle, no ERP ou no checkout, com webhook do gateway chamando a integração para liberar ou suspender o acesso. É o modelo certo para mensalidade recorrente, boleto e Pix com baixa assíncrona.

WhatsApp

Avisos de matrícula, lembrete de aula e alerta de inatividade funcionam melhor pela API Oficial do WhatsApp, disparados a partir dos eventos do Moodle. Um cuidado novo: com os usernames do WhatsApp, o identificador do contato nem sempre será o telefone, o que afeta o casamento entre aluno e conversa. Expliquei isso em usernames do WhatsApp e BSUID na API Oficial.

Armadilhas que eu mais vejo em integrações com o Moodle

Depois de anos ajudando instituições a integrar Moodle com outros sistemas em produção, estas são as falhas que mais geram chamado:

• Token de administrador na integração. É tentador porque "funciona tudo". Crie um usuário técnico, um serviço com só as funções necessárias, restrição de IP e data de validade no token, como recomenda a documentação de web services.
• Sem idempotência. O gateway reenvia o webhook, a integração matricula duas vezes ou cria usuário duplicado. Toda chamada precisa checar se a ação já foi feita.
• Sincronização em lote no horário de pico. Importar 5 mil usuários às 19h, quando os alunos estão online, derruba a performance. Rode fora do pico ou em fila.
• Nenhum log do lado da integração. Quando o aluno diz que pagou e não tem acesso, você precisa achar a chamada em segundos, não em horas.
• Funções descontinuadas. O 5.3 deprecou as antigas classes external_* usadas por plugins de web service. Plugin parado no tempo quebra no upgrade seguinte.
• Ninguém testa a integração antes de atualizar o Moodle. É o erro mais caro, e é o assunto da próxima seção.

Quanto custa integrar Moodle com outros sistemas (de verdade)

O desenvolvimento é a parte visível do que custa integrar Moodle com outros sistemas em uma instituição. Ele varia com três fatores: quantos sistemas entram, se o fluxo é de mão única ou de mão dupla e se é preciso escrever plugin dentro do Moodle.

O custo que pega desprevenido é o de manutenção. O Moodle lança duas versões por ano, em abril e outubro. Cada uma pode mudar requisitos de servidor, deprecar funções e alterar comportamento de plugins. Uma integração sem dono técnico tende a quebrar justamente na atualização de segurança que você não pode adiar.

Para orçar com realismo, some quatro itens:

1. Desenvolvimento: mapeamento dos dados, código da integração, plugin se houver
2. Homologação: ambiente de teste com cópia do Moodle e do outro sistema
3. Infraestrutura: fila, logs e monitoramento; integração em servidor sem cron confiável não funciona
4. Sustentação: revisão a cada versão do Moodle e a cada mudança de API do ERP, CRM ou gateway

Se o orçamento que você recebeu não tem os itens 2 e 4, ele não está mais barato. Está incompleto.

Como a Agathas Web resolve isso

A Agathas Web trabalha com Moodle há mais de 15 anos e tem a Moodle Developer Certification pela Moodle Academy. Somos uma empresa independente, não um Moodle Partner. Integrar Moodle com outros sistemas é parte do nosso serviço de desenvolvimento e sustentação de Moodle, junto com hospedagem, plugins e app.

O que normalmente entra no projeto:

• Integração com ERP e sistema acadêmico, incluindo o nosso SGA, com matrícula, cadastro e devolução de notas
• Gateway de pagamento com plugins próprios para ASAAS, Stripe e Pagar.me: boleto, Pix e cartão liberando o curso automaticamente
• SSO com Google Workspace, Microsoft Entra ou SAML
• WhatsApp pela API Oficial, disparado pelos eventos do Moodle
• Plugins sob medida para a sua regra de negócio, com o código ficando com você
• Planejamento do upgrade para o 5.3 e da migração gradual para OAuth 2 onde a nova API já cobre o caso

Como funciona na prática:

1. Diagnóstico gratuito de 1 hora: entendemos os sistemas, o volume e onde dói
2. Proposta técnica com arquitetura, cronograma e investimento
3. Desenvolvimento e homologação em ambiente separado do seu Moodle de produção
4. Sustentação mensal com atualizações, monitoramento e revisão das integrações a cada versão do Moodle

Para começar, agende o diagnóstico pela página de Moodle da Agathas Web e traga a lista dos sistemas que você quer conectar.

Conclusão: integre pelo processo, não pela ferramenta

O Moodle 5.3 tornou a autenticação das integrações mais segura, com tokens que expiram, escopos e revogação imediata. Mas a nova REST API ainda cobre pouco, e quem precisa integrar Moodle com outros sistemas hoje vai combinar web services clássicos, plugin de eventos e, onde couber, OAuth 2.

O caminho seguro é o mesmo de sempre: defina quem é o dono de cada dado, comece pelo fluxo que mais gera retrabalho e garanta que alguém vai cuidar da integração depois do lançamento. Se quiser ajuda para desenhar esse mapa, a equipe de desenvolvimento Moodle faz o diagnóstico sem compromisso.