Documentação Técnica - Integrações Asaas do BarberBot

3

Pastas auditadas

35

Arquivos PHP no recorte

3

Checkouts principais

0

Lacunas no recorte

Como o recorte está dividido

Os três módulos usam a mesma espinha dorsal, mas cada um nasce de uma origem de negócio diferente.

/asaas

Checkout de agendamento online

13 PHP

Fluxo público que parte de agendamentos temporários, gera cobrança no Asaas, consulta status e, quando aprovada, consolida o agendamento no núcleo do sistema.

agendamentos_temp agendamentos servicos clientes receber

GET: id_conta, total
REQUEST: ref, sobrenome, gerarDireto
POST: dados de cartão / endereço

/asaas_contas

Checkout de contas a receber

11 PHP

Fluxo dedicado a contas avulsas do financeiro. Usa a tabela receber como origem da cobrança e terceiriza a baixa financeira para a pasta /pagamentos.

receber clientes

GET: id_conta
REQUEST: ref, sobrenome, gerarDireto
POST: dados de cartão / endereço

/asaas_planos

Checkout de planos e assinaturas

11 PHP

Fluxo voltado a planos/assinaturas. Após a confirmação, delega a aprovação do plano para o próprio painel administrativo.

assinaturas itens_assinaturas clientes

GET: id_conta
REQUEST: ref, sobrenome, gerarDireto
POST: dados de cartão / endereço

Estrutura comum dos três módulos

Mesmo mudando a origem da cobrança, a topologia se repete. Isso ajuda a localizar rápido onde fica cada responsabilidade.

index.php

Tela inicial do checkout. Consulta o registro-base, monta resumo de cobrança e inclui os blocos de pagamento Pix, cartão e boleto.

status.php

Consulta o status da cobrança no Asaas e decide se precisa refletir o pagamento no núcleo do sistema.

obrigado.php

Tela final de retorno visual para o usuário após o fluxo de pagamento.

api-texto.php

Helper de mensageria usado por alguns fluxos para disparo de texto/notificação.

config/configApi.php

Centraliza token e diretório base do checkout. É ponto crítico porque influencia retorno, links e polling.

config/gerar_pix.php

Cria cobrança Pix no Asaas a partir do registro-base do módulo.

config/processa.php

Processa cartão de crédito com dados do formulário e integra com a API do Asaas.

config/processa_boleto.php

Processa boleto com dados do formulário e integra com a API do Asaas.

config/blocos/pix.php

Render parcial do bloco visual de Pix no checkout.

config/blocos/cartao.php

Render parcial do formulário de cartão.

config/blocos/boleto.php

Render parcial do formulário de boleto.

Diferenças que importam na depuração

Nem tudo termina dentro da própria pasta. Em alguns fluxos, o efeito final acontece em outras áreas do sistema.

Arquivos especiais de /asaas

asaas/pagamento_aprovado.php Consolida o agendamento: insere em agendamentos, cria receber quando necessário, aciona mensageria e limpa o temporário.
asaas/confirmacao.php Auxiliar de confirmação do fluxo de agendamento.

Integrações reaproveitadas por /asaas_contas

asaas_contas/status.php Quando a cobrança é confirmada, delega a baixa para ../pagamentos/baixar_conta.php em vez de ter um aprovador local.

Integrações reaproveitadas por /asaas_planos

asaas_planos/status.php Quando a cobrança é confirmada, delega a aprovação para ../sistema/painel/paginas/planos/aprovar_plano.php.

Achados reais do código

Esses pontos vieram da leitura do projeto real e merecem ficar visíveis para o próximo dev.

Achado real 1 — host_dir repetido

Nos arquivos config/configApi.php de asaas_contas e asaas_planos, o host_dir continua apontando para /asaas/. Isso pode desalinhar retorno, links ou polling se o código usar esse valor para construir URLs.

Achado real 2 — redirect inconsistente em contas

Em asaas_contas/status.php o redirecionamento final aponta para asaas_planos/obrigado.php. Para manutenção, isso merece revisão porque o contexto correto da cobrança é conta a receber.

Achado real 3 — forte acoplamento externo

asaas_contas/status.php depende de /pagamentos/baixar_conta.php e asaas_planos/status.php depende de /sistema/painel/paginas/planos/aprovar_plano.php. Quem depura o fluxo precisa seguir a chamada além da pasta atual.

Pontos fortes do desenho atual

Os três checkouts repetem uma estrutura consistente, o que facilita localizar index.php, status.php e a pasta config em qualquer módulo.
A separação por contexto de negócio ajuda: agendamento, contas a receber e planos não se misturam na origem do dado.
Os blocos de pagamento Pix, cartão e boleto ficam isolados em config/blocos, reduzindo acoplamento visual com a tela principal.

Pontos que exigem atenção de manutenção

Há consultas SQL interpoladas em partes do fluxo, principalmente nos arquivos index.php, status.php e pagamento_aprovado.php do checkout de agendamento.
Os três módulos compartilham padrão visual, mas não compartilham uma camada única de serviço; qualquer ajuste de API precisa ser replicado nas três árvores.
Existem dependências cruzadas com /pagamentos e com o painel, então um bug no checkout pode ter origem fora da pasta atual.

Leitura rápida de fluxo

Quando o bug vier de cobrança Asaas, esta é a ordem mais segura para percorrer os arquivos.

1.Entrar por index.php e validar o registro-base.

2.Confirmar o arquivo de criação da cobrança em config/gerar_pix.php, processa.php ou processa_boleto.php.

3.Seguir o polling em status.php e ver se a API retornou RECEIVED ou CONFIRMED.

4.Se houver confirmação, seguir a chamada externa: pagamento_aprovado.php, ../pagamentos/baixar_conta.php ou aprovar_plano.php.

5.Validar o retorno visual em obrigado.php e o redirecionamento final.