338 lines
8.0 KiB
Markdown
338 lines
8.0 KiB
Markdown
# 💳 Sistema de Parcelas Individuais com PIX
|
|
|
|
> **Controle completo de vendas parceladas com geração de PIX individual por vencimento**
|
|
|
|
## 🚀 Instalação Rápida (3 comandos)
|
|
|
|
```bash
|
|
# 1. Copie e execute no Supabase SQL Editor:
|
|
cat scripts/aplicar-sistema-parcelas.sql
|
|
|
|
# 2. Reinicie o servidor:
|
|
npm start
|
|
|
|
# 3. Teste no navegador:
|
|
http://localhost:3000
|
|
```
|
|
|
|
## ✨ O Que Mudou
|
|
|
|
### ANTES ❌
|
|
- Venda parcelada sem controle individual
|
|
- Um PIX único para o total
|
|
- Sem rastreamento de parcelas
|
|
- Mensagem genérica
|
|
|
|
### DEPOIS ✅
|
|
- **Cada parcela tem valor e vencimento próprios**
|
|
- **PIX individual por parcela**
|
|
- **Status: Pendente, Pago, Vencido**
|
|
- **Mensagem WhatsApp personalizada**
|
|
|
|
## 📸 Preview
|
|
|
|
### Mensagem Automática de Venda
|
|
```
|
|
Olá João! 👋
|
|
Sua compra foi registrada com sucesso! 💙
|
|
|
|
📅 Data da compra: 18/10/2025
|
|
💰 Valor total: R$ 150,00
|
|
💳 Pagamento: 3x de R$ 50,00 cada
|
|
|
|
Agradecemos pela sua preferência! 😊
|
|
Conte sempre com a Liberi Kids 👕👗
|
|
```
|
|
|
|
### Visualização de Parcelas
|
|
```
|
|
┌─────────────────────────────────┐
|
|
│ Parcela 1/3 🕐 Pendente │
|
|
│ 💰 R$ 50,00 │
|
|
│ 📅 18/11/2025 │
|
|
│ [Gerar PIX] 💳 │
|
|
├─────────────────────────────────┤
|
|
│ Parcela 2/3 ✅ Pago │
|
|
│ 💰 R$ 50,00 │
|
|
│ 📅 18/12/2025 │
|
|
│ ✅ Pago em: 17/12/2025 14:30 │
|
|
├─────────────────────────────────┤
|
|
│ Parcela 3/3 ⚠️ Vencida │
|
|
│ 💰 R$ 50,00 │
|
|
│ 📅 18/01/2026 │
|
|
│ [Gerar PIX] 💳 │
|
|
└─────────────────────────────────┘
|
|
```
|
|
|
|
## 🎯 Recursos Principais
|
|
|
|
| Recurso | Descrição |
|
|
|---------|-----------|
|
|
| 💳 **Parcelas Individuais** | Cada parcela com valor, vencimento e status próprios |
|
|
| 🏦 **PIX por Parcela** | Gere QR Code específico para cada vencimento |
|
|
| 📱 **WhatsApp Automático** | Mensagem personalizada com detalhes das parcelas |
|
|
| 🎨 **Interface Visual** | Cards coloridos por status (verde/amarelo/vermelho) |
|
|
| 📊 **Controle Total** | Rastreie pagamentos parcela por parcela |
|
|
| 🔔 **Alertas** | Integração com sistema de lembretes WhatsApp |
|
|
|
|
## 📚 Documentação
|
|
|
|
| Documento | Descrição |
|
|
|-----------|-----------|
|
|
| [IMPLEMENTACAO-COMPLETA-PARCELAS.md](IMPLEMENTACAO-COMPLETA-PARCELAS.md) | ✅ Checklist completo e detalhado |
|
|
| [GUIA-RAPIDO-PARCELAS.md](GUIA-RAPIDO-PARCELAS.md) | 🚀 Tutorial visual passo a passo |
|
|
| [INSTRUCOES-PARCELAS.md](INSTRUCOES-PARCELAS.md) | 📖 Documentação técnica completa |
|
|
| [scripts/aplicar-sistema-parcelas.sql](scripts/aplicar-sistema-parcelas.sql) | 💾 Script SQL de instalação |
|
|
|
|
## 🎓 Exemplo de Uso
|
|
|
|
```javascript
|
|
// 1. Cliente compra R$ 300,00 em 3x
|
|
Criar Venda Parcelada
|
|
├─ Valor: R$ 300,00
|
|
├─ Parcelas: 3x
|
|
└─ Resultado: 3 parcelas de R$ 100,00
|
|
|
|
// 2. Sistema salva automaticamente
|
|
venda_parcelas
|
|
├─ Parcela 1: R$ 100,00 → 18/11/2025
|
|
├─ Parcela 2: R$ 100,00 → 18/12/2025
|
|
└─ Parcela 3: R$ 100,00 → 18/01/2026
|
|
|
|
// 3. Cliente recebe WhatsApp
|
|
"Compra registrada: 3x de R$ 100,00 cada"
|
|
|
|
// 4. No vencimento, gere PIX individual
|
|
Parcela 1 → [Gerar PIX] → Enviar WhatsApp
|
|
Cliente paga → Status muda para ✅ Pago
|
|
|
|
// 5. Repetir para parcelas 2 e 3
|
|
Controle completo dos recebimentos!
|
|
```
|
|
|
|
## 🔥 Funcionalidades Avançadas
|
|
|
|
### 1. Geração de PIX Individual
|
|
```javascript
|
|
// Cada parcela gera seu próprio PIX
|
|
Parcela 1 → PIX de R$ 100,00
|
|
Parcela 2 → PIX de R$ 100,00
|
|
Parcela 3 → PIX de R$ 100,00
|
|
|
|
// Não mais um PIX único de R$ 300,00
|
|
```
|
|
|
|
### 2. WhatsApp por Parcela
|
|
```
|
|
Olá João! 💙
|
|
|
|
Segue o PIX para pagamento da *Parcela 2*:
|
|
|
|
💰 Valor: R$ 100,00
|
|
📅 Vencimento: 18/12/2025
|
|
|
|
[QR CODE IMAGE]
|
|
```
|
|
|
|
### 3. Status Automático
|
|
```javascript
|
|
// Sistema atualiza status automaticamente
|
|
Hoje < Vencimento → 🟡 Pendente
|
|
Pago → 🟢 Pago
|
|
Hoje > Vencimento → 🔴 Vencida
|
|
```
|
|
|
|
### 4. Integração com Alertas
|
|
```javascript
|
|
// Use variáveis nas mensagens de alerta:
|
|
{cliente} → Nome do cliente
|
|
{valor} → Valor da parcela
|
|
{quando} → Data de vencimento
|
|
{parcela} → Número da parcela
|
|
|
|
// Exemplo:
|
|
"Olá {cliente}! A {parcela} vence em {quando}. Valor: {valor}"
|
|
```
|
|
|
|
## 📊 Estrutura do Banco
|
|
|
|
```sql
|
|
CREATE TABLE venda_parcelas (
|
|
id UUID PRIMARY KEY,
|
|
venda_id UUID REFERENCES vendas(id),
|
|
numero_parcela INTEGER,
|
|
valor DECIMAL(10,2),
|
|
data_vencimento DATE,
|
|
status TEXT, -- pendente/pago/vencida/cancelada
|
|
data_pagamento TIMESTAMP,
|
|
pix_payment_id TEXT,
|
|
pix_qr_code TEXT,
|
|
pix_qr_code_base64 TEXT,
|
|
...
|
|
);
|
|
```
|
|
|
|
## 🌐 APIs Criadas
|
|
|
|
```javascript
|
|
// Listar parcelas de uma venda
|
|
GET /api/vendas/:id/parcelas
|
|
|
|
// Gerar PIX de uma parcela
|
|
POST /api/parcelas/:id/gerar-pix
|
|
|
|
// Enviar PIX por WhatsApp
|
|
POST /api/parcelas/:id/enviar-whatsapp
|
|
|
|
// Atualizar status da parcela
|
|
PUT /api/parcelas/:id/status
|
|
```
|
|
|
|
## 💡 Casos de Uso
|
|
|
|
### ✅ Loja de Roupas Infantis
|
|
- Venda de R$ 500,00 em 5x de R$ 100,00
|
|
- Cliente paga cada mês via PIX
|
|
- Lojista acompanha cada pagamento
|
|
- Envia lembrete antes do vencimento
|
|
|
|
### ✅ Venda de Alto Valor
|
|
- Produto caro parcelado em 10x
|
|
- Controle preciso de recebimentos
|
|
- PIX individual por parcela
|
|
- Menor risco de inadimplência
|
|
|
|
### ✅ Gestão Financeira
|
|
- Dashboard de parcelas a vencer
|
|
- Relatórios de recebimentos
|
|
- Previsão de entrada de caixa
|
|
- Controle de inadimplência
|
|
|
|
## ⚡ Performance
|
|
|
|
| Métrica | Valor |
|
|
|---------|-------|
|
|
| Tempo de geração de PIX | < 2s |
|
|
| Envio de WhatsApp | < 3s |
|
|
| Listagem de parcelas | < 100ms |
|
|
| Criação de venda | < 500ms |
|
|
|
|
## 🔒 Segurança
|
|
|
|
- ✅ Row Level Security (RLS) habilitado
|
|
- ✅ Validação de dados no backend
|
|
- ✅ Proteção contra SQL injection
|
|
- ✅ Autenticação via Supabase
|
|
- ✅ Criptografia de comunicações
|
|
|
|
## 🎨 Design Responsivo
|
|
|
|
```css
|
|
/* Desktop */
|
|
.parcelas-list {
|
|
grid-template-columns: repeat(3, 1fr);
|
|
}
|
|
|
|
/* Tablet */
|
|
@media (max-width: 768px) {
|
|
grid-template-columns: repeat(2, 1fr);
|
|
}
|
|
|
|
/* Mobile */
|
|
@media (max-width: 480px) {
|
|
grid-template-columns: 1fr;
|
|
}
|
|
```
|
|
|
|
## 📈 Roadmap
|
|
|
|
### ✅ Implementado
|
|
- [x] Tabela de parcelas
|
|
- [x] Backend APIs
|
|
- [x] Frontend UI
|
|
- [x] PIX individual
|
|
- [x] WhatsApp por parcela
|
|
- [x] Status visual
|
|
|
|
### 🔜 Próximas Features
|
|
- [ ] Dashboard de vencimentos
|
|
- [ ] Alertas automáticos
|
|
- [ ] Relatório de inadimplência
|
|
- [ ] Integração com boleto
|
|
- [ ] Desconto pagamento antecipado
|
|
- [ ] Juros para atraso
|
|
|
|
## 🐛 Troubleshooting
|
|
|
|
### Problema: Parcelas não aparecem
|
|
**Solução:**
|
|
```bash
|
|
# 1. Verificar se tabela existe
|
|
SELECT * FROM venda_parcelas LIMIT 1;
|
|
|
|
# 2. Reiniciar servidor
|
|
npm start
|
|
|
|
# 3. Limpar cache do navegador
|
|
Ctrl+Shift+R
|
|
```
|
|
|
|
### Problema: PIX não gera
|
|
**Solução:**
|
|
```bash
|
|
# 1. Verificar credenciais MercadoPago
|
|
cat .env | grep MERCADO_PAGO
|
|
|
|
# 2. Testar conexão
|
|
curl -X POST http://localhost:5000/api/test-pix
|
|
|
|
# 3. Ver logs do servidor
|
|
tail -f server.log
|
|
```
|
|
|
|
## 📞 Suporte
|
|
|
|
- 📧 Email: suporte@liberikids.com
|
|
- 💬 WhatsApp: (XX) XXXXX-XXXX
|
|
- 📖 Docs: [Documentação Completa](IMPLEMENTACAO-COMPLETA-PARCELAS.md)
|
|
|
|
## 🏆 Créditos
|
|
|
|
Desenvolvido para **Liberi Kids - Moda Infantil** 👕👗
|
|
|
|
## 📄 Licença
|
|
|
|
MIT License - Uso livre para o projeto Liberi Kids
|
|
|
|
---
|
|
|
|
## 🎯 TL;DR
|
|
|
|
```bash
|
|
# 1. Execute SQL no Supabase
|
|
scripts/aplicar-sistema-parcelas.sql
|
|
|
|
# 2. Reinicie servidor
|
|
npm start
|
|
|
|
# 3. Crie venda parcelada
|
|
Vendas > Nova Venda > Parcelado > 3x
|
|
|
|
# 4. Visualize parcelas
|
|
Clique no 👁️ da venda
|
|
|
|
# 5. Gere PIX
|
|
Clique "Gerar PIX" na parcela
|
|
|
|
# 6. Envie WhatsApp
|
|
Botão "Enviar por WhatsApp"
|
|
|
|
✅ PRONTO! Sistema funcionando!
|
|
```
|
|
|
|
---
|
|
|
|
**🚀 Comece agora e tenha controle total das suas vendas parceladas!**
|
|
|
|
*Leia: [IMPLEMENTACAO-COMPLETA-PARCELAS.md](IMPLEMENTACAO-COMPLETA-PARCELAS.md) para mais detalhes*
|