Laravel Transfeera

SDK Laravel oficial para integração completa com a API Transfeera Pagamentos • Recebimentos • Pix Automático • Conta Certa • Hub de Contas • MED

Índice

• Visão Geral
• Instalação
• Configuração
• Uso Rápido
• Recursos por Domínio
  • Pagamentos
  • Recebimentos
  • Pix Automático
  • Conta Certa / Validações
  • Hub de Contas
  • MED / Infrações
• Webhooks
• Tratamento de Erros
• Autenticação & mTLS
• Multi-tenancy (Hub de Contas)
• Comandos Artisan
• Testes
• Documentação
• Contribuição
• Licença

Visão Geral

O Laravel Transfeera SDK é um pacote Laravel nativo que encapsula toda a API da Transfeera — plataforma de pagamentos e recebimentos via Pix, boletos e transferências.

Diferenciais:

• 🪶 Zero dependências externas — usa apenas illuminate/support, illuminate/http e illuminate/contracts
• 🏗️ Arquitetura por domínios — 24 Resources organizados em 7 domínios de negócio
• 🧱 DTOs tipados — readonly class para requests e responses, sem bibliotecas externas
• 🔐 mTLS automático — certificação mútua TLS em produção sem configuração manual extra
• 🪝 Webhooks completos — validação HMAC-SHA256, eventos Laravel, controllers pré-registrados
• 🧪 Testado em CI — matrix PHP 8.3/8.4 × Laravel 12/13, PHPStan level 8, Rector
• 🔄 Multi-tenancy — suporte a múltiplas contas digitais via accountId

Instalação

composer require flaviomoreir4/laravel-transfeera

O Service Provider é registrado automaticamente via auto-discovery do Laravel.

Publique a configuração (opcional):

php artisan vendor:publish --tag=transfeera-config

Configuração

Adicione ao seu .env:

# Ambiente: sandbox | production
TRANSFEERA_ENVIRONMENT=sandbox
TRANSFEERA_CLIENT_ID=seu_client_id
TRANSFEERA_CLIENT_SECRET=seu_client_secret
TRANSFEERA_USER_AGENT="MeuApp (email@dominio.com)"

# Opcional — mTLS (obrigatório em produção)
TRANSFEERA_MTLS_CERT_PATH=/caminho/cert.pem
TRANSFEERA_MTLS_KEY_PATH=/caminho/key.pem

# Opcional — timeout e retry
TRANSFEERA_TIMEOUT=30
TRANSFEERA_RETRY_MAX=3
TRANSFEERA_RETRY_DELAY=100

# Opcional — webhook secrets
TRANSFEERA_WEBHOOK_SECRET_PAYMENTS=secret-pagamentos
TRANSFEERA_WEBHOOK_SECRET_RECEIVABLES=secret-recebimentos
TRANSFEERA_WEBHOOK_SECRET_CONTA_CERTA=secret-conta-certa

Todas as chaves têm defaults seguros (sandbox, sem credenciais). O SDK valida a configuração no boot e emite warnings no log se algo estiver inconsistente.

⚠️ Produção: O mTLS é obrigatório para as APIs de Pagamentos e Conta Certa em produção. Configure TRANSFEERA_MTLS_CERT_PATH e TRANSFEERA_MTLS_KEY_PATH apontando para seus certificados .pem.

Uso Rápido

Via Facade

use Transfeera;

// Criar um lote de pagamentos
$batch = Transfeera::batches()->create([
    'name' => 'Pagamento fornecedores',
    'type' => 'manual',
]);

// Consultar saldo
$balance = Transfeera::statement()->getBalance();

// Validar conta bancária (Conta Certa)
$validation = Transfeera::contaCertaValidations()->validate([
    'bank_code' => '341',
    'agency' => '1234',
    'account' => '56789-0',
    'document' => '123.456.789-00',
]);

Via Injeção de Dependência

use FlavioMoreir4\Transfeera\TransfeeraClient;

class PaymentService
{
    public function __construct(
        private TransfeeraClient $transfeera,
    ) {}

    public function payout(array $transfers): BatchResponseDTO
    {
        return $this->transfeera->batches()->create([
            'name' => 'Lote de pagamentos',
            'transfers' => $transfers,
        ]);
    }
}

Recursos por Domínio

Pagamentos

// Criar lote com transferências
$batch = Transfeera::batches()->create([
    'name' => 'Fornecedores Julho',
    'type' => 'manual',
]);

// Adicionar transferência ao lote
$transfer = Transfeera::transfers($batch['id'])->create([
    'amount' => 150000,                     // R$ 1.500,00 (em centavos)
    'pix_key' => 'cliente@email.com',
    'pix_key_type' => 'email',
    'description' => 'Pagamento nota 123',
]);

// Consultar saldo
$balance = Transfeera::statement()->getBalance();
// ['balance' => 500000, 'blocked' => 100000, 'available' => 400000]

Recebimentos

// Criar cobrança Pix com vencimento
$charge = Transfeera::charges()->create([
    'payer_document' => '123.456.789-00',
    'payer_name' => 'João Silva',
    'amount' => 50000,                // R$ 500,00 (centavos)
    'due_date' => '2025-08-15',
    'type' => 'pix',
]);

// Baixar PDF do boleto
$pdf = Transfeera::charges()->downloadPdfByChargeId($charge->id);

