Download the PHP package danielbbarcelos/laravel-bancos without Composer

laravel-bancos

Integração com bancos brasileiros (Pix, e futuramente boleto, pagamentos e conciliação) sob um contrato único, com um driver por banco. Você programa contra a interface canônica; cada driver faz o de-para para a API específica do banco.

Requisitos

• PHP ^8.2
• Laravel ^11.0 || ^12.0

Instalação

Configure as credenciais em .env — veja .env.example (na raiz do package) com todas as variáveis comentadas (Pix + boleto, Sicredi + C6) e config/bancos.php. Bancos de Pix exigem certificado mTLS — informe *_CERT_PATH e *_KEY_PATH.

Sicredi: como ligar de verdade

Para a integração funcionar contra a API real do Sicredi você precisa de três coisas:

1. Credenciais OAuth2 — client_id e client_secret gerados no app do Portal do Desenvolvedor Sicredi → SICREDI_CLIENT_ID / SICREDI_CLIENT_SECRET.
2. Certificado mTLS (obrigatório em toda chamada) — baixe no portal o .cer (PEM) e a chave .key SEM senha. Aponte em SICREDI_CERT_PATH / SICREDI_KEY_PATH. Sem o certificado, a API responde 403.
3. Scopes — são obrigatórios (sem eles o Sicredi retorna 400 "Escopo vazio"). O driver já envia um default para Pix (cob.* pix.* webhook.*); ajuste em SICREDI_SCOPES se precisar de cobv.*, cobr.* etc.

Ambientes: produção é https://api-pix.sicredi.com.br (default). A URL de homologação não é pública — solicite ao Sicredi ([email protected]) e defina em SICREDI_BASE_URL.

Diagnóstico

Antes de emitir cobranças, valide a conexão de ponta a ponta:

O comando traduz os erros mais comuns (ex.: 403 → certificado mTLS; 401 → credenciais). Em código, o mesmo está disponível via Bancos::driver('sicredi')->verificarConexao().

Uso em SaaS / multi-tenant

Em vez de credenciais fixas no .env, cada empresa/tenant pode ter as suas. A aplicação passa tudo em runtime com Bancos::build() — nada sensível precisa ir para o .env:

• Defaults compartilhados (base_url, scopes, timeout) vêm do bloco do banco no config/bancos.php; o tenant sobrepõe só o que é dele.
• Certificado: aceita o caminho de um arquivo ou o conteúdo PEM em memória — neste caso o package grava um arquivo temporário 0600 e o remove sozinho. A app guarda o certificado de forma segura (criptografado) e só entrega o conteúdo.
• Isolamento de token: o cache de token é separado por credencial automaticamente (hash de client_id+base_url); use cache_key para forçar um escopo por tenant. Dois clientes do mesmo banco nunca compartilham token.

[!note] Bancos::driver('sicredi') (modo .env) e Bancos::build('sicredi', [...]) (runtime) coexistem. Single-tenant usa o primeiro; SaaS usa o segundo.

Cobrança com vencimento (cobv) — "boleto-Pix"

Cobrança com data de vencimento, multa, juros e desconto. O txid é sempre seu (PUT):

[!note] cobv exige os scopes cobv.read cobv.write no token — já incluídos no default do driver Sicredi. As modalidades de multa/juros/desconto seguem o padrão BACEN.

Gerenciar cobrança e conciliar

Boleto registrado

📖 Guia de integração completo (multi-tenant com credenciais em runtime, emissão, PDF, alteração, listagem, webhook, tratamento de erros e exemplo Service+Controller): docs/README.md.

A API de boleto do Sicredi é um produto separado do Pix (outra base URL, OAuth2 grant_type=password + x-api-key, sem mTLS). Configure o bloco boleto em config/bancos.php e use:

[!note] Cheque o suporte antes: Bancos::banco()->suporta(Recurso::Boleto).

