Acapadev SDK

Acapadev API Client (Facade)

O SDK inclui uma ponte direta para a API central do Acapadev ID através do serviço AcapadevApiClient, exposto pela Facade Acapadev. Isto permite que a tua aplicação faça pedidos à API central autenticando-se automaticamente como uma máquina (OAuth2 Client Credentials Grant).

Exemplo de Uso

Para usares a API, basta chamares a Facade Acapadev:

use Acapadev\Sdk\Facades\Acapadev;

// Fazer um pedido GET
$utilizadores = Acapadev::get('/users/active');

// Fazer um pedido POST
$resposta = Acapadev::post('/logs/register', [
    'action' => 'login',
    'app' => 'token.ao',
]);

// Buscar cargos de um utilizador específico (nunca lança; [] em caso de falha)
$cargos = Acapadev::getUserRoles($acapadevUserId);

// Mesma leitura, mas propaga a falha em vez de a esconder
$cargos = Acapadev::fetchUserRoles($acapadevUserId);

A Facade trata automaticamente de gerar e renovar o access_token usando o ACAPADEV_CLIENT_ID e ACAPADEV_CLIENT_SECRET configurados no teu .env. Todos os pedidos são feitos e recebidos em JSON.

Os Dois Hosts

Esta é a distinção que causa mais problemas de integração, por isso vale a pena fixá-la:

Host	Serve	Configurado em
id.acapadev.com	SSO / OAuth: /oauth/authorize, /oauth/token	ACAPADEV_URL
api.acapadev.com	API REST: /v1/user, /v1/users/{id}/roles, faturação	derivado, ou ACAPADEV_API_URL

Os caminhos que passas à Facade são relativos à raiz da API já versionada:

Acapadev::get('/users/3/roles');   // → https://api.acapadev.com/v1/users/3/roles

O SDK deriva o host da API a partir do ACAPADEV_URL, trocando id. por api., portanto normalmente não precisas de configurar nada:

ACAPADEV_URL=https://id.acapadev.com    →  https://api.acapadev.com
ACAPADEV_URL=https://id.acapadev.test   →  https://api.acapadev.test

Se o teu ambiente não seguir esse padrão, define o host explicitamente — tem sempre prioridade sobre a derivação:

ACAPADEV_API_URL=https://api.staging.acapadev.com

Autenticação Automática (Client Credentials)

O token de acesso é obtido junto de {ACAPADEV_URL}/oauth/token usando grant_type=client_credentials, e é guardado em cache pelo tempo definido em acapadev.cache.token_ttl (por padrão 3000 segundos):

// Lógica interna do SDK (não precisas de escrever isto)
Http::asForm()->post(config('acapadev.url') . '/oauth/token', [
    'grant_type' => 'client_credentials',
    'client_id' => config('acapadev.client_id'),
    'client_secret' => config('acapadev.client_secret'),
    'scope' => '*',
]);

Métodos Disponíveis

Método	Descrição
get(string $endpoint, array $query = [])	Pedido GET à API central
post(string $endpoint, array $data = [])	Pedido POST à API central
getUserRoles(int|string $userId)	Atalho para /users/{id}/roles, devolve um array (vazio em caso de falha)
getAccessToken(bool $forceRefresh = false)	Obtém (ou renova) o token de acesso M2M diretamente

Tratamento de Erros

Pedidos que falhem (resposta não bem-sucedida ou erro de ligação) lançam a exceção Acapadev\Sdk\Exceptions\AcapadevApiException:

use Acapadev\Sdk\Exceptions\AcapadevApiException;

try {
    $dados = Acapadev::get('/users/active');
} catch (AcapadevApiException $e) {
    // Regista o erro ou aplica um fallback seguro
    report($e);
}