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

1. Configure os webhooks necessários

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.

Eventos recomendados:

NewSale

RecurrentSale

CancelMembership

ScheduleCancelMembership

ClearedDebt

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 importantes para o fluxo:

idMember

email

dados da venda

dados dos recebíveis associados

4. Identifique o usuário na plataforma externa

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:

1 = Em aberto

2 = Recebido

3 = Cancelado

4 = Atrasado

Importante:
A regra de ativação, bloqueio ou reativação deve considerar a política comercial e financeira adotada pela integração.

Exemplo de Fluxo

Um usuário faz ou renova um plano na plataforma de gestão.

Um webhook de venda ou renovação é disparado para o sistema externo.

O sistema externo recebe o idSale.

O sistema consulta os detalhes da venda.

O sistema obtém o idMember e o e-mail do usuário.

O sistema faz o vínculo com o usuário na plataforma externa.

O sistema ativa o acesso e envia uma comunicação de ativação, se aplicável.

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:

venda realizada

renovação recorrente

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.

3. Como localizar o usuário na plataforma externa?

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.

Controle de acesso de aluno via serviço externo

Objetivo#

Endpoint#

Requisitos#

Passo a Passo#

1. Configure os webhooks necessários#

2. Trate os eventos de venda e renovação#

3. Consulte os detalhes da venda#

4. Identifique o usuário na plataforma externa#

5. Ative o acesso#

6. Trate os eventos de cancelamento#

7. Trate a quitação de saldo vencido#

8. Valide o status financeiro antes de ativar ou manter acesso#

Exemplo de Fluxo#

Perguntas Frequentes#

1. Quais eventos devem ser cadastrados no webhook?#

2. Como obter os dados do usuário após receber o webhook?#

3. Como localizar o usuário na plataforma externa?#

4. O acesso deve ser desativado em qualquer cancelamento?#

5. O que fazer quando um pagamento em atraso for regularizado?#

Resultado Esperado#

Dicas Finais#

Suporte#