Introdução
Onboardar comerciantes significa mais do que preencher um formulário: é preciso disponibilizar produtos, configurar o rastreio, validar conversões e definir regras de comissões. O Affilentra liga estes passos numa ambiente self‑hosted, onde operadores, comerciantes e parceiros têm papéis separados. Este artigo mostra concretamente como configurar webhooks, regras de validação e pedidos de teste automatizados no Affilentra (PRO & NETWORK) para que comerciantes sejam integrados na sua rede de parceiros de forma rápida, segura e sem erros.
Por que um onboarding controlado por webhook?
Webhooks permitem integrar sistemas externos (loja, ERP, provedor de pagamentos) orientados a eventos no Affilentra. Em vez de entradas manuais ou importações agendadas, reage‑se imediatamente a eventos relevantes como a criação de um comerciante, atualizações de produto ou eventos de encomenda. Combinado com validações automatizadas e pedidos de teste, isto reduz a taxa de erro, encurta os tempos de processamento e aumenta a rastreabilidade para comerciantes e parceiros.
Passos preparatórios (lista de verificação antes da implementação técnica)
- Instalar uma instância Affilentra self‑hosted (PRO ou NETWORK).
- Assegurar: HTTPS, acesso para operadores de software e administradores, ambiente PHP/MySQL atualizado.
- Clarificar as informações de comerciante disponíveis: URL da loja, acesso à API, catálogo de produtos, modelos de comissão desejados.
- Definir quais eventos devem disparar webhooks (p.ex. merchant.created, product.updated, order.created, order.status_changed).
- Esboçar papéis e permissões: que ações comerciantes, parceiros e operadores podem executar.
Configuração de webhooks no Affilentra
O Affilentra oferece, nas edições PRO & NETWORK, a possibilidade de configurar webhooks para eventos globais e específicos de comerciante. Proceda da seguinte forma:
- Criar endpoint de webhook: No painel de administração, registe um novo webhook e informe a URL de destino do sistema externo.
- Seleção de eventos: Escolha os eventos de forma dirigida, p.ex. merchant.created, merchant.updated, product.synced, order.created. Limite a seleção ao necessário para reduzir o tráfego.
- Configurar segurança: Ative assinaturas HMAC com um secret partilhado. O Affilentra assina os payloads, e os sistemas externos verificam a assinatura antes do processamento.
- Estratégia de retry: Defina o número de tentativas de reenvio e a estratégia de backoff, para que falhas temporárias não causem perda de dados.
- Idempotência: Utilize IDs de evento únicos no payload, para que os receptores reconheçam repetições e evitem processamentos duplicados.
Notas práticas
Documente a estrutura de payload esperada para a sua equipa de loja ou ERP. Campos comuns são merchant_id, shop_url, products (com SKU, preço, disponibilidade) e signatur_meta. Nomes de campos claros e tipos de dados reduzem esforço de alinhamento.
Regras de validação: configurar regras de campo e de negócio
As regras de validação protegem a sua rede contra dados incorretos ou incompletos. A Affilentra permite verificações configuráveis em vários níveis:
- Checks de esquema: campos obrigatórios, tipos de dados e limites de comprimento (p. ex. shop_url deve ser HTTPS válido, SKU não pode estar vazio).
- Regras de negócio: Exemplo: tipos de comissão devem corresponder aos produtos, métodos de pagamento escolhidos devem estar ativados para o comerciante.
- Validação dependente do contexto: Regras que se aplicam apenas a certas categorias de comerciantes ou mercados (p. ex. valor mínimo de conversão para programas de parceiro específicos).
Implemente validações como parte do processo de processamento de webhooks. Em entradas com erros, a Affilentra envia automaticamente um feedback aos sistemas de origem (Webhook‑Response) e regista a mensagem de erro na interface de utilizador para operadores e comerciantes.
Encomendas de teste automatizadas: validar o tracking e a lógica de comissões
As encomendas de teste são centrais para verificar caminhos de tracking e cálculos de comissão antes do comerciante entrar em produção. Deve implementar encomendas de teste na Affilentra da seguinte forma:
- Ativar modo de teste: Defina para o comerciante um estado de teste, em que as encomendas são marcadas como teste e não geram pagamentos reais.
- Payloads de simulação: Crie ordens de teste standardizadas que cubram vários cenários: conversão bem‑sucedida, cancelamento, reembolso parcial, chargeback.
- Disparo automatizado: Triggerize encomendas de teste via webhook da loja ou através da API da Affilentra. As encomendas de teste devem conter os mesmos parâmetros de tracking que as encomendas live (p. ex. affiliate_id, campaign_id, click_id).
- Relato e rastreio: As encomendas de teste aparecem no histórico de encomendas incluindo estado de validação e cálculo de comissão, para que comerciantes e operadores possam identificar discrepâncias.
Implemente um fluxo de teste curto: enviar encomenda de teste → verificar a validação → controlar o cálculo da comissão → reiniciar a encomenda de teste ou promovê‑la para live, se tudo estiver correto.
Mapeamento de funções e permissões
Um elemento central no onboarding é a clara separação de funções. A Affilentra distingue operadores de software, comerciantes e parceiros. Configure as funções da seguinte forma:
- Operador do software: Acesso total à configuração do sistema, gestão de webhooks, administração de licenças e regras globais de validação.
- Comerciante: Controlo sobre produtos, preços, materiais promocionais, condições e webhooks específicos do comerciante; visualização das faturas de comissões para os seus próprios programas.
- Parceiro (Publisher/Creator): Links de tracking pessoais, histórico transparente de conversões e pagamentos, acesso a materiais promocionais.
As regras de mapeamento definem quais permissões padrão um comerciante recém-criado recebe. No PRO & NETWORK pode criar modelos que são atribuídos automaticamente juntamente com eventos de webhook (por exemplo, categoria de comerciante A → determinado modelo de comissões + acesso API limitado).
Pipeline de Onboarding de ponta a ponta: Exemplo de fluxo
Um fluxo típico e automatizado com a Affilentra apresenta-se assim:
- A loja envia merchant.created → Affilentra cria o comerciante e verifica os dados básicos (verificações de esquema).
- A Affilentra desencadeia merchant.validation_failed/merchant.validation_passed para o sistema da loja e para o operador.
- Se o check for aprovado, são iniciadas sincronizações de produtos via product.synced; regras de validação para produtos são executadas.
- Pedidos de teste são gerados automaticamente (order.created com test_flag); o tracking e a lógica de comissões são verificados.
- Após o teste bem-sucedido, o comerciante obtém o estado Live; os parceiros recebem links de tracking personalizados e podem iniciar campanhas.
Monitorização, logs e tratamento de erros
Utilize o registo de eventos na Affilentra: eventos de webhook, erros de validação e pedidos de teste devem ser visíveis no painel. Defina regras de alerta para erros recorrentes (por exemplo, sincronizações de produto falhadas) e estabeleça regras de escalonamento para o operador.
Exemplo prático: Arranque rápido para um novo comerciante
Fluxo concreto em poucos passos:
- Enviar dados do comerciante via webhook merchant.created para a Affilentra.
- A Affilentra valida os campos obrigatórios; em caso de dados em falta, a API da loja recebe um objeto de erro detalhado em retorno.
- Após verificações bem-sucedidas, os dados de produtos são sincronizados e é gerada automaticamente uma série de pedidos de teste.
- Os resultados dos testes são apresentados no portal do comerciante; o operador verifica a aprovação e coloca o comerciante em Live.
- Os parceiros recebem automaticamente links de tracking para o novo programa do comerciante e veem conversões de teste e Live no seu histórico.
Conclusão e recomendações de ação
O onboarding orientado por webhook reduz passos manuais e permite processos transparentes e reproduzíveis. Com Affilentra, garante-se que regras de validação e encomendas de teste façam parte integrante do onboarding — e que as funções fiquem claramente separadas. Na prática, isto significa: menos lançamentos incorretos, tempo de colocação no mercado mais rápido e pagamentos auditáveis para todas as partes envolvidas.
Próximo passo: Verifique a sua lista de verificação de onboarding, defina os eventos de webhook necessários e crie encomendas de teste standardizadas. Se pretende usar Affilentra, escolha o ponto de entrada adequado para a sua organização.
Próximo passo
Experimentar o Affilentra
Plataforma unificada que integra de forma transparente a disponibilização de produtos, tracking, validação de conversões, cálculo de comissões e pagamentos ao longo de funções claramente separadas; 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 auditável.