pagodera/TESTE_ABACATEPAY.md

Guia de Teste - Sistema de Doações AbacatePay

🔧 Configuração Inicial

1. Criar conta no AbacatePay

• Acesse: https://abacatepay.com
• Crie uma conta gratuita
• Acesse o Dashboard

2. Obter chave de API

• No Dashboard, vá para "API Keys" ou "Configurações"
• Copie sua TEST API KEY (começa com abc_test_...)
• Você também precisará da PRODUCTION API KEY quando for para produção

3. Configurar produtos (OPCIONAL)

O sistema de PIX não requer produtos pré-cadastrados no AbacatePay. Os valores são enviados diretamente na requisição.

Os produtos já estão definidos no código:

• Café: R$ 5,00 (500 centavos)
• Lanche: R$ 10,00 (1000 centavos)
• Almoço: R$ 25,00 (2500 centavos)

4. Configurar variáveis de ambiente

Crie um arquivo .env.local na raiz do projeto:

# AbacatePay API Keys
ABACATE_TEST_APIKEY=sua_chave_de_teste_aqui

# URL base da aplicação
NEXT_PUBLIC_BASE_URL=http://localhost:3000

IMPORTANTE: Não é necessário ABACATEPAY_ACCOUNT_ID nem produtos pré-cadastrados. O sistema PIX funciona diretamente com a API.

🧪 Testando o Sistema

Ambiente de Teste (Development)

1. Inicie o servidor de desenvolvimento:

pnpm run dev

2. Acesse a página de doações:

http://localhost:3000/pt/apoiar

3. Clique em um dos cards de doação

4. Verifique os logs no terminal:

🔧 AbacatePay: Using TEST environment
🔍 AbacatePay Request: {
  "frequency": "ONE_TIME",
  "methods": ["PIX"],
  "products": [
    {
      "externalId": "prod_...",
      "name": "Doação Café",
      "quantity": 1,
      "price": 500
    }
  ],
  ...
}
🔍 AbacatePay Response Status: 200

5. Resultado esperado:

• Status 200 ✅
• Redirecionamento para página de pagamento do AbacatePay
• OU exibição de QR Code PIX (modal)

Estrutura da Requisição Correta

{
  "frequency": "ONE_TIME",
  "methods": ["PIX"],
  "products": [
    {
      "externalId": "prod_6ryJmhfZGNJGjNaYaA1YqhDn",
      "name": "Doação Café",
      "quantity": 1,
      "price": 500
    }
  ],
  "returnUrl": "http://localhost:3000/apoiar/obrigado",
  "completionUrl": "http://localhost:3000/api/donations/verify"
}

Campos obrigatórios:

• ✅ externalId: ID do produto pré-cadastrado
• ✅ name: Nome do produto
• ✅ quantity: Quantidade (sempre 1)
• ✅ price: Valor em centavos (R$ 5,00 = 500)

🔍 Troubleshooting

Erro: "Route POST:/v1/billing not found"

Solução: Endpoint correto é /billing/create, não /billing

Erro: "must have required property 'name'"

Solução: Adicionar campo name no array de produtos

Erro: "Product not found"

Solução: Verificar se os IDs dos produtos estão corretos e existem no painel

Erro: "Invalid API key"

Solução:

• Verifique se a chave está correta no .env.local
• Certifique-se de usar ABACATE_TEST_APIKEY em development
• Reinicie o servidor após alterar variáveis de ambiente

Erro: "401 Unauthorized"

Solução: Chave de API expirada ou inválida. Gere uma nova no painel.

📋 Checklist de Validação

• Conta criada no AbacatePay
• API Key de teste obtida
• 3 produtos criados no painel (R$ 5, R$ 10, R$ 25)
• IDs dos produtos atualizados em types/donation.ts
• Arquivo .env.local criado com as variáveis
• Servidor reiniciado após configurar variáveis
• Página /pt/apoiar carrega sem erros
• Logs mostram "Using TEST environment"
• Clique em um card envia requisição
• Status 200 retornado
• Redirecionamento funciona ou QR Code é exibido

🚀 Deploy em Produção

Quando estiver pronto para produção:

1. Configure as variáveis no Vercel/Netlify:

ABACATE_APIKEY=abc_live_...
ABACATEPAY_ACCOUNT_ID=...
NEXT_PUBLIC_BASE_URL=https://seusite.com

2. O sistema detecta automaticamente o ambiente:

const isProduction = process.env.NODE_ENV === "production";
const apiKey = isProduction
  ? process.env.ABACATE_APIKEY
  : process.env.ABACATE_TEST_APIKEY;

3. Teste novamente em produção antes de divulgar

📞 Suporte

• Documentação: https://docs.abacatepay.com
• API Reference: https://abacatepay.readme.io
• Dashboard: https://abacatepay.com/dashboard