SDK da Selectwin para PHP

O SDK oficial da Selectwin para PHP (selectwin/sdk): pagamentos (cartão de crédito, Pix, boleto), assinaturas, carteiras, webhooks e mais.

composer require selectwin/sdk

#Primeiros passos

use Selectwin\SelectwinClient;
use Selectwin\Exception\CardException;

$sw = new SelectwinClient(getenv('SELECTWIN_API_KEY')); // sk_test_… / sk_live_…

// Crie uma transação Pix (valores em centavos). Passe um array ou um modelo gerado:
$tx = $sw->transactions->create([
    'amount' => 9990,
    'payment' => ['method' => 'pix', 'currency' => 'BRL'],
]);

// Atalhos com id / id + corpo
$one = $sw->transactions->retrieve('tra_…');
$sw->subscriptions->pause('subs_…');

// Exceções tipadas: decida pela classe ou pelo getSelectwinCode(), nunca pela mensagem
try {
    $sw->transactions->create([/* … */]);
} catch (CardException $e) {
    echo $e->getDisplayMessage(), $e->isReversible(); // texto ao comprador + se pode repetir
}

Todo recurso tem atalhos concisos (create, retrieve, update, list, delete, além de verbos como $sw->subscriptions->pause('subs_…')). A API gerada inteira continua ao alcance pelo ->raw():

$sw->transactions->raw()->createTransaction($request);

#Paginação

O list() de primeiro nível devolve um Paginator: percorra todos os itens de todas as páginas, pegue a primeira página ou junte tudo num array:

foreach ($sw->transactions->list(['limit' => 100]) as $tx) {
    // todas as transações, de todas as páginas
}

$firstPage = $sw->transactions->list(['limit' => 20])->first(); // a página (getData(), getHasMore())
$some = $sw->customers->list()->toArray(500);                    // junta tudo, com teto opcional

#Webhooks

// $rawBody PRECISA ser exatamente os bytes recebidos (não serialize de novo)
$event = $sw->constructEvent(
    $rawBody,
    $_SERVER['HTTP_X_SELECTWIN_SIGNATURE'] ?? null,
    getenv('SELECTWIN_WEBHOOK_SECRET'), // whsec_…
);
if ($event->type === 'transaction.approved') {
    $object = $event->object;
}

O Selectwin\WebhookEvents::ALL é o catálogo oficial; o WebhookEvents::isValid($type) valida um valor. O $sw->webhooks também cuida dos endpoints, dos eventos e das entregas.

#O que o SDK acrescenta ao cliente gerado

O pacote é um núcleo gerado (da especificação OpenAPI v2.0.0, namespaces Selectwin\Api e Selectwin\Model) mais uma camada de conveniência escrita à mão:

• Cliente tipado: new SelectwinClient($key) → $sw->transactions, $sw->subscriptions, …
• Atalhos concisos por recurso, que aceitam um array ou um modelo gerado; o ->raw() dá acesso a toda a superfície gerada.
• Exceções tipadas pelo status HTTP e pelo error.code: CardException (402, getDisplayMessage()/isReversible()), ValidationException (getParams()), RateLimitException (getRetryAfter()), AuthenticationException, PermissionDeniedException, NotFoundException, ConflictException, ApiErrorException, ApiConnectionException.
• Novas tentativas automáticas (429, 5xx e falha de rede), com backoff e respeitando o Retry-After (pilha de handlers do Guzzle).
• Idempotência: toda operação de escrita leva um X-Idempotency-Key.
• Paginação: Paginator (percorrer, first(), toArray(), pages()).
• Verificação de webhook: constructEvent (HMAC-SHA256 do corpo bruto, em tempo constante).

A autenticação vai no header selectkey; o ambiente (sandbox ou produção) sai do prefixo da chave (sk_test_ / sk_live_).

#Arquitetura

lib/                       # núcleo do openapi-generator (Selectwin\Api, \Model, Configuration…), sincronizado: NÃO edite
src/
  SelectwinClient.php      # o cliente: liga a Configuration e o Guzzle a todos os recursos
  Resource/                # GERADO: wrappers dos recursos (gen_resources.php) — NÃO edite
  Exception/Exceptions.php # hierarquia de exceções tipadas + ErrorFactory
  Http/ClientFactory.php   # handlers do Guzzle (tentativas) + middleware de idempotência
  Pagination/Paginator.php
  Webhook/                 # WebhookSignature (constructEvent) + Event
  WebhookEvents.php        # GERADO: catálogo de eventos

O lib/ e o src/ dividem o namespace Selectwin\ por dois diretórios PSR-4. O que vale para todas as chamadas entra uma vez só no cliente Guzzle e na Configuration: todo endpoint herda, e endpoint novo funciona sozinho quando o núcleo é gerado de novo.

#Desenvolvimento

composer install
php scripts/sync_core.php          # traz o núcleo gerado para lib/ (do selectwin-sdks)
php scripts/gen_resources.php      # refaz o src/Resource/*
php scripts/gen_webhook_events.php # refaz o src/WebhookEvents.php
vendor/bin/phpunit --testsuite unit
SELECTWIN_SANDBOX_KEY=sk_test_... vendor/bin/phpunit --testsuite integration

#Publicação (Packagist)

O Packagist serve as versões direto das tags do git: nada é enviado. Configuração, uma vez só:

1. Entre em https://packagist.org com o GitHub e clique em Submit com o endereço do repositório (https://github.com/selectwin/sdk-php). O Packagist instala um webhook, e toda tag enviada vira uma versão nova sozinha.
2. git tag v0.1.0 && git push origin v0.1.0.

O .github/workflows/release.yml roda a suíte de testes a cada tag e (se os segredos PACKAGIST_USERNAME / PACKAGIST_API_TOKEN estiverem definidos) avisa o Packagist para atualizar na hora; sem eles, conta com o webhook.