Integração com a API Cademi

A Cademi é uma plataforma brasileira para criação de áreas de membros, usada para hospedar, organizar e vender cursos online e outros produtos digitais. A integração do nosso sistema com a Cademi foca em matricular e desmatricular vendedores (sellers) nos produtos digitais, sincronizando seu status de acesso de forma automática.

Visão Geral

A integração permite que o status de um vendedor em um determinado serviço seja refletido na plataforma Cademi. As principais funcionalidades são:

• Habilitar Vendedor: Concede acesso a um vendedor na Cademi, associando-o a um produto.
• Desabilitar Vendedor: Revoga o acesso de um vendedor na Cademi.
• Listar Usuários: Lista todos os usuários cadastrados na plataforma Cademi.
• Deletar Usuário: Remove um usuário específico da plataforma Cademi pelo CPF.

Essas ações podem ser executadas de forma automática (quando um vendedor é criado ou deletado) ou manual (através do painel de administração).

Componentes Principais

A integração é estruturada em torno de uma classe de API, classes de suporte (Endpoint e Payload), Jobs para processamento assíncrono e gatilhos no sistema (Observers e painel Filament).

CademiAPI

É a classe central que encapsula toda a comunicação com a API da Cademi.

• Localização: app/Integrations/Cademi/CademiAPI.php

Responsabilidades:

• Autenticação: Envia as credenciais (Authorization e token) necessárias em cada requisição.
• Operações: Contém os métodos para as principais ações da API, utilizando as classes CademiEndpoint e CademiPayload para montar as requisições.
• Tratamento de Erros: Lança uma Exception se a resposta da API não indicar sucesso (success: false).
• Rate Limiting: Todas as requisições passam pelo CademiRateLimiter para respeitar o limite de taxa da API.
• Logging: Todas as requisições e respostas são logadas para facilitar a depuração.

Métodos disponíveis:

• enableSeller(Seller $seller, string $cademi_cod): Habilita um vendedor na Cademi.
• disableSeller(Seller $seller, string $cademi_cod): Desabilita um vendedor na Cademi.
• users(): Lista todos os usuários cadastrados na plataforma.
• delete(string $cpf): Remove um usuário específico pelo CPF.

Classes de Suporte

CademiEndpoint

Esta classe centraliza todos os endpoints (URIs) da API da Cademi, evitando a repetição de strings no código e facilitando a manutenção.

• Localização: app/Integrations/Cademi/CademiEndpoint.php

class CademiEndpoint
{
    const ENABLE_SELLER = '/postback/custom';
    const DISABLE_SELLER = '/postback/custom';
    const USERS_LIST = '/v1/usuario';
    const USER_DELETE = '/v1/usuario/%s';
}

CademiPayload

Responsável por construir o corpo (payload) das requisições enviadas para a API. Garante que os dados enviados estejam no formato esperado pela Cademi.

• Localização: app/Integrations/Cademi/CademiPayload.php

O método enableSeller, por exemplo, monta um array com todos os dados do vendedor e do produto, além de definir o status como aprovado.

class CademiPayload
{
    const STATUS_ENABLED = 'aprovado';
    const STATUS_DISABLED = 'cancelado';

    public static function enableSeller(Seller $seller, string $token, string $cademi_cod)
    {
        return  [
            'token' => $token,
            'codigo' => $cademi_cod,
            'status' => self::STATUS_ENABLED,
            'produto_id' => $seller->service->proposal->event_id,
            // ... outros dados do cliente
        ];
    }
    // ...
}

CademiRateLimiter

Classe responsável por gerenciar o rate limiting das requisições à API da Cademi, garantindo que o limite de 2 requisições por segundo seja respeitado.

• Localização: app/Integrations/Cademi/CademiRateLimiter.php

Funcionamento:

