Acapadev SDK

Introdução ao Acapadev SDK

Bem-vindo à documentação detalhada do Acapadev SDK! Este pacote Composer serve como a ponte central de comunicação entre o Acapadev ID (a nossa base central de identidades) e a tua Aplicação Satélite Laravel.

Porquê um SDK?

Ao integrar aplicações, escrever código de base repetitivo para validar assinaturas, capturar pedidos HTTP, descodificar JSON e gerir chaves pode ser entediante e arriscado (falhas de segurança). O SDK garante:

Padronização: Todas as aplicações da nossa rede falam a mesma língua.
Segurança Máxima: A encriptação e validação HMAC são geridas pelo pacote, sem que tenhas de mexer em código sensível.
Agilidade: Em menos de 2 minutos passas de uma app vazia para uma app completamente conectada ao Single Sign-On.

🔔 Webhooks & Eventos Laravel

Recebe notificações da central com validação de assinatura HMAC e dispara o evento nativo WebhookReceived.

🔐 SSO via Socialite

Driver customizado AcapadevProvider para o Laravel Socialite, prontos a usar.

🧩 Facade Acapadev

Ponte direta para a API central, com autenticação Client Credentials automática e renovação de token.

🧑‍🤝‍🧑 Cargos e Permissões

Trait HasAcapadevRoles para herdar automaticamente os cargos definidos na central, com cache incluída.

🛡️ Single Logout (Zero Trust)

Middleware EnsureAcapadevSession que garante que a sessão local nunca fica desatualizada em relação à central.

⚙️ Instalação Guiada

Comando php artisan acapadev:install configura as tuas variáveis de ambiente de forma interativa.

Instalação

Instala o pacote via Composer no teu projeto Laravel:

composer require devkussema/acapadev-sdk

De seguida, corre o comando de instalação. Ele publica o ficheiro de configuração config/acapadev.php e ajuda-te a preencher as variáveis necessárias no .env:

php artisan acapadev:install

O comando acapadev:install pergunta interativamente pelo ACAPADEV_WEBHOOK_SECRET, ACAPADEV_CLIENT_ID e ACAPADEV_CLIENT_SECRET. Se deixares o Webhook Secret em branco, o SDK gera automaticamente um valor aleatório seguro.

Variáveis de Ambiente

Depois da instalação, o teu .env deve conter (no mínimo) as seguintes chaves:

ACAPADEV_URL=https://id.acapadev.com
ACAPADEV_CLIENT_ID=
ACAPADEV_CLIENT_SECRET=
ACAPADEV_WEBHOOK_SECRET=
ACAPADEV_REDIRECT_URI=/auth/acapadev/callback
ACAPADEV_WEBHOOK_PATH=acapadev/webhook

O ACAPADEV_URL é o host de SSO. A API REST vive num host próprio (api.acapadev.com), que o SDK deriva automaticamente trocando id. por api. — por isso, na maioria dos casos, não precisas de o declarar. Só é necessário quando o teu ambiente não segue esse padrão:

# Opcional — tem prioridade sobre a derivação automática
ACAPADEV_API_URL=https://api.staging.acapadev.com

Usa a v1.2.1 ou superior

Versões anteriores tinham defeitos que faziam a leitura de cargos e o perfil do SSO falhar em silêncio. Antes de escreveres qualquer contorno para um sintoma estranho, confirma a versão e lê Problemas Conhecidos — é provável que o problema já não exista.

Documentação Local

Todo o conteúdo desta secção também está disponível offline dentro do próprio pacote. Podes publicá-lo para o teu projeto (útil para consulta rápida na tua equipa) com:

php artisan acapadev:docs

Próximos Passos

Explora as secções seguintes para veres cada funcionalidade do SDK em detalhe: Webhooks & Eventos, SSO com Socialite, o Cliente de API (Facade), Cargos e Permissões, e Sincronização de Sessão.

← AcapaPay CodeIgniter Webhooks & Eventos →