Billing

Endpoints para consumo, faturas e emissão via gateway de pagamento Asaas (Pix, boleto, cartão).

Base paths: /v1/usage, /v1/billing

---

Modelo de cobrança

O gateway suporta múltiplos planos. Cada account é vinculada a um BillingPlan:

Plan code	Modelo
pay_as_you_go	Cobrado por mensagem enviada + por phone ativo no mês
flat	Mensalidade fixa + overage (acima de N mensagens incluídas)
free_tier	Sem cobrança (uso interno / parceiros)
custom	Configurado por negociação (campo metadata no plano)

Além disso, custos WABA (conversas categorizadas pela Meta) são repassados com markup opcional (account.wabaMarkupPct).

---

Usage

GET /v1/usage

Resumo de uso. Sem query params → mês corrente. Com from/to → período custom (UTC).

curl https://wpp.ogmma.com.br/v1/usage \
  -H "X-API-Key: ak_live_..."

curl 'https://wpp.ogmma.com.br/v1/usage?from=2026-04-01T00:00:00.000Z&to=2026-05-01T00:00:00.000Z' \
  -H "X-API-Key: ak_live_..."

Response 200

{
  "period": { "from": "2026-05-01T00:00:00.000Z", "to": "2026-06-01T00:00:00.000Z" },
  "costCents": 12500,
  "wabaPassthroughCents": 8200,
  "messagesSent": 1234,
  "messagesReceived": 567,
  "activePhones": 3,
  "breakdown": {
    "BAILEYS": { "sent": 800, "received": 400 },
    "WABA": { "sent": 400, "received": 150, "conversations": { "MARKETING": 12, "UTILITY": 88 } },
    "INSTAGRAM": { "sent": 34, "received": 17 }
  }
}

Campo	Descrição
costCents	Total em centavos BRL
wabaPassthroughCents	Custo Meta (conversas WABA) repassado
messagesSent / messagesReceived	Contadores absolutos
activePhones	Phones que enviaram ≥1 mensagem no período

Errors

HTTP	Code	Quando
400	VALIDATION_ERROR	from sem to ou vice-versa

---

Current bill

GET /v1/billing/current

Resumo simplificado do mês corrente (idêntico a /v1/usage sem params, formato reduzido).

curl https://wpp.ogmma.com.br/v1/billing/current \
  -H "X-API-Key: ak_live_..."

Response 200

{
  "period": { "from": "...", "to": "..." },
  "costCents": 12500,
  "wabaPassthroughCents": 8200,
  "messagesSent": 1234,
  "activePhones": 3
}

---

Invoices

GET /v1/billing/invoices

Lista as últimas 24 faturas (12 meses x 2 ciclos potenciais).

Response 200

[
  {
    "id": "inv-1234-...",
    "accountId": "...",
    "periodStart": "2026-04-01T00:00:00.000Z",
    "periodEnd": "2026-05-01T00:00:00.000Z",
    "totalCents": 12500,
    "breakdown": { "messages": 4500, "phoneMonths": 3000, "wabaPassthrough": 5000 },
    "status": "PAID",
    "dueDate": "2026-05-10T00:00:00.000Z",
    "paidAt": "2026-05-08T15:23:00.000Z",
    "gatewayProvider": "asaas",
    "gatewayChargeId": "pay_1234567",
    "gatewayInvoiceUrl": "https://www.asaas.com/i/pay_1234567",
    "pixQrCode": "iVBORw0KG...",
    "pixCopyPaste": "00020126...",
    "boletoUrl": "https://www.asaas.com/b/pdf/pay_1234567",
    "boletoBarcode": "23793.39001 ...",
    "createdAt": "...",
    "updatedAt": "..."
  }
]

Status:

Status	Significado
OPEN	Criada localmente, sem gateway ainda
ISSUED	Cobrança criada no gateway, aguardando pagamento
PAID	Pagamento confirmado
OVERDUE	Gateway marcou atrasada
FAILED	Chargeback ou falha definitiva
REFUNDED	Estornada
VOID	Anulada antes de cobrar