• Utiliza cache do Laravel com locks atômicos para garantir que apenas 2 requisições sejam executadas por segundo.
• Implementa um sistema de retry automático com timeout máximo de 5 segundos.
• Se uma requisição não puder ser executada dentro do limite de tempo, lança uma RuntimeException.
• Mantém um histórico de timestamps das últimas requisições no cache.

Métodos:

• throttle(callable $callback): Executa o callback respeitando o rate limit, com retry automático.
• clear(): Limpa o estado do rate limiter (útil para testes ou manutenção).

// Exemplo de uso interno na CademiAPI
public function enableSeller(Seller $seller, string $cademi_cod)
{
    return $this->rateLimiter->throttle(function () use ($seller, $cademi_cod) {
        // Requisição HTTP aqui
    });
}

Actions: EnableInCademi e DisableInCademi

O sistema utiliza o padrão de Actions (via pacote lorisleiva/laravel-actions) para executar as operações de integração com a Cademi. Isso permite que as mesmas actions sejam executadas de forma síncrona ou assíncrona (como Jobs).

• Localização: app/Actions/Seller/

EnableInCademi:

• Gera um código único (Str::ulid()) para o vendedor.
• Chama a CademiAPI para habilitar o vendedor.
• Atualiza o vendedor local com o código gerado.
• Implementa tratamento de erros com logging.
• Pode ser executada como Job usando EnableInCademi::dispatch($seller).

DisableInCademi:

• Usa o cademi_cod existente do vendedor.
• Chama a CademiAPI para desabilitar o vendedor.
• Remove o código do vendedor local.
• Implementa tratamento de erros com logging.
• Pode ser executada como Job usando DisableInCademi::dispatch($seller).

SellerObserver

Automatiza a integração com a Cademi em dois momentos do ciclo de vida do vendedor: criação e exclusão.

• Localização: app/Observers/SellerObserver.php

Método created: Quando um vendedor é criado, o observer verifica se a integração está ativa para o evento (baseado nas datas cademi_start_date e cademi_end_date). Se estiver ativo, despacha a action EnableInCademi de forma assíncrona.

Método deleted: Quando um vendedor é deletado, o observer automaticamente despacha a action DisableInCademi para revogar o acesso na plataforma Cademi.

// app/Observers/SellerObserver.php
public function created(Seller $seller): void
{
    $event = $seller->service->proposal->event;

    if ($event->cademi_start_date <= now() && $event->cademi_end_date >= now()) {
        EnableInCademi::dispatch($seller);
    }
}

public function deleted(Seller $seller): void
{
    DisableInCademi::dispatch($seller);
}

SellersRelationManager (Filament)

No painel de administração, a gestão manual da integração é feita através de uma coluna na tabela de vendedores.

• Localização: app/Filament/{Admin|Client}/Resources/ServiceResource/RelationManagers/

Um ícone de toggle permite habilitar ou desabilitar um vendedor de forma síncrona (dispatchSync), e um ícone de "spinner" com atualização automática da tabela (polling) informa o usuário enquanto a operação está em andamento.

Modelo de Dados (sellers)

O campo cademi_cod na tabela sellers é crucial para a integração:

• null: O vendedor não está integrado ou foi desabilitado.
• 'integrating': O processo de integração está em andamento.
• (string): O vendedor está ativo na Cademi, e o valor é seu identificador único na plataforma.

Comandos Artisan

• sellers:enable-in-cademi: Habilita em massa todos os vendedores sem código Cademi em eventos ativos (dentro do período cademi_start_date e cademi_end_date). Este comando é útil para:
  • Recuperar integrações que falharam
  • Integrar vendedores criados antes da ativação da integração
  • Re-sincronizar vendedores após manutenções

Configuração

As credenciais da API da Cademi devem ser configuradas no arquivo .env:

CADEMI_URL=https://url.da.api.cademi/
CADEMI_AUTHORIZATION="Bearer ..."
CADEMI_TOKEN=seu_token_interno

Estas variáveis são lidas a partir do arquivo config/cademi.php.