Runbook — Pix via Sicoob (primeira transação)

Como configurar os recebimentos por Pix (Sicoob) e validar a primeira transação. Decisão e trade-offs em ADR-0003.

Visão geral do fluxo

1. O checkout cria o pedido (pending) e uma cobrança Pix no Sicoob.
2. A página /pedido/retorno mostra QR Code + copia-e-cola e faz polling (5s).
3. O cliente paga no app do banco → Sicoob chama o webhook → a reconsulta confirma → o pedido vira paid → efeitos (pepitas / sócio pago-e-pendente).

Variáveis de ambiente

Fase 0 — Mock (ver a UI agora, sem nada externo)

Gera o QR PIX localmente — ideal para desenvolver/demonstrar a tela sem rede, certificado ou conta.

1. No .env.local: SICOOB_ENV=mock e SICOOB_PIX_KEY=teste@covil.com.br.
2. npm run dev, faça login, adicione um item ao carrinho e clique Gerar Pix. O QR Code + copia-e-cola aparece em /pedido/retorno, e o pedido fica em orders com pix_txid / pix_copia_cola.

No mock a cobrança nunca "confirma" (não há webhook). Serve para validar a UI.

Fase 1 — Sandbox do Sicoob (valida a comunicação)

SICOOB_ENV=sandbox fala com o endpoint de sandbox do Sicoob, usando o client_id público embutido. Atenção: o sandbox público é um mock de contrato — responde às chamadas (útil para confirmar que credenciais e formato estão certos), mas não devolve um QR real. Para ver o QR de verdade, use o modo mock (Fase 0) ou produção (Fase 2).

Fase 2 — Produção (primeira transação real)

1. Conta Sicoob com a API Pix Recebimentos habilitada (peça ao gerente). PF serve para começar; PJ é recomendada (ver ADR-0003).
2. Certificado ICP-Brasil A1 (e-CPF se PF; e-CNPJ se PJ). Converta para base64:

   [Convert]::ToBase64String([IO.File]::ReadAllBytes("certificado.pfx"))

   Cole em SICOOB_CERT_PFX_BASE64 e a senha em SICOOB_CERT_PASSWORD (Vercel).
3. Chave Pix cadastrada na conta → SICOOB_PIX_KEY.
4. client_id de produção no portal → SICOOB_CLIENT_ID. Defina SICOOB_ENV=production.
5. Cadastre o webhook na API do Sicoob (uma vez), apontando para a URL base — o Sicoob concatena /pix ao chamar:

   PUT https://api.sicoob.com.br/pix/api/v2/webhook/{SUA_CHAVE_PIX}
   Body: { "webhookUrl": "https://<seu-site>/api/sicoob/webhook" }

   (autenticado com Bearer + client_id + mTLS, como as demais chamadas).
6. Teste com R$ 0,01: gere um pedido, pague o QR, e confirme que o pedido vira paid e (se o comprador for sócio ativo) as pepitas creditam.

Troubleshooting

• Webhook não confirma: confira que a URL cadastrada bate e que o path recebido é /api/sicoob/webhook/pix. O handler reconsulta o txid; se a cobrança não estiver CONCLUIDA na API, ele (corretamente) não confirma.
• HTTP 401 / erro de auth em produção: certificado/senha errados ou API não habilitada na conta. Verifique SICOOB_CERT_* e fale com o gerente.
• QR não aparece: confira SICOOB_PIX_KEY e os logs — a criação da cobrança pode ter falhado (o pedido é marcado cancelled nesse caso).

Migração PF → PJ

Quando a atlética organizar o CNPJ: emita o certificado e-CNPJ, troque SICOOB_CERT_*, SICOOB_CLIENT_ID e SICOOB_PIX_KEY. Não há mudança de código.