GET /v1/billing/invoices/:id

Detalhe.

Errors

HTTP	Code	Quando
404	INVOICE_NOT_FOUND	—

---

Asaas (gateway de pagamento)

Padrão da Oggma para BR: Asaas. Suporta Pix, boleto e cartão.

POST /v1/billing/customer

Cria/atualiza o customer no Asaas. Necessário antes de emitir a primeira fatura.

Body

Campo	Tipo	Obrigatório
cpfCnpj	string	sim (11 ou 14 dígitos)
name	string	não (usa account.name)
phone	string	não
addressLine	string	não
addressNumber	string	não
province	string	não
postalCode	string	não (CEP)

curl -X POST https://wpp.ogmma.com.br/v1/billing/customer \
  -H "X-API-Key: ak_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "cpfCnpj": "12345678000199",
    "phone": "5511988887777",
    "addressLine": "Av. Paulista",
    "addressNumber": "1000",
    "province": "Bela Vista",
    "postalCode": "01310100"
  }'

Response 201

{ "asaasCustomerId": "cus_1234567" }

Errors

HTTP	Code	Quando
503	ASAAS_NOT_CONFIGURED	Servidor sem ASAAS_API_KEY

POST /v1/billing/invoices/:id/issue

Emite uma fatura no Asaas (cria charge + retorna links de pagamento).

Body (opcional)

Campo	Tipo	Default
billingType	BOLETO | PIX | CREDIT_CARD | UNDEFINED	UNDEFINED (cliente escolhe na página)
dueInDays	int	servidor define (geralmente 10)

curl -X POST https://wpp.ogmma.com.br/v1/billing/invoices/inv-1234-.../issue \
  -H "X-API-Key: ak_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "billingType": "PIX", "dueInDays": 7 }'

Response 200

{
  "id": "inv-1234-...",
  "status": "ISSUED",
  "gatewayChargeId": "pay_1234567",
  "gatewayInvoiceUrl": "https://www.asaas.com/i/pay_1234567",
  "pixQrCode": "iVBORw0KG...",
  "pixCopyPaste": "00020126...",
  "boletoUrl": null,
  "boletoBarcode": null,
  "dueDate": "2026-05-28T00:00:00.000Z"
}

---

Dunning (inadimplência)

O gateway tem um ciclo automatizado de cobrança:

   Fatura overdue?
        │
        ▼
   1-6 dias atraso  → WARNING   (email lembrete)
        │
        ▼
   7-13 dias atraso → CRITICAL  (email firme + flag)
        │
        ▼
   14+ dias atraso  → SUSPENDED (account.status='SUSPENDED' → API bloqueada)

Em SUSPENDED:

• Toda chamada autenticada retorna 402 ACCOUNT_SUSPENDED.
• Webhooks param de ser entregues (entram em DLQ).
• Worker para de processar mensagens (já enfileiradas ficam aguardando).
• Phones permanecem ativos no DB (não há logout WhatsApp).

Após pagamento, o webhook Asaas reativa automaticamente (reactivateAccountIfClean).

---

Webhook Asaas (interno)

POST /v1/asaas-webhook é o endpoint público que recebe eventos do Asaas (payment.confirmed, payment.refunded, etc). Não é chamado pelo cliente — é configurado no painel Asaas com asaas-access-token header.

Eventos publicados após processar:

• billing:invoice.paid → conteúdo: invoice id, paidAt.
• billing:invoice.failed → conteúdo: invoice id, reason.

Disponíveis no webhook do cliente caso ele subscreva esses tipos.

---

Boas práticas

1. Crie o customer Asaas no onboarding — sem isso, primeira fatura mensal falha.
2. Monitore account.dunningStage via dashboard interno (não exposto via API pública — admin only).
3. Pague antes de 14 dias para evitar SUSPENDED automático.
4. Implemente UI de invoice consumindo pixQrCode (base64 PNG) e pixCopyPaste para o usuário pagar dentro do seu app.