Vintém — Efí

Receber Pix pela sua conta Efí, com o Vintém no meio.

⚠️ O adapter ainda não foi testado na homologação do Efí. Ele foi escrito pela documentação oficial e testado contra um Efí simulado. Os pontos que só a homologação confirma estão marcados abaixo. Acompanhe pela #27.

1. Conta e credenciais

1. Conta Digital Efí com o menu “API”. É o que a documentação da Efí pede; conta de pessoa física também serve se o menu aparecer. O menu só existe no painel web, não no app.
2. No painel, em API → Aplicações, crie uma aplicação e ative a API Pix com os escopos de homologação (e de produção, quando for a hora): os escopos que o Vintém usa são cob.write, cob.read, cobv.write, cobv.read, pix.read (Pix recebidos), pix.write (devolução) e webhook.write. No painel eles aparecem como Alterar/Consultar cobranças, Alterar/Consultar Pix, Alterar Webhooks e Alterar/Consultar cobranças com vencimento. Não marque Enviar Pix nem Pagar QR Code: o Vintém só recebe. O painel não deixa criar a aplicação sem ao menos um escopo de produção; para testar só na homologação, marque em produção apenas “Consultar cobranças”, que só lê.
3. Copie o Client ID e o Client Secret do ambiente que vai usar. Cada aplicação tem um par para produção e outro para homologação.
4. Em API → Meus Certificados, gere o certificado do mesmo ambiente e baixe o .p12. O download só acontece na criação.

2. Cadastrar a conta no Vintém

Segredos vêm de arquivo, nunca de flag, porque flag fica no histórico do shell:

printf '%s' 'SEU_CLIENT_SECRET' > secret.txt   # ou crie o arquivo num editor
vintem conta criar --id minha-loja --nome "Minha Loja" --psp efi \
  --chave sua-chave-pix@exemplo.com --ambiente homologacao \
  --client-id SEU_CLIENT_ID --client-secret-arquivo secret.txt \
  --certificado homologacao.p12

Se o .p12 tiver senha, passe também --senha-certificado-arquivo. O certificado é conferido na hora (RN-62), e o conta listar mostra até quando ele vale. Depois, apague secret.txt: o Vintém guarda tudo cifrado com a VINTEM_MASTER_KEY.

A chave Pix precisa ser da conta Efí; senão o Efí recusa a cobrança com chave_invalida.

3. Webhook

vintem conta webhook minha-loja --url-publica https://seu-vintem.exemplo.com

O Vintém gera uma URL com um token secreto e a registra na sua chave Pix (PUT /v2/webhook/:chave). O Efí acrescenta /pix ao fim, e a rota do Vintém aceita os dois caminhos. Ao registrar, o Efí manda uma notificação de teste, que o Vintém aceita sem registrar nada.

Sobre o mTLS do webhook. O Efí exige mTLS no servidor que recebe o aviso. O Vintém não termina TLS, então registra o webhook com x-skip-mtls-checking: true. Nesse modo, o Efí pede que você garanta de outro jeito que o aviso veio dele:

• O token secreto na URL já faz o papel do “hmac na URL” que o Efí sugere. Aviso sem o token certo responde 401.
• Restrinja a origem no seu proxy ao IP que o Efí publica (hoje 34.193.116.226; confira na documentação de webhooks).

Se o webhook falhar ou sumir, a conciliação busca os Pix em GET /v2/pix a cada 5 minutos (RN-31). Nenhum pagamento depende só do aviso.

4. Testar na homologação

• Só cobranças de R$ 0,01 a R$ 10,00 são confirmadas e geram webhook. Acima disso, a cobrança fica ATIVA para sempre.
• Devolução de R$ 0,01 é rejeitada de propósito (simulação de falha).

Desvios do Efí tratados pelo adapter

Estão no código, em internal/adapters/psp/efi/doc.go:

• Erros: o Efí responde {"nome","mensagem"} na cob e o formato de problema na cobv.
• expiracao vem como string no GET.
• GET /v2/pix filtra com fim inclusivo.
• Devolução com id repetido responde 409; o adapter a torna idempotente.
• ⚠️ A confirmar na homologação: o erro de txid repetido na cobv, que a documentação não nomeia.