AcapaPay · CodeIgniter 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 (ver Checkout), os seus planos locais têm de estar registados no servidor central. O comando spark acapapay:sync-plans automatiza este processo.

O Contrato PlanoProviderInterface

namespace AcapaPay\CodeIgniter\Contracts;

interface PlanoProviderInterface
{
    /**
     * Devolve os planos ativos a sincronizar com o AcapaPay.
     * Cada item deve conter pelo menos: reference_code, name, price.
     * Campos opcionais: description, currency, billing_cycle, features.
     *
     * @return list
     */
    public function listarPlanos(): array;

    /**
     * Chamado após uma sincronização bem-sucedida, para que o host
     * persista o id atribuído pelo AcapaPay a cada plano localmente.
     */
    public function marcarSincronizado(string $referenceCode, string $acapapayPlanId): void;
}

Passo 1 — Implementar o Contrato

<?php

namespace App\Services;

use AcapaPay\CodeIgniter\Contracts\PlanoProviderInterface;

class AcapaPayPlanoProvider implements PlanoProviderInterface
{
    public function listarPlanos(): array
    {
        $model = new \App\Models\ProdutoModel(); // ou o seu model de preços/planos

        return $model->where('activo', true)->findAll();
        // cada item precisa de: reference_code, name, price
        // opcional: description, currency, billing_cycle, features
    }

    public function marcarSincronizado(string $referenceCode, string $acapapayPlanId): void
    {
        (new \App\Models\ProdutoModel())
            ->where('reference_code', $referenceCode)
            ->set('acapapay_plan_id', $acapapayPlanId)
            ->update();
    }
}

Passo 2 — Registar o Provider

Aponte acapapay.planoProvider para a classe concreta em app/Config/AcapaPay.php da sua aplicação:

<?php

namespace Config;

use AcapaPay\CodeIgniter\Config\AcapaPay as BaseAcapaPay;

class AcapaPay extends BaseAcapaPay
{
    public ?string $planoProvider = \App\Services\AcapaPayPlanoProvider::class;
}

Passo 3 — Executar a Sincronização

php spark acapapay:sync-plans

O que o comando acapapay:sync-plans faz internamente:

1. Lê acapapay.planoProvider e valida que a classe existe e implementa PlanoProviderInterface.
2. Chama listarPlanos() na sua implementação.
3. Se não houver planos, avisa e termina sem chamar a API.
4. Autentica via OAuth2 (token cacheado) e envia o lote via PUT /v1/billing/plans, através do método sincronizarPlanos() da classe AcapaPay.
5. Para cada plano devolvido na resposta (plans, com reference_code e id), chama marcarSincronizado($referenceCode, $id) na sua implementação.