# Skill Cobranca Automatizada Saas Abacatepay

> Automatic SaaS billing engine with AbacatePay (PIX + credit card), configurable dunning (regua de cobranca), trial management, invoice portal, email (Resend) and WhatsApp (Evolution API) notifications, admin CRUD, and billing metrics. Covers the full billing lifecycle from provisioning to collection.

- Skill: `iapro-community/skill-cobranca-automatizada-saas-abacatepay-2` (Agent Skill, multi-file: 6 files)
- Install (CLI): `npx skillmds@latest add iapro-community/skill-cobranca-automatizada-saas-abacatepay-2`
- Raw SKILL.md: https://api.skillmd.com/api/skills/iapro-community/skill-cobranca-automatizada-saas-abacatepay-2/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Finance & Business
- Author: IAPro-Community (https://skillmd.com/u/iapro-community)
- Updated: 2026-09-21
- Page: https://skillmd.com/skills/iapro-community/skill-cobranca-automatizada-saas-abacatepay-2

---


# skill-cobranca-automatizada-saas-abacatepay

## When To Use

This skill covers the complete automated billing system ("cobranca automatizada") for Brazilian SaaS products using AbacatePay. Use when implementing or maintaining:

=== Provisioning ===
- Billing configuration tables (cobrancas, cobranca_reguas, billing_config, etc.)
- Dunning rule sequencing (cobranca_regua_eventos)
- Encrypted integration configs (Resend, Evolution API, AbacatePay)

=== Billing Engine ===
- Automated invoice generation and dunning execution via cron
- AbacatePay billing creation (PIX + CARD)
- Webhook processing with HMAC-SHA256 verification
- Invoice state machine (pending, paid, overdue, cancelled, refunded)
- Subscription/plan integration via cobranca_tracking

=== Trial Management ===
- Configurable trial duration
- Pre-expiration notifications (7/3/1 days before)
- Automatic trial expiration and account blocking

=== Interfaces ===
- Public invoice page (FaturaPage) with PIX QR Code, payment link, polling
- Pricing/Plans page with AbacatePay checkout
- User-side invoice listing (MinhasCobrancasSection)
- Admin billing management (cobranças CRUD, planos CRUD, global settings)
- Plan Manager (PlanManager) for user plan changes

=== Notifications ===
- Email via Resend with HTML templates (logo, badge, invoice details)
- WhatsApp via Evolution API with template variables
- Variables: {{nome}}, {{plano}}, {{valor}}, {{vencimento}}, {{link_pagamento}}, {{empresa_nome}}
- Dunning sequence: configurable events with days_apos_vencimento, channel (email/whatsapp/ambos)

## Architecture

```
                     +-------------------+
                     |   Cron (8/12/16h  |
                     |   BRT + 5min)     |
                     +--------+----------+
                              |
         +--------------------+--------------------+
         |                    |                    |
   Processar            Trial               Metrics
   Cobranças          Notificações          (meia-noite)
         |                    |
   +-----v------+      +-----v------+
   | Ver regua   |      | Trial exp. |
   | Send notif  |      | Notif pre  |
   | Create bill |      +------------+
   +-----+------+
         |
   +-----v------------------------------------------+
   |           Controller Layer                      |
   |  cobrancas.ts | abacatepay-webhook.ts           |
   |  fatura.ts    | trial.ts                        |
   +-----+----------------------------+--------------+
         |                            |
   +-----v----------+        +--------v---------+
   |  AbacatePay    |        |  Notifications    |
   |  API v2        |        |  Resend + Evol.  |
   +----------------+        +------------------+
         |
   +-----v----------+
   |  Supabase/     |
   |  PostgreSQL    |
   +----------------+
```

## Billing State Machine

```
pending ──► paid ──► refunded
  │
  ├──► overdue ──► paid
  │             └──► cancelled
  │
  └──► cancelled
```

States managed by `invoice-state-machine.ts`:
- `pending`: cobrança criada, aguardando pagamento
- `paid`: paga, `released_at` setado, conteúdo liberado
- `overdue`: vencida, entra na régua de cobrança
- `cancelled`: cancelada manualmente ou por expiração
- `refunded`: estornada (transição exclusiva de `paid`)

## Key Tables

| Table | Purpose |
|---|---|
| `cobrancas` | Core billing records per user |
| `cobranca_reguas` | Dunning rule sets per tenant |
| `cobranca_regua_eventos` | Individual dunning events in sequence |
| `billing_config` | Encrypted integration configs (Resend, Evolution, AbacatePay) |
| `front_users` | User profiles with plan and status |
| `partner_billing_config` | Partner-specific billing overrides |
| `cobranca_tracking` | Subscription-like recurring billing tracking |
| `transaction_log` | Billing operation audit log |
| `abacatepay_events` | Raw webhook event storage |

Full details in `billing-tables.md`.

## Core Flows

### Dunning Flow (Régua de Cobrança)
1. Cron runs billing-cron.ts at 8h/12h/16h BRT
2. Queries cobrancas WHERE status = 'overdue' AND NOT paga
3. For each cobranca, resolves billing_config + cobranca_regua + cobranca_regua_eventos
4. Checks if next evento should fire (based on dias_apos_vencimento)
5. Sends notification via billing-sender.ts (email + WhatsApp)
6. If all eventos fired and still overdue, marks as cancelled

### Webhook Flow
1. POST /api/abacatepay-webhook receives event
2. HMAC-SHA256 signature verification (replay + timing-safe compare)
3. Rate limited: 100 req/min per IP
4. On `billing.paid`: processPaymentWithTransaction updates cobranca + cobranca_tracking
5. On failure: processRollback reverts state
6. Raw event stored in abacatepay_events

### Trial Flow
1. trial-cron.ts runs every 5 minutes
2. Queries users where trial ends within notification window
3. Sends pre-expiration notifications (7/3/1 day before)
4. On expiration: blocks account (status = blocked)
5. billing-cron.ts also handles trial notifications at 8/12/16h

### Invoice Portal Flow
1. FaturaPage loads by shortlink (8 chars, unique)
2. Materializes billing from AbacatePay API on demand
3. Shows: PIX QR Code, payment link, due date, amount, status badge
4. Polls status every 5 seconds
5. "Share via WhatsApp" button with pre-formatted message

## Configuration

billing_config stores encrypted credentials per owner (AES-256-GCM):
- `resend_config`: Resend API key + from email
- `evolution_config`: Evolution API URL + API key + instance
- `abacatepay_config`: AbacatePay API key
- `trial_duration_days`: Trial length (default)
- Encryption key: BILLING_CONFIG_ENCRYPTION_KEY env var

See `billing-config.md` for full schema and setup.

## Guardrails

1. Keep ALL payment provider secrets server-side. Never expose AbacatePay API keys in browser bundles.
2. Process webhooks idempotently: check cobranca current state before mutating.
3. Treat checkout redirect as advisory. Grant access only after webhook confirmation.
4. Do not log API keys, webhook secrets, full CPF/CNPJ, full phone numbers.
5. Cron must not overlap. billing-cron uses lock checks to prevent concurrent runs.
6. Dunning notifications must respect channel preference (email, whatsapp, or ambos).
7. Trial expiration is irreversible: set status = blocked, do not auto-unblock without payment.
8. Metrics queries (MRR, faturamento) should use aggregateBillingMetrics(), not ad-hoc SQL.

## Local Reference (example-saas)

This skill is extracted from the example-saas SaaS billing system. The production codebase is at:

- `{{USER_HOME}}/Documents/Code/example-saas/server/controllers/cobrancas.ts` — billing CRUD + processing + dunning
- `{{USER_HOME}}/Documents/Code/example-saas/server/controllers/abacatepay-webhook.ts` — webhook handler
- `{{USER_HOME}}/Documents/Code/example-saas/server/controllers/fatura.ts` — invoice lookup by shortlink
- `{{USER_HOME}}/Documents/Code/example-saas/server/controllers/trial.ts` — trial expiration processing
- `{{USER_HOME}}/Documents/Code/example-saas/server/services/abacatepay-create-billing-v2.ts` — AbacatePay billing creation
- `{{USER_HOME}}/Documents/Code/example-saas/server/services/billing-sender.ts` — notification dispatch (email + WhatsApp)
- `{{USER_HOME}}/Documents/Code/example-saas/server/services/billing-email-template.ts` — HTML invoice email template
- `{{USER_HOME}}/Documents/Code/example-saas/server/services/billing-integrations-config.ts` — encrypted config management
- `{{USER_HOME}}/Documents/Code/example-saas/server/services/billing-metrics.ts` — MRR and billing metrics
- `{{USER_HOME}}/Documents/Code/example-saas/server/utils/invoice-state-machine.ts` — state machine logic
- `{{USER_HOME}}/Documents/Code/example-saas/server/cron/billing-cron.ts` — main billing scheduler
- `{{USER_HOME}}/Documents/Code/example-saas/server/cron/trial-cron.ts` — trial scheduler
- `{{USER_HOME}}/Documents/Code/example-saas/src/pages/FaturaPage.tsx` — public invoice page
- `{{USER_HOME}}/Documents/Code/example-saas/src/components/PlansPage.tsx` — pricing/plans page
- `{{USER_HOME}}/Documents/Code/example-saas/src/components/PlanManager.tsx` — user plan manager
- `{{USER_HOME}}/Documents/Code/example-saas/src/components/AdminCobrancas.tsx` — admin billing CRUD
- `{{USER_HOME}}/Documents/Code/example-saas/src/components/AdminPlanos.tsx` — admin plan CRUD
- `{{USER_HOME}}/Documents/Code/example-saas/src/components/AdminGlobalSettings.tsx` — global settings
- `{{USER_HOME}}/Documents/Code/example-saas/src/components/MinhasCobrancasSection.tsx` — user invoice list
- `{{USER_HOME}}/Documents/Code/example-saas/supabase/migrations/20260617_cobrancas_foundation.sql` — core tables
- `{{USER_HOME}}/Documents/Code/example-saas/supabase/migrations/20260617_cobrancas_website_final.sql` — shortlink trigger
- `{{USER_HOME}}/Documents/Code/example-saas/supabase/migrations/20240101_billing_config.sql` — billing_config table
- `{{USER_HOME}}/Documents/Code/example-saas/supabase/migrations/20240117_partner_billing.sql` — partner billing

## Reference Files

- `billing-tables.md` — complete table schemas, indexes, enums, RLS policies
- `billing-flows.md` — detailed flow diagrams and pseudocode for each core flow
- `billing-config.md` — encryption, config resolution, and setup steps
- `billing-admin.md` — admin interfaces and CRUD operations
- `billing-notifications.md` — email/WhatsApp templates, dunning sequence, template variables

## Validation

- After changes, run build and typecheck (npm run build, npm run typecheck or equivalent)
- Simulate webhook: POST billing.paid event and verify idempotent processing
- Test dunning: create overdue cobranca with regua de 0/3/7 dias and confirm notification dispatch
- Test trial: set trial_duration_days=1, create user, wait for pre-expiration and expiration
- Verify no AbacatePay/Resend/Evolution keys leak to browser bundles
- Run project lint when available

## Related Skills

- `skill-abacatepay-integration` — AbacatePay API specifics (billing create, list, webhook)
- `skill-saas-core-limits` — plan limits, entitlements, feature flags after payment
- `skill-evolution-api` — WhatsApp notification channel
- `skill-supabase-rls` — RLS policies for billing tables
- `skill-saas-factory` — top-level SaaS construction entry