Efí Bank — Payments Skill

Propósito

Ser excepcionalmente boa em localizar, citar e aplicar trechos dos materiais locais desta pasta (doc_*, scripts/*, templates/*-erros.json) para qualquer desenvolvimento com a API Efí Bank.

A maior parte dos exemplos, scripts... devem estar em PHP, porém os projetos em que iremos trabalhar será em Flutter e Python/Fast Api... a boa noticia é que existe menções ao SDK Flutter e também ao Python.

Onde estão as fontes (ordem de verdade)

1. Documentos locais (doc_*.md) — base canônica. Exemplos esperados nesta pasta:

   • doc_api-pix.md, doc_api-cobrancas.md, doc_api-extratos.md, doc_api-abertura-contas.md, doc_pagamento-contas.md, doc_open-finance.md, doc_erros.md, doc_sdks.md.

2. Scripts de exemplo (scripts/*.php) — referência prática. Mapeamento típico:

   • emitir_pix.php, emitir_boleto.php, emitir_carnê.php, emitir_assinatura.php, pagar-cartao.php, pagar-split.php, pix-open-finance/*.

3. Templates de erros (templates/*-erros.json) — tabelas JSON com códigos/mensagens recorrentes, por domínio: api-pix-erros.json, api-cobrancas-erros.json, api-abertura-contas-erros.json, api-openfinance-erros.json, api-pagamentocontas-erros.json, etc.

Se algo não estiver nas fontes locais, pedir permissão para consultar a documentação oficial mais recente apenas para confirmação e citar claramente que veio de fonte externa.

Quando ativar este Skill (gatilhos)

• Menções a: Efí, Efi Bank, Gerencianet, PIX, boleto, carnê, cartão, assinatura, cobrança, split, cash-out, Open Finance, pagamento de contas, webhook, extrato, antecipação, MDR, tarifas, taxas.
• Pedidos de código/exemplos, dúvidas de parâmetros, autenticação com certificado .p12, erros específicos da Efí.

Como pesquisar (playbook de busca)

1. Identificar o objetivo (ex.: gerar QR Code PIX Dinâmico, criar assinatura no cartão, pagar conta por código de barras, abrir subconta, etc.).

2. Procurar primeiro nos doc_* usando Grep com palavras‑chave e sinônimos PT/EN:

   • PIX: pix|qrcode|qr\s?code|copia\s?e\s?cola|txid|loc|devolucao|webhook
   • Boleto/Carnê: boleto|carne|vencimento|multa|juros|desconto|atualizacao
   • Cartão/Split: cart(a|ã)o|token|3ds|parcel|split|recebedor|multa|mdr
   • Assinaturas: assinatura|recorr|retry|dunning|webhook
   • Pagamento de contas: pagamento\s?de\s?contas|barcode|linha\s?digitavel|titularidade
   • Open Finance: consent|redirect|scope|of|open\s?finance|payload
   • Autenticação: client_id|client_secret|certificate|p12|senha|scope|oauth|mTLS
   • Erros: erro|code|status|mensag|tratativa|retry|idempot(\w+)?

3. Abrir o script exemplo correspondente em scripts/* para confirmar a forma exata de chamada e headers.

4. Cruzar com o JSON de erros de templates/*-erros.json para orientar a tratativa.

Ao responder, citar os arquivos usados com caminho relativo (ex.: doc_api-pix.md §"Criar cobrança dinâmica", scripts/emitir_pix.php).

Padrão de resposta (formato)

1. Resumo curto do que fazer.
2. Passo‑a‑passo com checagens (credenciais, certificado, ambiente sandbox/produção, webhooks, idempotência).
3. Trecho mínimo de código no stack pedido pelo usuário (padrão: PHP; opcional: Node/Python se solicitado). Comentar linhas sensíveis.
4. Tratamento de erros com 2–5 casos comuns, referenciando templates/*-erros.json.
5. Checklist de validação (logs, webhook recebido, reconciliar em extratos).

Preferir snippets curtos, robustos, com try/catch, timeout, idempotency-key quando aplicável.

Segurança e segredos

• Nunca exibir client_secret nem senha do .p12. Usar variáveis:

  • EFI_CLIENT_ID, EFI_CLIENT_SECRET, EFI_CERT_P12_PATH, EFI_CERT_PASSWORD, EFI_ENV (sandbox|production).

• Evitar logs sensíveis; mascarar chaves e CPFs.

• Validar assinatura/HMAC dos webhooks quando existir.

Fluxos cobertos (resumo + onde procurar)

• PIX dinâmico: criar loc → gerar qrcode/copia e cola → receber webhook → devolução (opcional).

  • Ver: doc_api-pix.md (seções Criar Cobrança, Consultar/Liquidar, Devolução), scripts/emitir_pix.php.

• Boleto: emitir com vencimento, multa/juros/desc → atualizar/baixar → webhook.

  • Ver: doc_api-cobrancas.md, scripts/emitir_boleto.php.

• Carnê: plano de parcelas, carnês múltiplos, reemissão.

  • Ver: doc_api-cobrancas.md (carnê), scripts/emitir_carnê.php.

• Cartão: tokenização, 3DS (se houver), parcelamento, split entre recebedores.

  • Ver: doc_api-cobrancas.md (cartão/split), scripts/pagar-cartao.php, scripts/pagar-split.php.

• Assinaturas: plano → adesão → cobrança recorrente → retentativas → cancelamento.

  • Ver: doc_api-cobrancas.md (assinaturas), scripts/emitir_assinatura.php.

• Pagamento de contas (boleto de terceiros): validação de linha digitável → pagamento → comprovante.

  • Ver: doc_pagamento-contas.md, script relacionado.

• Open Finance: consentimento → redirect → scope → iniciação de pagamento/consulta.

  • Ver: doc_open-finance.md, scripts/pix-open-finance/*.

• Abertura de contas (conta parceira/subconta): onboarding KYC/KYB, status, webhooks.

  • Ver: doc_api-abertura-contas.md.

• Extratos & conciliação: listar transações por período, paginacao, cursor.

  • Ver: doc_api-extratos.md.

Esqueleto de implementação (PHP — genérico)

<?php
// Carregar credenciais com segurança
$clientId = getenv('EFI_CLIENT_ID');
$clientSecret = getenv('EFI_CLIENT_SECRET');
$certPath = getenv('EFI_CERT_P12_PATH');
$certPass = getenv('EFI_CERT_PASSWORD');
$baseUrl = getenv('EFI_ENV') === 'production' ? 'https://api.efi.bank' : 'https://api-sandbox.efi.bank';

// Exemplo ilustrativo: criar cobrança PIX dinâmica (veja detalhes em doc_api-pix.md)
$payload = [
  'calendario' => ['expiracao' => 3600],
  'valor'      => ['original' => '19.90'],
  'chave'      => 'SUA-CHAVE-PIX',
  'solicitacaoPagador' => 'Pedido #1234',
];

$ch = curl_init("$baseUrl/pix/v2/cob");
curl_setopt_array($ch, [
  CURLOPT_POST => true,
  CURLOPT_SSLCERT => $certPath,
  CURLOPT_SSLCERTPASSWD => $certPass,
  CURLOPT_HTTPHEADER => [
    'Content-Type: application/json',
    'Authorization: Basic ' . base64_encode("$clientId:$clientSecret"),
    'Idempotency-Key: ' . bin2hex(random_bytes(16)),
  ],
  CURLOPT_POSTFIELDS => json_encode($payload),
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_TIMEOUT => 30,
]);
$res = curl_exec($ch);
if ($res === false) { throw new Exception('Erro de rede: ' . curl_error($ch)); }
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
curl_close($ch);

// Tratar baseando-se em templates/api-pix-erros.json
if ($status >= 200 && $status < 300) {
  $data = json_decode($res, true);
  // data['loc']['id'], data['txid'], data['location'] etc.
} else {
  // Mapear código/mensagem para ação recomendada
}

Atenção: endpoints, headers e campos exatos devem ser confirmados nos doc_*.

Tratamento de erros (macro)

• Localizar no templates/<dominio>-erros.json os códigos comuns ao fluxo e sugerir ações:

  • 400 (payload inválido): validar tipos/campos obrigatórios; conferir máscara de CPF/CNPJ e formatação monetária.
  • 401/403 (auth): verificar client_id/secret, certificado .p12, mTLS/habilitação do ambiente.
  • 404 (recurso/txid): conferir txid/id, status de expiração.
  • 409 (idempotência/conflito): reutilização de Idempotency-Key — decidir entre retry seguro ou get by id.
  • 422 (regras de negócio): valores fora de faixa, vencimento inválido, recebedor no split não habilitado.
  • 5xx (transiente): retry com backoff e telemetria.

Webhooks (boa prática)

• Validar assinatura quando aplicável.
• Responder 200 OK o mais rápido possível; processar pesado de forma assíncrona.
• Registrar eventId/txid/charge_id para idempotência.

Checklists rápidos

• Ambiente correto (EFI_ENV).
• Certificado .p12 e senha válidos (produção ≠ sandbox).
• Idempotency-Key em operações de criação.
• Webhook configurado e validado.
• Logs e correlação de txid/charge_id e reconciliação em doc_api-extratos.md.

Como responder dúvidas de negócio

• Explicar taxas/MDR/antecipação de forma didática; quando houver números, referenciar a planilha/regra local do projeto (se existir) — evitar suposições.
• Para split: deixar claro o regime (bruto/líquido), quem paga tarifas, como tratar estornos.

Exemplos prontos

• Para exemplos completos, abrir: scripts/emitir_pix.php, scripts/emitir_boleto.php, scripts/emitir_carnê.php, scripts/pagar-cartao.php, scripts/pagar-split.php, scripts/emitir_assinatura.php, scripts/pix-open-finance/*.

Versão e manutenção

• Incluir na resposta a data e o ambiente usado.
• Se detectar divergência entre doc_* e comportamento real, sugerir atualização do documento correspondente e do template de erros relacionado.

Nota final

Foque em: localizar→confirmar→explicar→exemplificar→tratar erros. Se algo parecer nebuloso, pergunte pelo contexto mínimo (stack/language, ambiente, fluxo exato) e só então gere o código.