AcapaPay · Laravel SDK

Sincronização de Planos de Faturação

Para Que Serve

O Acapadev mantém um catálogo centralizado de planos. Para que a sua app possa criar sessões de checkout com um plan_reference_code válido, os seus planos locais têm de estar registados no servidor central. O comando acapapay:sync-plans automatiza este processo.

Configurar a Model de Planos

No ficheiro config/acapapay.php, defina qual é a sua Model de planos:

'plan_model' => \App\Models\Plan::class,

Preparar a Tabela

Adicione a coluna acapapay_plan_id à tabela de planos, onde o UUID oficial devolvido pelo servidor central será guardado:

// Numa nova migration:
Schema::table('plans', function (Blueprint $table) {
    $table->string('acapapay_plan_id')->nullable();
});

Campos Esperados pela API (Padrão)

O SDK lê os seguintes campos diretamente da sua Model por padrão:

Campo da Model	Obrigatório	Descrição
reference_code	Sim	Código único do plano (ex: "PRO_MONTHLY")
name	Sim	Nome do plano para exibição
price	Sim	Preço em AOA (sem símbolos)
description	Não	Descrição do plano
currency	Não	Moeda (padrão: 'AOA')
billing_cycle	Não	'monthly' ou 'yearly' (padrão: 'monthly')
features	Não	Array de funcionalidades incluídas

Personalizar o Formato (toAcapaPayFormat)

Se as suas colunas tiverem nomes diferentes, implemente o método toAcapaPayFormat() na sua Model. O SDK dá sempre prioridade a este método, se existir:

<?php

namespace App\Models;

use Illuminate\Database\Eloquent\Model;

class Plan extends Model
{
    public function toAcapaPayFormat(): array
    {
        return [
            'reference_code' => $this->codigo_referencia,
            'name'           => $this->nome_plano,
            'description'    => $this->descricao ?? '',
            'price'          => $this->preco,
            'currency'       => 'AOA',
            'billing_cycle'  => $this->ciclo_faturacao,
            'features'       => json_decode($this->funcionalidades_json ?? '[]', true),
        ];
    }
}

Executar a Sincronização

php artisan acapapay:sync-plans

O que este comando faz internamente:

1. Obtém um Token OAuth M2M do SSO (Client Credentials).
2. Lê todos os planos com is_active = true da sua base de dados.
3. Transforma cada plano para o formato AcapaPay (usando toAcapaPayFormat() ou os campos padrão).
4. Envia a lista via PUT /v1/billing/plans para o servidor central.
5. O servidor devolve os UUIDs oficiais atribuídos a cada plano.
6. O comando atualiza a coluna acapapay_plan_id localmente com cada UUID.