Integracao Asaas — Guia Completo

O Asaas e o gateway de pagamento da plataforma. Cada nucleo configura seu proprio Asaas — API Key, webhook token e ambiente sao independentes por nucleo.

1. Como Obter a API Key do Asaas

O administrador do nucleo precisa de uma conta no Asaas:

1. Acesse sandbox.asaas.com (testes) ou asaas.com (producao) e crie/acesse sua conta
2. Clique no icone de engrenagem (canto inferior esquerdo) → Configuracoes da Conta
3. No menu lateral, clique em Integracao
4. Na aba Chaves de API, clique em Gerar nova chave
5. Copie a chave (formato $aact_...)
6. Na plataforma, va em Configuracoes → cole no campo API Key Asaas

2. Como Configurar o Webhook

O webhook permite que o Asaas notifique a plataforma quando um pagamento e confirmado, atrasado ou estornado.

1. No Asaas, va em Configuracoes da Conta → Integracao
2. Clique na aba Webhooks → Adicionar
3. Cole a URL do webhook:

   https://mbles-api-541511987434.us-east1.run.app/api/webhooks/asaas

4. Selecione os eventos:
   • PAYMENT_CONFIRMED — pagamento confirmado
   • PAYMENT_RECEIVED — pagamento recebido
   • PAYMENT_OVERDUE — pagamento atrasado
   • PAYMENT_REFUNDED — estorno
   • PAYMENT_DELETED — cancelado
5. Clique em Salvar — o Asaas gera um Access Token automaticamente
6. Copie esse token e cole no campo Webhook Token Asaas nas configuracoes do nucleo

Importante: URL do Webhook e Dominios

https://mbles-api-541511987434.us-east1.run.app/api/webhooks/asaas

Validacao per-Nucleo

O sistema valida o webhook token por nucleo (nao globalmente):

Asaas envia webhook
  │
  ├── Body contem payment.id (ID do pagamento no Asaas)
  │
  ▼
Service busca pagamento no banco pelo asaas_payment_id
  │
  ├── Encontrou? → pega nucleo_id do pagamento
  │     → busca asaas_webhook_token do nucleo
  │     → valida header "asaas-access-token" contra token do nucleo
  │     → se invalido: 401 Unauthorized
  │
  └── Nao encontrou? → verifica se algum nucleo tem esse token
        → se nenhum tem: 401 Unauthorized

3. Ambiente: Sandbox vs Production

O admin alterna entre sandbox e production no campo Ambiente das configuracoes do nucleo. Cada ambiente requer sua propria API Key e Webhook Token.

4. Configuracao na Plataforma

Em Configuracoes (menu lateral), o admin preenche:

5. Customer (Cliente Asaas)

Criado automaticamente no primeiro pagamento do membro. Usa CPF para buscar/criar. Salvo em usuarios.asaas_customer_id.

6. Metodos de Pagamento

7. Split Payment (CC + R$)

O membro pode pagar parte com moedas virtuais e parte com R$:

Exemplo: Produto custa 5000 CC / R$50
Membro seleciona: 3000 CC + R$20 via PIX

Calculo:
proporcaoCC = 3000 / 5000 = 0.6 (60%)
valorReal = R$50 * (1 - 0.6) = R$20

Sistema:
1. Debita 3000 CC (imediato se 100% CC, ou via webhook se mix)
2. Gera cobranca Asaas de R$20
3. Webhook confirma → pedido avanca

8. Parcelamento

O admin define o maximo de parcelas por nucleo (nucleos.max_parcelas_cartao). Aplica a compras na loja com cartao de credito. Assinaturas nao parcelam.

9. Fluxo: Compra na Loja

Membro clica "Comprar"
  │
  ├── 100% CC?
  │     SIM → debita CC → pedido PENDENTE
  │
  └── Tem R$?
        │
        ▼
  Gera cobranca Asaas (PIX/Cartao/Boleto)
  Pedido fica AGUARDANDO_PAGAMENTO
        │
        ▼
  Webhook PAYMENT_CONFIRMED
        │
        ├── Valida token per-nucleo
        ├── Debita CC parciais (se mix)
        └── Pedido avanca para PENDENTE
              │
              ▼
        Admin: SEPARADO → ENTREGUE

10. Fluxo: Assinatura de Plano

Membro escolhe plano + ciclo (mensal/anual)
  │
  ├── 100% CC?
  │     SIM → debita CC → plano ativo imediato
  │
  └── Tem R$?
        │
        ▼
  Gera cobranca Asaas
  Assinatura fica PENDENTE
        │
        ▼
  Webhook PAYMENT_CONFIRMED
        │
        ├── Valida token per-nucleo
        ├── Debita CC parciais
        └── Ativa plano do usuario
              (plano_id + data_validade_plano)

11. Fluxo: Doacao

Membro seleciona valor (livre ou sugerido)
  │
  ├── 100% CC? → debita CC → doacao confirmada
  │
  └── R$? → cobranca Asaas → webhook confirma

12. Cupons de Desconto

Admin cria cupons (% ou valor fixo). Aplicados apenas na loja. O sistema valida: ativo, nao expirado, uso nao atingido. Desconto aplicado antes do split payment.

13. Arquitetura Tecnica

14. Tabela de Migrations Relacionadas