Quando a fatura está vencida e ninguém acompanha
Uma fatura está em atraso, não há resposta na caixa de entrada e a contabilidade perde tempo com atribuições manuais. É precisamente aqui que um enfoque orientado por eventos entra: webhooks notificam em tempo real quando um pagamento é recebido, quando um nível de cobrança muda ou quando é registado um pagamento parcial. O Debentra disponibiliza esses eventos na sua própria infraestrutura e possibilita assim processos automatizados e controlados no ERP, no sistema de ticketing e na monitorização.
Por que Webhooks para a gestão de clientes devedores?
Polling gera atrasos e trabalho extra. Webhooks enviam eventos imediatamente para os seus sistemas, reduzem passos manuais e garantem documentação consistente na sua infraestrutura. Importante: com o Debentra o controlo permanece com o utilizador – em especial na autorização de lembretes de pagamento.
Como o Debentra entrega Webhooks (Visão geral)
O Debentra envia pedidos HTTP(S) POST em eventos definidos: payment.received, invoice.reminder_level_changed, payment.partial_received, entre outros. As cargas (payloads) contêm campos estruturados como invoice_id, customer_id, amount, paid_amount, due_date e um event_type. Através de um mapeamento claro destes campos no ERP ou no ticketing é possível controlar fluxos de trabalho automáticos.
Três cenários típicos de integração
1) Recebimento de pagamento: lançamento direto e fechamento de ticket
Cenário: Um pagamento foi creditado na conta. O ERP deve compensar automaticamente o lançamento em aberto e fechar um ticket de suporte aberto.
Exemplo de payload (exemplo para o sistema receptor):
{ "event_type": "payment.received", "timestamp": "2026-10-27T09:32:15Z", "invoice_id": "INV-2026-00042", "customer_id": "CUST-1001", "amount_due": 1200.00, "paid_amount": 1200.00, "currency": "EUR", "payment_reference": "SEPA-TRX-12345" }
Mapeamento recomendado:
- invoice_id → ERP.invoice.number
- customer_id → ERP.customer.accountId
- paid_amount → ERP.payments.amount
- payment_reference → ERP.payments.reference
- timestamp → ERP.payments.date
Reação típica:
- ERP: Atribuição automática e compensação do lançamento em aberto; gerar comprovativo de pagamento.
- Ticketing: Se existir um ticket de cobrança aberto, fechar automaticamente o ticket com o comentário "Pagamento recebido".
- Monitorização: Incrementar a métrica "recebimentos diários de pagamentos".
2) Mudança de nível de cobrança: libertação de modelos de lembrete e escalonamento
Cenário: Uma fatura atinge o nível de cobrança 2. A gestão de cobranças deve preparar um lembrete, mas entregá‑lo primeiro como rascunho num ticket para controlo.
Exemplo de payload:
{ "event_type": "invoice.reminder_level_changed", "timestamp": "2026-10-27T10:05:00Z", "invoice_id": "INV-2026-00037", "customer_id": "CUST-1260", "old_level": 1, "new_level": 2, "due_date": "2026-10-01" }
Mapeamento recomendado:
- invoice_id → Ticket.subject (por ex.: "Nível de aviso 2: INV-2026-00037")
- new_level → Ticket.priority ou etiqueta (por ex.: "aviso:nivel2")
- due_date → Ticket.due_date
Reação típica:
- Ticketing: Criar ticket de rascunho com modelo de lembrete e contexto; atribuir ao responsável para aprovação.
- ERP/Finanças: Marcar o item para acompanhamento reforçado; gerar um cálculo de custos de cobrança como anexo.
- Monitorização: Incrementar contador para avisos abertos >1, para rastrear tendências de escalonamento.
Importante: Apesar da automação, a decisão de aprovação permanece com o utilizador — o lembrete só é enviado após confirmação manual.
3) Pagamento parcial / Plano de prestações: Extrato e gestão de parcelas
Cenário: Um cliente efetua um pagamento parcial. Os planos de prestações no ERP têm de ser atualizados e os saldos em aberto acompanhados.
Exemplo de payload:
{ "event_type": "payment.partial_received", "timestamp": "2026-10-27T11:20:40Z", "invoice_id": "INV-2026-00081", "customer_id": "CUST-3007", "paid_amount": 400.00, "remaining_amount": 800.00, "installment_plan": { "plan_id": "PLAN-9001", "next_due": "2026-11-27", "installment_amount": 400.00 } }
Mapeamento recomendado:
- paid_amount → ERP.accounting.partialPayments[]
- remaining_amount → ERP.openItems.amount
- installment_plan.plan_id → ERP.customFields.ratenplanId
- installment_plan.next_due → ERP.customFields.nextInstallmentDate
Reação típica:
- ERP: Atualizar plano de prestações, criar lançamentos subsequentes e lembrete de prazo.
- Ticketing: Acrescentar comentário ao processo original com o estado do pagamento.
- Monitorização: Gerar alerta se as prestações acordadas não forem cumpridas dentro do prazo.
Estratégias de segurança e de retry para deployments on‑prem
On‑prem significa controlo total sobre a superfície de ataque e o comportamento de retry. Medidas recomendadas:
- Criptografia de transporte: Receba webhooks apenas via HTTPS.
- Autenticação & Assinatura: Assine payloads com HMAC (p. ex. SHA256) e verifique a assinatura no servidor. Exemplo de cabeçalho HTTP: X-Debentra-Signature: sha256=....
- Certificados de cliente e lista de permissões por IP: Opcional para proteção adicional entre o Debentra e os seus endpoints.
- Idempotência: Cada payload inclui um event_id ou webhook_id único. Processe eventos de forma idempotente para evitar ações duplicadas.
- Estratégia de retentativa: Implemente backoff exponencial (p. ex. 1min, 5min, 20min, 1h) e limite o número de tentativas. Após X tentativas de entrega com falha: Dead‑letter Queue e alerta para operações.
- Quarentena & Revisão manual: Em caso de mapeamentos com erro, categorização automática em uma fila manual em vez de escalonamento direto.
- Logging & trilha de auditoria: Armazenar logs completos dos payloads recebidos, verificação de assinatura, status de processamento e intervenções manuais.
Boas práticas para mapeamento de campos e convenções de nomenclatura
Um mapeamento consistente evita mal-entendidos ao processar eventos. Sugestões:
- Use chaves únicas e imutáveis: invoice_id, customer_id, event_id.
- Utilize valores de status claros: "open", "partial", "paid", "overdue" em vez de textos livres.
- Mantenha campos de valor como números decimais com indicação de moeda: amount: 1234.56, currency: "EUR".
- Inclua um campo human_readable_note que contenha observações contextuais curtas (não como substituto de campos estruturados).
- Documente o mapeamento no wiki interno, incluindo exemplos e códigos de resposta esperados.
Plano de implementação em cinco passos
- Defina os events: inicialmente escolha payment.received, invoice.reminder_level_changed e payment.partial_received.
- Crie endpoints: listeners HTTPS no ERP/Ticketing com verificação HMAC e lógica idempotente.
- Implemente e teste os mapeamentos de payload em um ambiente de staging.
- Rollout com monitoramento: ative mecanismos de retentativa, Dead‑letter‑Queue e alertas para falhas de entrega.
- Operacionalize: revisão regular de logs, ajuste de mapeamentos/regras e treinamento dos responsáveis pela rotina de liberação.
Exemplo curto: Como manter o controlo
Defina em Debentra a regra "reminder.auto_send = false" e configure eventos de webhook para que, na alteração do nível de cobrança, seja criado um ticket com um rascunho. O responsável verifica o modelo, confirma o envio no ticket e assim dispara uma segunda ação API. Assim a automação fica eficiente, mas a responsabilidade de aprovação permanece com o utilizador.
Conclusão
Os webhooks tornam a monitorização de vencimentos e o acompanhamento de faturas eficientes — desde que defina um mapeamento claro, transmissão segura e mecanismos de retry robustos. O Debentra fornece os eventos on‑prem, a sua infraestrutura gere as escriturizações no ERP, os fluxos de tickets e os sinais de monitorização. Um rollout direcionado reduz tarefas manuais sem abdicar do controlo sobre o envio de cobranças ou lançamentos contabilísticos.
Aja agora: Escolha a edição adequada para ativar ferramentas de integração e funcionalidades de automatização. Escolher edição: https://debentra.de
Próximo passo
Experimentar o Debentra
Visão central e controlo de processos para contas a receber e pagamentos com total soberania dos dados; reduz o trabalho manual de reconciliação (PRO) e permite contabilidade integrada (PREMIUM); modelos de instalação e licenciamento à escolha.