Integração Asaas – BarberBot

📁 Estrutura dos arquivos (o que existe nos 3 módulos)

Os três módulos repetem praticamente a mesma estrutura interna:

• index.php – tela principal do checkout (entrada do usuário).
• status.php – consulta status do pagamento no Asaas (GET no endpoint de pagamentos).
• obrigado.php – página de “sucesso”/finalização visual (pós checkout).
• pagamento_aprovado.php – rotina de confirmação (baixa e/ou confirmação do serviço/assinatura).
• confirmacao.php e api-texto.php – mensageria/WhatsApp (confirmações/recibos).
• config/ – engine do checkout (config API + blocos Pix/Cartão/Boleto + CSS).

Subpasta config/

• configApi.php – token e base do host (usa variáveis do sistema).
• processa.php – processamento do Cartão (POST com dados do cartão e holder).
• processa_boleto.php – geração/retorno do Boleto.
• gerar_pix.php – criação do cliente + pagamento Pix + obtenção do QR Code.
• blocos/pix.php, blocos/cartao.php, blocos/boleto.php – HTML do checkout por método.
• css/style.css – estilos do checkout.

⚙️ Configuração da API (token e host)

config/configApi.php

Arquivo simples que “pega” o token e calcula o host base. No seu projeto está assim:

$access_token = $asaas;
$host_dir     = $url_sistema.'asaas/';

• $asaas vem do sistema (normalmente de /sistema/conexao.php ou config central).
• $url_sistema vem do sistema e precisa ser a URL base correta.
• Sem token correto, nenhum checkout vai gerar cliente/pagamento.

Endpoints usados (API v3)

• POST https://api.asaas.com/v3/customers – cria cliente.
• POST https://api.asaas.com/v3/payments – cria pagamento.
• GET https://api.asaas.com/v3/payments/<ID> – consulta status.

🔁 Fluxo do checkout de AGENDAMENTO (asaas/)

1) Entrada – asaas/index.php

• Recebe id (id do registro em agendamentos_temp) e o total.
• Mostra UI com três métodos: Pix / Cartão / Boleto.
• Os blocos HTML vêm de config/blocos/*.php.

2) PIX – asaas/config/gerar_pix.php

• Carrega o agendamentos_temp (por id) e extrai cliente/serviço.
• Cria/garante cliente no Asaas (/customers).
• Cria pagamento Pix (/payments).
• Retorna os dados do Pix (QRCode, payload e ID do pagamento) para o frontend.

3) CARTÃO – asaas/config/processa.php

• Recebe os campos do cartão via POST (holderName, number, expiryMonth, expiryYear, ccv).
• Cria cliente no Asaas (customers).
• Cria pagamento com billingType = CREDIT_CARD.
• Usa externalReference para amarrar a cobrança ao registro local.

4) BOLETO – asaas/config/processa_boleto.php

• Cria cliente no Asaas.
• Cria pagamento com billingType = BOLETO.
• Retorna URL/linha digitável para exibir para o cliente.

5) Status – asaas/status.php

• Consulta GET https://api.asaas.com/v3/payments/<id>.
• Retorna status (ex.: PENDING, RECEIVED, CONFIRMED etc.).
• É usado para “polling” (ficar verificando até aprovar).

6) Confirmação final – asaas/pagamento_aprovado.php

• Quando aprovado, a lógica do sistema costuma: confirmar agendamento, registrar pagamento e limpar temporário.
• O padrão do BarberBot é migrar agendamentos_temp → agendamentos e gravar ref_pix / valor pago.

💰 Checkout de CONTAS A RECEBER (asaas_contas/)

O módulo asaas_contas replica a estrutura, mas normalmente trabalha com:

• receber (tabela de contas) como base.
• Baixa via atualização de pago, data_pgto, pgto, ref_pix etc.

Pontos de manutenção

• Conferir se o externalReference usado na criação da cobrança identifica a conta local (id_ref).
• Na confirmação, garantir que não dá baixa duplicada (webhook/polling).

📆 Checkout de PLANOS/ASSINATURAS (asaas_planos/)

O módulo asaas_planos é voltado a planos/assinaturas. Ele normalmente:

• Associa pagamento a assinaturas (e/ou grupo/itens de assinatura).
• Confirma pagamento e atualiza vencimento/recorrência conforme regra do sistema.

Pontos de manutenção

• Quando aprovado, atualizar campos como pago, data_vencimento/vencimento e referência de pagamento.
• Evitar criar múltiplas cobranças para a mesma assinatura em “refresh” do usuário.

🗃️ Tabelas envolvidas (referência rápida)

🔐 Segurança e ajustes obrigatórios (sem frescura)

• CPF/email hardcoded: em processa.php existe CPF e e-mail fixos no código. Isso deve virar dado real do cliente ou cair para configuração.
• Token Asaas: não colocar token fixo em arquivo público. O padrão certo é vir da config do sistema (como já está).
• Dados de cartão: evitar logar POST de cartão em arquivo/erro. Nunca salvar número completo.
• Validação: conferir valor e referência no servidor antes de marcar como pago (não confiar no front).
• HTTPS: checkout tem que rodar em HTTPS para não vazar dados.

🧯 Troubleshooting rápido

• Erro ao criar cliente: conferir token em $asaas e se o servidor consegue acessar api.asaas.com.
• Pix não gera QR: conferir retorno do POST /payments e se o payload está sendo exibido no bloco Pix.
• Status não atualiza: checar se status.php está recebendo o ID do pagamento correto.
• Pagamento aprovado e não confirma: revisar pagamento_aprovado.php e a lógica de migração/baixa.