Webhook de boleto (liquidação/estorno)

Diferente do webhook Pix, o boleto usa um contrato de webhook:

Webhook Pix (confirmação de recebimento)

Para saber que uma cobrança foi paga, registre um webhook e processe a notificação.

1. Registrar o webhook no PSP

2. Receber a notificação

O package não registra rota — você cria o endpoint e aplica a sua segurança. O Sicredi notifica via mTLS (valide o certificado do cliente na borda: servidor web / proxy), e é recomendável restringir por IP. No controller, delegue o parsing ao package:

processarNotificacao() dispara o evento Events\PixRecebido para cada Pix recebido e retorna list<Recebimento>.

3. Reagir ao pagamento

[!warning] O endpoint de webhook é público. Proteja-o (mTLS do PSP na borda + allowlist de IP). O padrão BACEN não usa assinatura HMAC — a autenticidade vem do mTLS.

Arquitetura

Como Sicredi, C6 e a maioria dos PSPs brasileiros seguem o padrão Pix do BACEN, o de-para vive uma vez só em Drivers\Bacen. Um novo banco geralmente é só um Connector (como ele emite o token) + os prefixos de rota.

Trocar de banco não muda o código de quem chama.

Registrar um driver de terceiros

Suporte atual

* C6: implementado sobre o núcleo BACEN. O endpoint de token, scopes e versão das rotas estão sob a doc oficial (portal exige cadastro) — confirme e ajuste via config (token_url, token_via_basic, scopes, rota_cob, rota_pix) antes de produção.

Antes de chamar um recurso que pode não existir: Bancos::banco()->suporta(Recurso::Boleto).

Testes

Os testes usam Http::fake() — não tocam nenhuma API real.

Segurança

• mTLS + TLS verify: a verificação do certificado do servidor é sempre habilitada (verify => true); o package nunca a desabilita.
• HTTPS obrigatório: base_url e a webhookUrl precisam ser https (anti-MITM). Um http:// lança BancoException. Só dev local pode liberar via permitir_http => true.
• Credenciais mascaradas: connectors e drivers usam #[\SensitiveParameter] (redige em stack traces) e __debugInfo() (mascara client_secret/password/x_api_key/certificado em dd()/var_dump()/dump()).

  ⚠️ var_export(), print_r() e serialize() não respeitam __debugInfo() — não serialize um connector/driver numa queued job; passe os dados, não o objeto.

• Token cifrado no cache: o access token é gravado com Crypt::encrypt (usa a APP_KEY), então vazar o store de cache não basta. Ainda assim, use um store seguro (ex.: Redis com AUTH/TLS) em produção.
• Webhook: a autenticidade vem do mTLS do PSP na borda + allowlist de IP (o BACEN não usa HMAC). O processarNotificacao() limita o nº de Pix por payload (webhook_max_itens, anti-DoS) — implemente rate-limit no endpoint.
• Erros: BancoApiException->corpo traz a resposta crua do PSP (pode conter PII). Não logue a exceção crua; o getMessage() expõe só detail/title.
• Certificado em memória: ao passar o PEM por conteúdo, o arquivo temporário é 0600 e removido no __destruct e no shutdown (mesmo após fatal).

Robustez

• Retry com backoff: chamadas re-tentam automaticamente em falhas transitórias (timeout/conexão e HTTP 5xx); 4xx não é re-tentado (vira BancoApiException na hora). Configurável por banco: tentativas (default 3) e retry_intervalo_ms (default 200). Use txid nos PUT para idempotência.
• Retry em 401: se o PSP responder 401 (token expirado no servidor antes do TTL local), o token cacheado é descartado e a chamada é refeita uma vez automaticamente.
• Validação de txid: ao criar cobrança com txid (imediata ou cobv), o formato BACEN (26–35 alfanuméricos) é validado antes de chamar a API — falha cedo com mensagem clara, sem gastar um round-trip para receber um 400.