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. Configuracao

O admin configura a API Key do Asaas em /dashboard/configuracoes:

• API Key: obtida no painel Asaas (sandbox ou producao)
• Ambiente: sandbox (testes) ou production (real)
• Webhook Token: para validar callbacks do Asaas

As credenciais ficam na tabela nucleos (colunas asaas_api_key, asaas_environment, asaas_webhook_token).

2. Fluxos de Pagamento

2.1 Compra na Loja (checkout)

1. Membro adiciona produtos ao carrinho
2. Escolhe: pagar parte em moedas + parte em R$ (split payment)
3. Escolhe metodo: PIX, Cartao ou Boleto
4. POST /loja/checkout → cria pedidos + cria cobranca no Asaas
5. Se PIX: retorna QR Code para pagamento
6. Se Cartao: processa na hora (pode parcelar)
7. Se Boleto: retorna URL do boleto
8. Webhook Asaas notifica CONFIRMED → pedido atualizado
9. Lancamento financeiro criado automaticamente (categoria DOACAO)

NOTA: Convidados (is_nucleo_origem=false) NAO podem usar a loja.
Saldo verificado via membros_nucleos.saldo_capixacoins.

2.2 Doacao

1. Membro acessa /dashboard/loja → secao "Doar"
2. Escolhe valor em R$ + opcionalmente em moedas
3. POST /loja/doar → cria registro + cobranca no Asaas
4. Mesmos metodos (PIX/Cartao/Boleto)
5. Webhook confirma → lancamento financeiro criado

2.3 Assinatura de Plano

1. Membro acessa /dashboard/assinatura
2. Escolhe plano e ciclo (mensal/semestral/anual)
3. POST /planos/assinar → cria assinatura + cobranca recorrente no Asaas
4. Webhook confirma cada parcela → atualiza data_validade_plano
5. Cron diario verifica vencimentos

3. Webhook do Asaas

Endpoint: POST /webhooks/asaas

O Asaas envia eventos quando o status de um pagamento muda:

4. Sync Automatico de Planos (Cron)

Problema: planos podem ser comprados fora da plataforma (site externo, transferencia direta). Esses pagamentos existem no Asaas mas nao na plataforma.

Solucao: cron diario (3h da manha) + trigger manual:

Cron @Cron('0 3 * * *') em MembrosService.syncPlanosFromAsaas:
1. Para cada nucleo com asaas_api_key configurada
2. Lista pagamentos CONFIRMED + RECEIVED dos ultimos 7 dias no Asaas
3. Agrupa parcelas (mesma customer + valor + descricao normalizada)
4. Tenta casar plano:
   a) Match por valor exato (preco_real == value)
   b) Match por nome do plano na descricao da cobranca
5. Tenta casar customer com membro do nucleo via CPF ou email
6. Se casar: atribui plano com plano_origem='asaas_sync' + 1 ano validade
7. Cria registro em pagamentos + financeiro_lancamentos
8. Se NAO casar usuario: cria lancamento financeiro mesmo assim
   (com nome do customer na descricao, "SEM MEMBRO VINCULADO")
9. Notifica o membro se atribuiu plano

Trigger Manual: Sincronizar Planos

Botao em /dashboard/membros → abre modal com:

• Presets de periodo: 7d, 30d, 90d, 6 meses, 1 ano, 2 anos
• Input customizado (1-730 dias)
• Modal de resultados detalhado por grupo (atribuidos, sem match, ja processados)
• Atribuicao manual inline para pagamentos sem match de usuario

5. Rebuild Financeiro

Busca TODAS as cobrancas confirmadas direto no Asaas (nao so da tabela pagamentos) e cria lancamentos financeiros retroativos.

• Agrupa parcelas automaticamente
• Filtra cobrancas de teste (descricao com "teste", valor < R$1, customer com nome "teste")
• Filtra parcelas futuras (dueDate > hoje)
• Detecta categoria: PLANO (match com planos cadastrados), DOACAO, EVENTO, OUTROS (heuristica)
• Idempotente via UNIQUE em asaas_payment_id

Botao "Limpar Sync Asaas"

Remove todos os lancamentos com origem=sync_asaas do nucleo. Util para refazer o rebuild do zero. NAO toca em lancamentos manuais ou webhook.

6. Atribuicao Manual de Plano

Admin pode atribuir plano a um membro manualmente (para pagamentos fora do Asaas):

• Tab "Plano" no detalhe do membro (/dashboard/membros/:id)
• Dropdown de planos + botao "Atribuir"
• Validade: 1 ano a partir de hoje
• plano_origem = manual, plano_atribuido_por = admin que atribuiu

7. Badges de Origem do Plano

8. Tabelas Envolvidas

• pagamentos — ledger de pagamentos reais (asaas_payment_id UNIQUE)
• financeiro_lancamentos — receitas/despesas (origem: manual, webhook_asaas, sync_asaas. asaas_payment_id UNIQUE parcial)
• membros_nucleos — plano_id, plano_origem, plano_atribuido_em/por, plano_asaas_payment_id
• pedidos_loja — pedidos com pagamento_id FK
• assinaturas — assinaturas recorrentes
• nucleos — asaas_api_key, asaas_environment, asaas_webhook_token

9. Erros Comuns