// Criar chave Pix
$key = Transfeera::pixKeys()->create([
    'type' => 'email',
    'value' => 'cobranca@exemplo.com',
]);

Pix Automático

// Criar autorização Pix Automático
$auth = Transfeera::pixAutomaticoAuthorizations()->create([
    'payer_document' => '123.456.789-00',
    'payer_name' => 'João Silva',
    'payer_bank' => '341',
    'limit_amount' => 100000,         // R$ 1.000,00 (centavos)
    'limit_type' => 'monthly',
]);

// Criar instrução de pagamento
$intent = Transfeera::pixAutomaticoPaymentIntents()->create([
    'authorization_id' => $auth->id,
    'amount' => 50000,
    'description' => 'Assinatura mensal',
]);

Conta Certa / Validações

// Validar conta bancária
$result = Transfeera::contaCertaValidations()->validate([
    'bank_code' => '341',
    'agency' => '1234',
    'account' => '56789-0',
    'document' => '123.456.789-00',
    'account_type' => 'corrente',
]);

Hub de Contas

// Criar conta digital
$account = Transfeera::accounts()->create([
    'name' => 'Conta Cliente A',
    'document' => '12.345.678/0001-90',
    'type' => 'company',
]);

MED / Infrações

// Analisar infração individual
$analysis = Transfeera::infractions()->analyze([
    'end_to_end_id' => 'E123456789012024...',
    'infraction_type' => 'fraud',
]);

// Devolução em lote
$result = Transfeera::infractions()->returnBatch([
    'infractions' => [...],
]);

Webhooks

O SDK expõe 3 endpoints para receber notificações da Transfeera:

Validação de assinatura: HMAC-SHA256, automática. Configure os secrets no .env.

// Ouvir eventos no EventServiceProvider
use FlavioMoreir4\Transfeera\Events\TransfeeraWebhookReceived;

protected $listen = [
    TransfeeraWebhookReceived::class => [
        MinhaListener::class,
    ],
];

Publicar rotas (opcional):

php artisan vendor:publish --tag=transfeera-routes

📖 Consulte docs/webhooks.md para detalhes completos.

Tratamento de Erros

Todas as exceptions estendem TransfeeraException:

use FlavioMoreir4\Transfeera\Exceptions\{
    TransfeeraException,
    TransfeeraAuthenticationException,  // 401
    TransfeeraValidationException,      // 422 — use $e->getErrors()
    TransfeeraRateLimitException,       // 429 — use $e->getRetryAfter()
    PaymentException,                   // Erros em Pagamentos
    ReceivableException,                // Erros em Recebimentos
    PixAutomaticoException,             // Erros em Pix Automático
    ContaCertaException,                // Erros em Conta Certa
    AccountException,                   // Erros no Hub de Contas
    InfractionException,                // Erros em MED/Infrações
};

try {
    $batch = Transfeera::batches()->create([...]);
} catch (TransfeeraValidationException $e) {
    // Campos inválidos
    foreach ($e->getErrors() as $field => $messages) { ... }
} catch (TransfeeraRateLimitException $e) {
    // Rate limit — backoff
    $retryAfter = $e->getRetryAfter();
    $limit = $e->getLimit();
    $remaining = $e->getRemaining();
} catch (PaymentException $e) {
    // Erro específico de pagamentos
}

📖 Consulte docs/exceptions.md para a hierarquia completa.

Autenticação & mTLS

O SDK gerencia o ciclo de vida do token OAuth2 client_credentials automaticamente:

• Cache — token armazenado no cache do Laravel (store configurável)
• Renovação antecipada — renova 60s antes do expires_in real
• Concorrência — lock de cache evita múltiplas renovações simultâneas
• Multi-tenancy — tokens separados por accountId

// Forçar renovação manual
Transfeera::getConfig(); // ou via TokenManager

mTLS em produção é aplicado automaticamente nas APIs de Pagamentos e Conta Certa. Configure:

TRANSFEERA_MTLS_CERT_PATH=/etc/ssl/transfeera/cert.pem
TRANSFEERA_MTLS_KEY_PATH=/etc/ssl/transfeera/key.pem

Multi-tenancy (Hub de Contas)

Todos os Resources aceitam $accountId opcional:

// Operar como conta específica
$batches = Transfeera::batches('acc_123')->list();

// Criar recurso em nome de outra conta
$batch = Transfeera::batches('acc_456')->create([
    'name' => 'Lote Conta B',
]);

O TokenManager adiciona scope=account_id:{accountId} ao token, garantindo escopo correto.

Comandos Artisan

php artisan transfeera:check
# 🔍 Verificando Transfeera SDK...
# 📋 Ambiente: sandbox
# ✅ Ambiente válido.
# ✅ Credenciais configuradas.
# ✅ Endpoint de autenticação acessível.

Testes

composer test              # Pest (283 testes, 482 asserções)
composer test-coverage     # Com cobertura (PHP 8.3+)
composer phpstan           # PHPStan level 8
composer rector            # Rector dry-run
composer format            # Pint PSR-12

O CI roda em matrix PHP 8.3/8.4 × Laravel 12/13.

Documentação

Links oficiais da Transfeera:

• Documentação da API
• Índice completo (llms.txt)

Contribuição

Veja CONTRIBUTING.md para detalhes.

composer test && composer phpstan && composer rector

Licença

MIT © Flávio Moreira. Veja o arquivo LICENSE para detalhes.