README

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
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

Resource	Métodos	Response DTO
`batches()`	`create()`, `list()`, `get()`, `update()`, `delete()`	`BatchResponseDTO`
`transfers()`	`create()`, `get()`, `update()`, `delete()`	`TransferResponseDTO`
`billets()`	`create()`, `get()`, `list()`, `update()`, `delete()`	`BilletResponseDTO`
`banks()`	`list()`	`BankResponseDTO[]`
`statement()`	`getBalance()`, `getTransactions()`	`StatementResponseDTO` / `array`
`recurrences()`	`create()`, `get()`, `list()`, `update()`, `delete()`	`RecurrenceResponseDTO`
`pix()`	`consultKey()`, `parseEMV()`	`PixResponseDTO` / `array`

// 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

Resource	Métodos	Response DTO
`pixKeys()`	`create()`, `list()`, `get()`, `update()`, `delete()`	`PixKeyResponseDTO[]`
`pixQrCodes()`	`create()`, `list()`, `get()`	`PixQrCodeResponseDTO`
`pixCashIn()`	`list()`, `get()`	`PixCashInResponseDTO[]`
`charges()`	`create()`, `list()`, `get()`, `update()`, `delete()`, `downloadPdfByChargeId()`	`ChargeResponseDTO`
`paymentLinks()`	`create()`, `list()`, `get()`, `delete()`	`PaymentLinkResponseDTO`

// 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

Resource	Métodos	Response DTO
`pixAutomaticoAuthorizations()`	`create()`, `list()`, `get()`, `revoke()`	`AuthorizationResponseDTO`
`pixAutomaticoPaymentIntents()`	`create()`, `list()`, `get()`, `cancel()`	`PaymentIntentResponseDTO`

// 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

Resource	Métodos	Response DTO
`contaCertaValidations()`	`validate()`, `get()`, `list()`, `listBanks()`	`ValidationResponseDTO` / `array`
`contaCertaBanks()`	`list()`	`BankResponseDTO[]`

// 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

Resource	Métodos	Response DTO
`accounts()`	`create()`, `list()`, `get()`, `update()`, `delete()`	`AccountResponseDTO`

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

MED / Infrações

Resource	Métodos	Response DTO
`infractions()`	`analyze()`, `analyzeBatch()`, `list()`, `get()`, `return()`, `returnBatch()`	`InfractionResponseDTO` / `array`

// 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:

Rota	Domínio	Controller
`POST /webhooks/transfeera/payments`	Pagamentos	`WebhookController@payments`
`POST /webhooks/transfeera/receivables`	Recebimentos	`WebhookController@receivables`
`POST /webhooks/transfeera/conta-certa`	Conta Certa	`WebhookController@contaCerta`

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

Comando	Descrição
`php artisan transfeera:install`	Publica configuração e exibe instruções
`php artisan transfeera:check`	Valida credenciais, conectividade e mTLS
`php artisan transfeera:check --silent`	Retorna apenas o código de saída (CI/CD)
`php artisan transfeera:debug`	Diagnóstico completo do SDK
`php artisan transfeera:cache-warm`	Pré-aquece o cache do token OAuth

php artisan transfeera:check
# 🔍 Verificando conectividade e credenciais da API Transfeera...
# 🌐 Testando autenticação: https://login-api-sandbox.transfeera.com/authorization
# OK: Credenciais validadas

php artisan transfeera:check --silent && echo "Transfeera OK"

Mais detalhes em docs/comandos-artisan.md.

Testes

composer test              # Pest (300 testes, 547 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

Documento	Conteúdo
Pagamentos	Lotes, transferências, boletos, saldo, recorrências
Recebimentos	Chaves Pix, QR Codes, Cash-in, cobranças, links
Pix Automático	Autorizações, Payment Intents, fluxo completo
Conta Certa	Validações, bancos suportados
Hub de Contas	Contas digitais, onboarding, tenancy
MED / Infrações	Infrações, análise individual/lote, devolução
Webhooks	Rotas, secrets, validação HMAC, listeners
Exceptions	Hierarquia completa, catch, métodos úteis
Middlewares	Config, logging, métricas, Prometheus
Erros	Códigos HTTP, handlers, retry
Fila	Jobs base, backoff inteligente, Horizon/Pulse
Comandos Artisan	Instalação, check, debug, cache-warm
Primeiro Pagamento	Passo a passo inicial
Primeiro Recebimento	Passo a passo inicial
Changelog	Histórico de versões (Keep a Changelog)
Roadmap	Planejamento de versões futuras

Links oficiais da Transfeera:

Contribuição

Veja CONTRIBUTING.md para detalhes.

composer test && composer phpstan && composer rector

flaviomoreir4 / laravel-transfeera

Maintainers

Package info

Statistics

Security