Plano de Execução — Gateway Bancário Real (Fiducia)

Plano de execução completo para levar App\Models\Banks\Fiducia (o adapter real de BankInterface, ao lado do mock Teste) do estado atual — implementado, não validado contra o provedor real — até uma conta de produção operando com dinheiro real. Referência técnica do que já existe: Gateway Bancário Real — Sandbox e Produção. Este documento é o plano; aquele é o contrato/mapeamento.

Regra deste plano: nenhuma fase avança para a próxima sem o critério de saída (✅) da fase anterior cumprido. Nenhum código novo é escrito no gateway Fiducia fora do escopo da fase em andamento sem atualizar este documento primeiro.

0. Contexto — por que este plano existe

O gateway Teste é 100% mock local; nada do que ele "confirma" prova que a integração real funciona. Fiducia foi implementado usando só a coleção Postman API_de_Contas_-_Integracao como contrato — que documenta requisição, mas não tem um único exemplo de resposta salvo para nenhum dos ~150 endpoints. Ou seja: os nomes de campo enviados estão confirmados; os nomes de campo lidos de volta ($response->json('campo')) são best-effort, marcados no código com // RESPOSTA NÃO CONFIRMADA.

Isso significa que nada neste adapter deve ser considerado correto até ser validado contra uma chamada real — daí o plano em fases, com um gate de validação (Fase 2) antes de qualquer outra coisa avançar.

1. Legenda de status

	Significado
✅	Concluído
🔵	Em andamento
⛔	Não iniciado
🔒	Bloqueado — depende de algo fora do controle do time de código

2. Fases

Fase 0 — Levantamento ✅

Objetivo: decidir provedor, escopo e arquitetura de credenciais antes de escrever qualquer código.

[x] Identificar o provedor real (Fiducia SCM — única coleção "conta bancária real" em fastgivr-docs-bank).
[x] Definir escopo da primeira entrega: contrato atual de BankInterface + métodos extra já chamados via Account::getBank() (não os ~150 endpoints da coleção inteira — cartões, cripto, remessas, onboarding via API ficam fora).
[x] Definir arquitetura de credenciais: sistêmica (.env) vs. por conta (banco, criptografada, com cálculo de expiração de sessão).
[x] Mapear cada método de BankInterface/getBank() para um endpoint da coleção Postman (tabela completa em Gateway Bancário Real).

Critério de saída: decisão registrada, mapeamento completo. Cumprido.

Fase 1 — Implementação do adapter ✅

Objetivo: código que compila, segue o mapeamento da Fase 0, e falha de forma explícita (nunca finge sucesso) onde não há endpoint confirmado.

[x] Migration 2026_09_09_000001_add_fiducia_credentials_to_accounts_table — bank_login_password/bank_operator_code (novas, criptografadas) + token ampliado para TEXT.
[x] App\Models\Account — $fillable/$casts (encrypted)/$hidden para as credenciais novas.
[x] config/banks.php — bloco fiducia (modo, URLs, timeout, credencial sistêmica).
[x] App\Models\Banks\Fiducia implements BankInterface — todos os métodos da interface + métodos extra usados via getBank() em produção (Pix in/out, boleto, transferência).
[x] .env.example atualizado.
[x] php -l em todos os arquivos tocados (sem vendor/ disponível neste ambiente para rodar testes/PHPStan — ver Fase 4).
[x] Documentação de referência (gateway-bancario-real.md) com o mapeamento completo e as lacunas conhecidas.

Critério de saída: código commitado, sintaticamente válido, sem chamada real ainda testada. Cumprido — branch claude/image-format-api-8yiyfu em fastgivr-api e fastgivr-docs-bank.

Fase 2 — Validação no sandbox real 🔒

Objetivo: provar (ou corrigir) cada suposição da Fase 1 contra o ambiente de homologação real da Fiducia (api.contashoml.fiduciascm.digital).

Bloqueio: exige credenciais reais de sandbox (login por conta: cpfcnpj/conta/password/cod_operador; e/ou credencial sistêmica: client_id/client_secret) e uma conta de teste já existente na Fiducia. Sem isso a fase não começa.

