Introdução
Webhooks são a espinha dorsal das integrações modernas: impulsionam a automatização em tempo real, reduzem o trabalho manual e melhoram a transparência entre comerciantes, parceiros e sistemas de faturação. Para operadores de programas de afiliados, a sincronização fiável de eventos de conversão, preparação de pagamentos e execução de pagamentos é especialmente crítica. Este artigo mostra fluxos de trabalho práticos de Webhook com Affilentra — incluindo modelos de payload e notas de integração para sistemas contabilísticos, fornecedores de pagamento e sistemas ERP internos.
Por que Webhooks com Affilentra?
A Affilentra fornece uma plataforma de afiliados self-hosted com papéis claramente separados (operador de software, comerciante, parceiro). Os Webhooks permitem aqui entregar automaticamente eventos do programa de parceiros a sistemas externos: conversões validadas, listas de pagamentos preparadas e atualizações de estado. Através da arquitetura self-hosted, os comerciantes mantêm a soberania dos dados e podem operar endpoints de Webhook por conta própria ou integrá‑los na middleware existente.
Tipos de evento essenciais e a sua utilização
Os seguintes eventos formam a base para fluxos de trabalho práticos:
- conversion.created – um evento de tracking foi registado e validado.
- conversion.updated – alterações de estado (por exemplo, chargeback, reembolso, conversão confirmada).
- payout.prepared – uma lista de pagamento ou um registo de pagamento foi criado para faturação.
- payout.paid – o pagamento foi transmitido ao fornecedor de pagamento ou marcado como pago.
- accounting.export_ready – dados relevantes para a contabilidade estão prontos para exportação (por exemplo, como lançamentos contabilísticos ou CSV).
- erp.update_required – alteração de estado que deve ser refletida no ERP interno (por exemplo, estado de fulfillment ou fatura).
Modelos de payload (Exemplos)
Os seguintes payloads servem como modelos para integração. Ajuste os campos ao seu esquema interno e processe apenas os campos de que necessitar.
conversion.created (Exemplo)
{
"event": "conversion.created",
"timestamp": "2026-11-04T10:15:30Z",
"conversion": {
"id": "conv_12345",
"merchant_id": "m_987",
"partner_id": "p_456",
"offer_id": "o_22",
"amount": 149.90,
"currency": "EUR",
"status": "pending_validation",
"meta": { "order_ref": "ORD-20261104-001" }
}
}
payout.prepared (Exemplo)
{
"event": "payout.prepared",
"timestamp": "2026-11-04T11:00:00Z",
"payout": {
"id": "po_20261104_01",
"merchant_id": "m_987",
"partner_id": "p_456",
"gross_amount": 320.00,
"fees": 5.00,
"net_amount": 315.00,
"currency": "EUR",
"payout_method": "bank_transfer",
"batch_id": "batch_20261104",
"entries": [ { "conversion_id": "conv_12345", "amount": 120.00 }, { "conversion_id": "conv_12346", "amount": 200.00 } ]
}
}
payout.paid (Exemplo)
{
"event": "payout.paid",
"timestamp": "2026-11-04T12:30:00Z",
"payout": {
"id": "po_20261104_01",
"paid_at": "2026-11-04T12:28:00Z",
"transaction_id": "txn_7890",
"provider_status": "settled"
}
}
accounting.export_ready (Exemplo)
{
"event": "accounting.export_ready",
"timestamp": "2026-11-04T12:35:00Z",
"export": {
"id": "exp_20261104_01",
"format": "csv",
"records": [ { "account_code": "8400", "debit": 0, "credit": 315.00, "description": "Affiliate Payout" } ]
}
}
Fluxos de integração típicos
1) Conversão → Preparação contabilística
Fluxo: conversion.created → conversion.updated (confirmado) → accounting.export_ready.
- Em conversion.created: Armazene um registo mínimo na middleware, execute validações (por ex. duplicados, referências CVR/encomenda).
- Em conversion.updated com estado confirmed: Gere um lançamento contabilístico (devedores, receitas, IVA) ou marque a conversão para inclusão na próxima exportação.
- Em accounting.export_ready: Gere CSV/DATEV/JSON e coloque-o no diretório contabilístico ou envie-o por SFTP ao seu contabilista.
2) Preparação de pagamento → Provedor de pagamentos
Fluxo: payout.prepared → API do provedor de pagamentos → payout.paid.
- payout.prepared: Gere um lote com entradas de payout, verifique limites e disponibilidade (saldo, estado KYC).
- Envie o lote ao seu provedor de pagamentos; use chamadas idempotentes e forneça batch_id como referência.
- Receba a resposta do provedor, marque as transações e aguarde o evento payout.paid para a contabilização final.
3) Sincronização ERP para fulfillment e estado de faturas
Fluxo: conversion.updated / erp.update_required → API do ERP.
- Em alterações de estado (por ex. fulfilled, refunded) a Affilentra envia um evento erp.update_required.
- Mapeamento: external_reference → número de encomenda do ERP; atualize o estado de fulfillment, números de fatura e estado do pagamento.
- Boas práticas: Utilize acknowledgement por lote, limitação de taxa e verifique referências quanto à unicidade.
Boas práticas para integrações robustas
- Segurança: Assine cargas úteis de Webhook com HMAC (SHA256) e verifique timestamps para impedir ataques de replay.
- Idempotência: Processe a mesma Event‑ID várias vezes sem efeitos secundários. Utilize chaves de idempotência dedicadas.
- Gestão de erros: Implemente lógica de retry com Exponential Backoff; registe entregas falhadas centralmente.
- Versionamento: Introduza um campo de versão do esquema de eventos para manter compatibilidade nas alterações de esquema.
- Batching: Envie eventos agregados para contabilidade e pagamentos (p.ex. batch_id) para reduzir esforço e latência.
- Minimização de dados: Envie apenas os campos que os sistemas de destino precisam; armazene metadados adicionais de forma opcional.
- Monitorização: Monitorize taxas de entrega, latência e taxa de erro; notifique os responsáveis em caso de falhas.
Observações por função
- Comerciante (Merchant): Defina endpoints de Webhook, escolha eventos e determine métodos de pagamento. O self‑hosting permite controlo total sobre os fluxos de dados.
- Parceiro (Publisher): Beneficie de links de tracking auditáveis e de estados de pagamento transparentes, que podem ser enviados por Webhooks para painéis ou ferramentas contabilísticas.
- Operador de software: Forneça assinaturas seguras, documentação e monitorização; ofereça modelos e exemplos de mapeamento para fornecedores contabilísticos e de pagamentos comuns.
Exemplos práticos: passos de implementação
- Defina os eventos relevantes e um conjunto mínimo de campos necessários (p.ex. conversion_id, amount, currency).
- Configure uma middleware ou um pequeno serviço receptor que valide Webhooks, deduplique e roteie para sistemas de destino.
- Implemente assinaturas HMAC e verifique timestamps dentro de uma janela curta (p.ex. 5 minutos).
- Teste com eventos simulados: conversion.created → payout.prepared → payout.paid → accounting.export_ready.
- Documente códigos de erro e processos de recuperação para as suas equipas de Finanças e Operações.
Conclusão e próximo passo
Com Affilentra é possível representar fluxos de Webhook para tracking de conversões, preparação de pagamentos e exportações contabilísticas de forma prática e segura — especialmente em cenários self‑hosted, onde o controlo e a privacidade dos dados são centrais. A combinação de esquemas de eventos claros, processamento idempotente e lotes de pagamento controlados reduz trabalho manual e aumenta a transparência para comerciantes e parceiros.
Pronto para usar Webhooks em produção? Escolher início
Próximo passo
Experimentar o Affilentra
Plataforma unificada que reúne de forma transparente a disponibilização de produtos, o rastreio, a validação de conversões, o cálculo de comissões e os pagamentos com papéis claramente separados; opção de instalação self-hosted com licença perpétua sem participação nas receitas; os comerciantes mantêm o controlo sobre produtos, condições e materiais promocionais; os parceiros recebem links de tracking pessoais e um histórico de pagamentos rastreável.