Sistema de notificações de pagamento
TLDR: assumir do Asaas o envio de avisos de cobrança ao cliente e passar a enviá-los pelo
messenger-api, por email, WhatsApp ou SMS, habilitado por organização.
Contexto
Hoje dependemos do Asaas para notificar o cliente sobre pagamentos pendentes, lembretes, vencimentos e atrasos. Queremos assumir esse processo e usar o messenger-api como canal de envio.
O sistema de notificações depende fortemente da arquitetura descrita em ../architecture/event_streaming.md.
Objetivos
Habilitar notificações no nível da organização. Quando habilitadas, tratar as mensagens quando os callbacks forem disparados. As notificações a suportar:
- Nova solicitação de pagamento
- Alterações de valor e de vencimento do pagamento
- Lembrete de vencimento próximo (10 dias antes)
- Lembrete no dia do vencimento
- Lembrete quando o pagamento não é registrado
- Lembrete quando a cobrança do pagamento falha
- Lembrete após 7 dias sem registro de pagamento
- Agradecimento quando o pagamento é registrado
Todas as notificações são agendadas. Todos os lembretes são tratados por cronjobs, e cada job consulta o banco pelo critério correspondente e enfileira os jobs relevantes para processamento imediato.
Fora de escopo
- O campo de organização que indica se ela trata as próprias comunicações ainda não existe no momento em que esta spec foi escrita, e precisa ser criado.
Mudanças
Gatilhos por comunicação
| Comunicação | Gatilho | Conteúdo mínimo |
|---|---|---|
| Nova solicitação de pagamento | Webhook PAYMENT_CREATED; dispara o evento interno payment_created |
Valor, vencimento e link de pagamento |
| Alteração de valor ou vencimento | Webhook PAYMENT_UPDATED; dispara o evento interno payment_changed |
Valor, vencimento e link atualizado |
| Lembrete de vencimento próximo | 10 dias antes do vencimento (hardcoded por ora) | Valor, vencimento e link |
| Lembrete no dia do vencimento | Na data de vencimento | Valor, vencimento e link, com destaque visual maior |
| Pagamento não registrado (3 dias após o vencimento) | Sem confirmação após 3 dias do vencimento | Valor, vencimento, link, consequências de não pagar e botão de contato com o suporte |
| Cobrança falhou | Webhook PAYMENT_REPROVED_BY_RISK_ANALYSIS; dispara o evento interno payment_declined |
Valor, vencimento e link para nova tentativa |
| Pagamento não registrado (após 7 dias) | Sem confirmação após 7 dias | Mesmo conteúdo do lembrete de 3 dias |
| Agradecimento | Webhook PAYMENT_CONFIRMED ou PAYMENT_RECEIVED; dispara o evento interno payment_confirmed |
Valor pago e mensagem de agradecimento |
O agradecimento é enviado apenas na primeira ocorrência de qualquer um dos dois eventos num mesmo pagamento, para evitar mensagem duplicada.
Todas as notificações só são enviadas se a organização estiver configurada para tratar as comunicações.
Templates
Os templates de email ficam armazenados no messenger-api. Quando uma mensagem de email é disparada, a aplicação seleciona o template correto, prepara a mensagem e envia ao cliente. O conteúdo de SMS e WhatsApp é fornecido pelo ibft-api.
Como verificar
Os jobs de notificação devem ser testados com testes unitários no nível de ActiveJob. Incluir também testes de enfileiramento dos jobs quando uma solicitação de pagamento é registrada.
Documentação
Não implementado. Não há integração com messenger-api no código, nem o campo de organização que habilita as comunicações.
- Arquitetura de que este sistema depende: ../architecture/event_streaming.md
- Eventos de notificação do Asaas: https://docs.asaas.com/docs/default-notifications
- Eventos de webhook do Asaas: https://docs.asaas.com/docs/payment-events