[ ] Provisionar FIDUCIA_SANDBOX_BASE_URL (já default) e as credenciais de uma conta de teste real em accounts.bank_login_password / bank_operator_code (criptografadas) — nunca direto no .env.
[ ] POST /login — confirmar nome do campo do token e do tempo de expiração na resposta; ajustar Fiducia::login() se divergir dos palpites atuais (token/access_token/accessToken, expires_in).
[ ] Para cada linha "Requisição sim, resposta não" da tabela de mapeamento: 1 chamada real, 1 ajuste de parsing se necessário, marcar como confirmado na tabela.
[ ] Confirmar a tabela de códigos tipo_chave/tipo_iniciacao do Pix (hoje é palpite em Fiducia::identifyPixKeyType()/pixKeyTypeCode()).
[ ] Confirmar se GET /pix/dict/gestao-chave/{chave}/oculto resolve chaves de terceiros (necessário para getPixTransactionDetails()) ou só as próprias — se só as próprias, achar o endpoint certo de consulta DICT de terceiros na coleção ou no suporte da Fiducia.
[ ] Confirmar com a Fiducia (ou testando) se existe endpoint de status para transferência instantânea (não agendada) — hoje getBankTransferStatus() só cobre /transferencia/agendada/:id.

Critério de saída: todas as linhas da tabela de mapeamento marcadas como confirmadas, ou documentadas como decisão consciente de não suportar (com justificativa). Nenhum // RESPOSTA NÃO CONFIRMADA deveria sobrar no código sem uma entrada correspondente aqui.

Fase 3 — Corrigir o que a Fase 2 encontrar errado ⛔

Objetivo: ajustar App\Models\Banks\Fiducia com os nomes de campo e comportamentos reais descobertos na Fase 2. Esta fase só existe separada da 2 porque "descobrir o que está errado" e "corrigir" são handoffs diferentes (a Fase 2 pode ser feita por quem tem acesso às credenciais; a correção pode voltar para quem escreveu o adapter).

[ ] Atualizar parsing de resposta em cada método afetado.
[ ] Remover os comentários // RESPOSTA NÃO CONFIRMADA confirmados.
[ ] Atualizar a tabela de mapeamento em gateway-bancario-real.md.

Critério de saída: zero divergência conhecida entre código e comportamento real observado no sandbox.

Fase 4 — Testes automatizados ⛔

Objetivo: travar o comportamento validado nas Fases 2/3 para não regredir silenciosamente.

[ ] composer install funcionando neste (ou outro) ambiente — não foi possível instalar vendor/ durante a Fase 1 (rede instável no ambiente de execução); confirmar antes de prosseguir.
[ ] Feature tests de App\Models\Banks\Fiducia com Http::fake() — um caso por método, usando as respostas reais capturadas na Fase 2 como fixtures (não respostas inventadas).
[ ] Teste de expiração/renovação de token (getAccessToken() chamando /login de novo só depois de token_expires vencer).
[ ] Teste de que baseUrl() recusa mode=production sem FIDUCIA_PRODUCTION_BASE_URL.
[ ] Rodar a suíte completa (php artisan test) para garantir que nada em Account (novos $fillable/$casts/$hidden) quebrou testes existentes.
[ ] Análise estática (phpstan/larastan, se configurado no projeto).

Critério de saída: suíte verde, cobertura de cada método do adapter.

Fase 5 — Piloto controlado em sandbox ⛔

Objetivo: operar o adapter real de ponta a ponta através do produto (não só chamadas isoladas), com uma conta de sandbox dedicada.

[ ] Criar uma Account de piloto com bank_gateway = 'Fiducia'.
[ ] Rodar o fluxo completo pelo app/internet banking: consulta de saldo (se/quando implementado), Pix in, Pix out (chave e dados bancários), emissão de boleto, pagamento de boleto de terceiro, transferência bancária, devolução de Pix.
[ ] Confirmar que os webhooks/settlement (PixInSettlementService etc.) funcionam com dados vindos de uma resposta real da Fiducia, não do mock Teste.
[ ] Revisar logs (Log::warning em Fiducia::assertSuccessful()) por qualquer falha silenciosa.

Critério de saída: um ciclo completo de produto rodando no sandbox real sem intervenção manual, por pelo menos alguns dias de uso ativo.

