Skip to content

v2.2.0 — Efí Pix com mTLS e assinaturas completas do Asaas

Choose a tag to compare

@mariolucasdev mariolucasdev released this 21 Sep 15:41
459fca8

Duas lacunas fechadas. O Efí, que era o gateway mais fraco da biblioteca com 1 de 5 capacidades, passa a ter 4 de 5 com a API Pix. As assinaturas do Asaas, que só sabiam criar, passam a cobrir os 14 endpoints da API.

Para quem chama a biblioteca, tudo é aditivo. Veja a nota de compatibilidade abaixo.

🔐 Efí: API Pix com mTLS

O Efí tem duas APIs com as mesmas credenciais. A de Cobranças (boleto) já estava integrada, e a v2.2.0 integra a API Pix:

Gateway Clientes Cobranças Assinaturas Webhooks Chaves Pix
Efí v2.1.0 — ✅ — — —
Efí v2.2.0 — ✅ ✅ ✅ ✅

Toda requisição da API Pix é por mTLS, inclusive a do token. Basta passar o certificado da aplicação:

$efi = new EfiGateway($clientId, $clientSecret, certificate: '/caminho/certificado.p12');

$cobranca = $efi->pixCharge()
    ->setAmount(Money::reais('123,45'))
    ->setKey('sua-chave-pix')
    ->setCustomer(new Customer('Mário Lucas', '12345678909'))
    ->create();

$efi->pixCharge()->qrCode($cobranca['loc']['id'])['qrcode'];   // copia e cola
  • Cobrança Pix (pixCharge()): imediata ou com vencimento, QR Code e devolução
  • Chaves Pix (pix()): chaves aleatórias (EVP)
  • Webhooks (webhook()): um por chave Pix, com skipMtlsChecking() para servidores que não validam o certificado do Efí
  • Pix Automático (subscription()): o pagador autoriza uma vez no app do banco, e cada ciclo é debitado sem nova aprovação. Cobre a recorrência, o QR Code de autorização e a cobrança de cada ciclo

Na API Pix, o valor só entra como Money. Ela quer reais ("123.45"), enquanto a API de Cobranças do mesmo gateway quer centavos. Aceitar número cru ali recriaria exatamente o erro que o Money existe para evitar.

🪪 Certificate: mTLS genérico

O padrão do BACEN para API Pix exige mTLS, e Inter, BB, Itaú, Sicoob e Sicredi seguem o mesmo esquema. Por isso o certificado é PHPay\Http\Certificate, e não algo exclusivo do Efí:

new Certificate('/caminho/certificado.p12', 'senha');
Certificate::fromBase64(getenv('EFI_CERTIFICATE_BASE64'));   // para container e serverless

fromBase64() grava o certificado num temporário com permissão 0600, apagado ao fim do processo. A senha nunca aparece num var_dump().

🔁 Asaas: assinaturas completas

Antes só existia create(). Agora o recurso cobre toda a API de assinaturas do Asaas:

$assinaturas = $phpay->subscription();

$assinatura = $assinaturas
    ->setCustomer($cliente)
    ->setAmount(Money::reais('49,90'))
    ->setCycle(SubscriptionCycleEnum::MONTHLY)
    ->setSubscription(['billingType' => 'BOLETO', 'nextDueDate' => '2026-10-10'])
    ->create();

$id = $assinatura['id'];

$assinaturas->deactivate($id);                 // pausa sem apagar cobranças
$assinaturas->reactivate($id, '2026-11-10');   // o Asaas exige novo vencimento
file_put_contents('carne.pdf', $assinaturas->paymentBook($id));
  • getAll(), find(), update(), destroy(), deactivate() e reactivate()
  • getPayments(): as cobranças já geradas pela assinatura
  • paymentBook(): o carnê, como os bytes do PDF
  • updateCreditCard(): troca o cartão sem cobrar
  • Nota fiscal emitida automaticamente a cada cobrança: create/get/update/destroyInvoiceSettings() e getInvoices()

🐛 Correções

  • Efí: o token da API de Cobranças ficava em cache para sempre. Um gateway que fica vivo num worker de fila passava a tomar 401 quando o Efí expirava o token. Agora o token é renovado sozinho, e o da API Pix também.
  • Asaas: cycle passa a ser obrigatório na criação de assinatura, como na especificação do Asaas. Antes o payload sem ele passava pela validação e só falhava no gateway.

⚠️ Nota de compatibilidade

Para quem chama a biblioteca, nada muda. Os parâmetros novos do EfiGateway (certificate e pixClient) são opcionais e ficam no fim do construtor, e create([...]) da assinatura do Asaas funciona como antes.

Três pontos para conferir:

  1. O Guzzle mínimo sobe de ^7.0 para ^7.3, a primeira versão que sabe usar certificado .p12. A 7.3 é de março de 2021.
  2. Criar assinatura no Asaas sem cycle agora lança ValidationException antes da chamada, em vez de ApiException do Asaas. A requisição já falhava; só falha mais cedo e com mensagem melhor.
  3. Quem implementa a SubscriptionInterface do Asaas fora da biblioteca precisa acompanhar as assinaturas novas: create(array $subscription = []) ganhou default, e a interface ganhou métodos. Quem só usa o recurso não é afetado.

🧪 Qualidade

275 → 354 testes (968 asserções), todos com HTTP simulado e sem rede.

  • Os testes do Efí conferem que o client montado apresenta o certificado e o token em toda requisição, no host certo de cada ambiente.
  • As rotas foram conferidas no SDK oficial do Efí, no padrão Pix do BACEN e na especificação oficial do Asaas.

Ainda não foram exercitadas contra os sandboxes reais, o que exige o certificado de homologação do Efí e o token de sandbox do Asaas. Os scripts examples/efi/pix.php e examples/asaas/subscriptions.php estão prontos para isso.

Full Changelog: v2.1.0...v2.2.0