Controle de acesso de aluno via serviço externo
Objetivo#
Ativar ou desativar automaticamente o acesso de usuários em uma plataforma externa com base no ciclo de vida da assinatura no EVO.Endpoint#
Este caso de uso depende principalmente de eventos via webhook e de consultas complementares aos endpoints de vendas, matr ículas e recebíveis da API.Requisitos#
webhooks de venda e recorrência: Devem estar configurados para notificar sempre que uma nova venda ou renovação ocorrer.
webhooks de cancelamento: Devem estar configurados para notificar cancelamentos imediatos ou agendados de matrícula.
webhook de quitação de saldo vencido: Deve estar configurado para notificar quando um débito vencido for regularizado.
identificador da venda: Necessário para consultar os dados completos da venda quando o evento retornar idSale.
identificador da matrícula: Necessário para consultar os dados da matrícula quando o evento retornar idMemberMembership.
e-mail do usuário: Necessário para realizar o vínculo entre o usuário da plataforma externa e o cadastro da plataforma de gestão.
Passo a Passo#
Cadastre os eventos de venda e renovação para capturar novas ativações de acesso.
Cadastre também os eventos de cancelamento e regularização financeira para refletir mudanças de status da assinatura.
2. Trate os eventos de venda e renovação#
Quando ocorrer uma nova venda ou renovação, o sistema externo receberá um webhook com o identificador da venda.
Armazene o idSale recebido para uso na consulta posterior.
3. Consulte os detalhes da venda#
Utilize o idSale recebido no webhook para consultar os detalhes completos da venda.
No retorno da venda, localize o objeto do membro e obtenha os dados necessários para integração.
dados dos recebíveis associados
Utilize o e-mail retornado no objeto do membro para localizar o usuário correspondente na plataforma externa.
Caso o usuário ainda não exista, siga a estratégia definida pelo seu sistema para criação, convite ou ativação.
5. Ative o acesso#
Quando a venda ou renovação estiver válida, ative o acesso do usuário na plataforma externa.
Se necessário, envie uma comunicação de ativação, convite ou link de primeiro acesso.
6. Trate os eventos de cancelamento#
Quando ocorrer um cancelamento de matrícula, imediato ou agendado, o sistema receberá um webhook contendo idMemberMembership.
Utilize esse identificador para consultar os dados da matrícula.
Com base no status e nas regras do seu sistema, desative o acesso imediatamente ou programe a desativação para a data correta.
7. Trate a quitação de saldo vencido#
Quando ocorrer o evento ClearedDebt, consulte novamente a venda com base no idSale retornado.
Verifique os recebíveis associados à venda e confirme o status financeiro do aluno.
Se a regularização restabelecer o direito de uso, reative o acesso na plataforma externa.
8. Valide o status financeiro antes de ativar ou manter acesso#
Ao consultar a venda, utilize o objeto de receivables para avaliar a situação do pagamento.
Considere os possíveis status financeiros:
A regra de ativação, bloqueio ou reativação deve considerar a política comercial e financeira adotada pela integração.Exemplo de Fluxo#
1.
Um usuário faz ou renova um plano na plataforma de gestão.
2.
Um webhook de venda ou renovação é disparado para o sistema externo.
3.
O sistema externo recebe o idSale.
4.
O sistema consulta os detalhes da venda.
5.
O sistema obtém o idMember e o e-mail do usuário.
6.
O sistema faz o vínculo com o usuário na plataforma externa.
7.
O sistema ativa o acesso e envia uma comunicação de ativação, se aplicável.
8.
Caso futuramente ocorra cancelamento ou atraso relevante, novos eventos atualizam esse acesso.
Perguntas Frequentes#
1. Quais eventos devem ser cadastrados no webhook?#
Para o fluxo completo, recomenda-se utilizar eventos de:cancelamento de matrícula
agendamento de cancelamento
quitação de saldo vencido
2. Como obter os dados do usuário após receber o webhook?#
Quando o webhook retornar idSale, consulte os detalhes da venda.
Quando retornar idMemberMembership, consulte os detalhes da matrícula.
O identificador mais comum para vinculação é o e-mail retornado nos dados do membro.
4. O acesso deve ser desativado em qualquer cancelamento?#
Isso depende da regra de negócio da integração.
Em cancelamentos agendados, pode ser necessário manter o acesso até a data efetiva de encerramento.
5. O que fazer quando um pagamento em atraso for regularizado?#
Utilize o evento de quitação do saldo vencido para revisar a situação financeira e, se aplicável, reativar o acesso.
Resultado Esperado#
Se todas as etapas forem seguidas corretamente:novas assinaturas e renovações passam a ativar o acesso automaticamente;
cancelamentos passam a desativar ou agendar a desativação do acesso;
regularizações financeiras permitem reavaliar e restabelecer o acesso quando aplicável.
Dicas Finais#
Sempre consulte os dados completos da venda ou da matrícula após o webhook.
Não tome decisões apenas com base no evento recebido; use os endpoints complementares para confirmar o estado atual.
Centralize a lógica de ativação e desativação em uma regra única no sistema externo.
Trate eventos duplicados de webhook com idempotência.
Registre logs de processamento para auditoria e reprocessamento.
Suporte#
Se houver dúvidas sobre os eventos disponíveis, payloads de webhook ou endpoints de consulta, consulte a documentação.Modified at 2026-05-15 03:49:27