Fase 6 — Checklist de produção ⛔

Itens já listados em Gateway Bancário Real → Antes de ligar em produção, reproduzidos aqui como parte do plano:

[ ] Todas as fases 2–5 concluídas.
[ ] FIDUCIA_PRODUCTION_BASE_URL preenchida só quando a conta de produção estiver liberada pela Fiducia.
[ ] Credenciais de produção nunca reaproveitadas de sandbox (nem vice-versa) — client secret, login por conta, tudo distinto.
[ ] Plano de rotação de senha de login por conta (bank_login_password) documentado — o que fazer quando a Fiducia exigir troca.
[ ] Alçada/aprovação humana explícita antes de trocar BANK_DEFAULT_GATEWAY ou o bank_gateway de qualquer conta real para Fiducia em produção — decisão de negócio, não só técnica.
[ ] Plano de rollback: como voltar uma conta de Fiducia para Teste (ou pausar) se algo der errado em produção, sem perder dados de transações já em andamento.

Fase 7 — Rollout gradual em produção ⛔

Objetivo: não trocar todas as contas de uma vez.

[ ] Uma conta interna/de teste da própria empresa primeiro, com valores baixos.
[ ] Monitoramento ativo (alertas em BankException/falhas de autenticação) durante a janela inicial.
[ ] Expansão gradual (não definido neste documento — decisão de produto: percentual de contas novas, por volume, por segmento etc.).

3. Onde cada fase é rastreada

Fase	Dono	Onde fica o resultado
0–1	Time de código	`fastgivr-api` (branch `claude/image-format-api-8yiyfu`), este documento e `gateway-bancario-real.md`
2–3	Quem tem acesso às credenciais de sandbox + time de código	Tabela de mapeamento em `gateway-bancario-real.md`, atualizada linha a linha
4	Time de código	Suíte de testes em `fastgivr-api/tests`
5	Time de produto + código	Registro de piloto (fora deste repositório de docs, ou uma nova seção aqui quando começar)
6–7	Operações + decisão de negócio	Este documento (checklist marcado) + decisão registrada separadamente (não em código)

4. Riscos

Risco	Impacto	Mitigação
Nomes de campo de resposta errados chegam a produção sem validação	Alto — dinheiro real movido com dado mal interpretado (ex.: valor, destinatário)	Gate da Fase 2 obrigatório; `baseUrl()` já recusa `production` sem URL configurada
Código de `tipo_chave`/`tipo_iniciacao` do Pix errado	Alto — Pix pode ir para o destinatário/tipo errado	Validar explicitamente na Fase 2 antes de qualquer Pix out real
Credencial de sandbox vazando para produção (ou vice-versa)	Alto — mistura de ambientes	Checklist da Fase 6; credenciais sempre em variáveis/colunas separadas, nunca hardcoded
`consultarBoletosDDA()`/`printBoletoPdf()` sem endpoint conhecido	Baixo — funcionalidade opcional, já degrada para `[]`/`null`	Aceito como lacuna conhecida; revisitar se o produto passar a depender disso
Sem `vendor/` neste ambiente para rodar testes/análise estática	Médio — Fase 1 não pôde ser verificada além de `php -l`	Fase 4 cobre isso explicitamente antes de qualquer validação de negócio

Ver também

Gateway Bancário Real — Sandbox e Produção — contrato técnico e mapeamento método → endpoint
Mapa do MVP — onde o Pix/boleto/transferência aparecem no produto como um todo
Coleção Postman — API de Contas

Plano de Execução — Gateway Bancário Real (Fiducia) ​

0. Contexto — por que este plano existe ​

1. Legenda de status ​

2. Fases ​

Fase 0 — Levantamento ✅ ​

Fase 1 — Implementação do adapter ✅ ​

Fase 2 — Validação no sandbox real 🔒 ​

Fase 3 — Corrigir o que a Fase 2 encontrar errado ⛔ ​

Fase 4 — Testes automatizados ⛔ ​

Fase 5 — Piloto controlado em sandbox ⛔ ​

Fase 6 — Checklist de produção ⛔ ​

Fase 7 — Rollout gradual em produção ⛔ ​

3. Onde cada fase é rastreada ​

4. Riscos ​

Ver também ​