Repository navigation
v2.2.0 — Efí Pix com mTLS e assinaturas completas do Asaas
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, comskipMtlsChecking()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 serverlessfromBase64() 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()ereactivate()getPayments(): as cobranças já geradas pela assinaturapaymentBook(): o carnê, como os bytes do PDFupdateCreditCard(): troca o cartão sem cobrar- Nota fiscal emitida automaticamente a cada cobrança:
create/get/update/destroyInvoiceSettings()egetInvoices()
🐛 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:
cyclepassa 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:
- O Guzzle mínimo sobe de
^7.0para^7.3, a primeira versão que sabe usar certificado.p12. A 7.3 é de março de 2021. - Criar assinatura no Asaas sem
cycleagora lançaValidationExceptionantes da chamada, em vez deApiExceptiondo Asaas. A requisição já falhava; só falha mais cedo e com mensagem melhor. - Quem implementa a
SubscriptionInterfacedo 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