Geração de Cobrança
Como o Quaza cria boletos/PIX/débitos a partir dos contratos e vendas
A geração de cobrança é o processo que transforma serviços contratados (mensalidades, parcelas, vendas avulsas) em cobranças efetivas — boletos registrados, PIX dinâmicos, débito automático. Esta wiki cobre as 5 actions de geração, configurações por carteira, retentativas e troubleshooting.
Glossário
| Termo |
O que é |
| Cobrança |
Solicitação de pagamento — boleto, PIX, débito, cartão |
| Débito |
Registro interno do valor a receber (em financeiro) |
| Carteira |
Conjunto carteira-banco-gateway que define como cobrar (forma, encargos, layout) |
| Action |
Classe PHP que executa a geração (Action\Financeiro\Gerar*) |
Fluxo geral
📅 1. Origem (contrato/venda)
Sistema identifica o que cobrar: mensalidade do contrato, parcela de venda, taxa avulsa, etc.
↓
⚙️ 2. Action de geração
Uma das 5 actions roda: GerarCobranca, GerarDebitoDetalhe, GerarDebitoProporcional, GerarDebitosMensalidade, GerarVenda.
↓
💾 3. Cria débito
Registro inserido em financeiro com valor, vencimento, cliente, carteira, tipo.
↓
📡 4. Gera cobrança no provider
Se carteira tem gateway → API → boleto/PIX/cartão. Se CNAB → entra na próxima remessa.
↓
✅ 5. Cobrança disponível pro cliente
Email/WhatsApp/portal envia o link/PDF. Cliente paga → retorno baixa o débito automaticamente.
5 actions de geração
| Action |
Quando usar |
Origem típica |
| GerarCobranca |
Padrão — gerar cobrança avulsa |
Botão na tela de débito |
| GerarDebitoDetalhe |
Débito com detalhamento (itens) |
Vendas com produtos múltiplos |
| GerarDebitoProporcional |
Proporcional pra mudanças mid-cycle |
Cliente muda de plano no meio do mês |
| GerarDebitosMensalidade |
Lote mensal de mensalidades |
Tarefa diária |
| GerarVenda |
Venda de produto avulso |
POS/Loja |
Tela de Cobrança
Financeiro › Cobrança
Listagem de cobranças com filtros · botão de ação contextual.
Configuração da carteira
Configuração da carteira: define banco, gateway, encargos, layout CNAB se aplicável.
Cada carteira controla:
-
Banco/Gateway — provider de pagamento
-
Convênio — código no banco
-
Layout CNAB — 240/400/150/SIRO (se usa CNAB)
-
Forma de pagamento padrão — boleto/PIX/cartão/débito
-
Encargos — multa, juros, desconto antecipado
Encargos automáticos
| Encargo |
Campo |
Aplicado quando |
| Multa |
configValorMulta |
1º dia de atraso (% do valor) |
| Juros |
configValorJuros |
Por dia de atraso (% mensal / 30) |
| Desconto antecipado |
configValorDescontoAntecipado |
Pagamento antes do vencimento |
📌 Encargos são configurados na carteira mas podem ser sobrescritos por contrato (campos análogos no contrato).
Retentativas
Cada gateway suporta até 3 tentativas automáticas de geração. Se falhar 3x:
- Cobrança fica em estado de erro (visível na tela)
- Tarefa diária pode reentrar — depende do gateway
- Operador pode reentar manualmente via botão na cobrança
Pegadinhas
⚠️ 1. Carteira sem gateway gera só débito interno. Sem boleto/PIX. Confira a carteira do contrato antes de ativar.
⚠️ 2. Token gateway expirado. Algumas APIs (Asaas, Sicoob) usam token com validade. Quaza renova automaticamente em 3 tentativas; depois disso, gateway fica em erro.
🛑 3. Geração duplicada. Quaza protege contra rodar a mesma action 2x no mesmo débito — mas se houver erro intermediário, pode gerar 2 boletos. Confirme antes de processar manualmente.
💡 4. Encargos NÃO retroativos. Se você muda multa de 2% pra 5% hoje, débitos antigos mantêm 2%. Nova config aplica a NOVAS gerações.
FAQ
Posso gerar cobrança sem cliente?
Não — débito sempre tem cliente. Pra ajustes contábeis sem cliente, use Lançamento Manual.
Erro "Cobrança duplicada" — o que fazer?
Quaza detectou que esse débito já tem cobrança ativa no gateway. Confirme via Gateway Log antes de gerar nova.
Como gerar cobrança em lote?
Para mensalidades use a tarefa diária. Para outras, use Edição Múltipla na tela Cobrança e ação "Gerar cobrança".