Evandro Fonseca Junior
ef521876eb
Updated ABACATEPAY_SETUP.md with comprehensive setup guide, including environment variables, API key instructions, webhook configuration, donation flow, and field details for better integration clarity. Added required fields (phone, CPF/CNPJ) to the donation form in app/[locale]/apoiar/page.tsx to collect essential donor information and improve compliance. This ensures smoother setup and more robust donation processing.
163 lines
4.2 KiB
Markdown
163 lines
4.2 KiB
Markdown
# 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:
|
|
|
|
```env
|
|
# 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**:
|
|
```bash
|
|
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
|
|
|
|
```json
|
|
{
|
|
"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:
|
|
```typescript
|
|
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
|
|
|