On this page

Guia de Integração Tajo-Brevo

Este guia completo orienta-o através da integração da sua plataforma de fidelidade Tajo com o Brevo para criar campanhas de envolvimento com clientes poderosas e automatizadas.

Visão Geral

A integração Tajo-Brevo permite-lhe:

  • Sincronizar dados de clientes em tempo real entre plataformas
  • Automatizar campanhas de fidelidade com base no comportamento do cliente
  • Rastrear envolvimento por e-mail, SMS e WhatsApp
  • Segmentar clientes por nível de fidelidade e comportamento de compra
  • Acionar mensagens personalizadas para eventos chave de fidelidade

Pré-requisitos

Antes de iniciar a integração, certifique-se de que tem:

  • Conta Tajo com programa de fidelidade configurado
  • Conta Brevo com acesso à API
  • Chaves de API válidas para ambas as plataformas
  • Endpoints de webhook configurados para sincronização em tempo real
  • Certificado SSL para transmissão segura de dados

Passo 1: Configuração de Autenticação

Gerar Chave de API Brevo

  1. Faça login na sua conta Brevo
  2. Aceda a Conta e Plano > Chaves de API
  3. Clique em Gerar uma nova chave de API
  4. Nomeie-a “Integração Tajo”
  5. Copie e guarde a chave em segurança
Terminal window
# Guardar em variáveis de ambiente
export BREVO_API_KEY="xkeysib-your-api-key-here"
export TAJO_WEBHOOK_SECRET="your-webhook-secret"

Configurar Integração Tajo

No seu painel Tajo:

  1. Aceda a Definições > Integrações
  2. Selecione Brevo da lista
  3. Introduza a sua chave de API Brevo
  4. Configure as definições de sincronização
{
  "brevo_api_key": "xkeysib-your-api-key-here",
  "sync_frequency": "real-time",
  "sync_contacts": true,
  "sync_orders": true,
  "sync_events": true,
  "loyalty_attributes": [
    "LOYALTY_POINTS",
    "LOYALTY_TIER",
    "TOTAL_SPENT",
    "LAST_PURCHASE"
  ]
}

Passo 2: Sincronização de Dados de Clientes

Configuração de Sincronização de Contactos

Configure a sincronização automática de contactos para manter os dados de clientes atualizados:

// Sincronizar cliente no registo
async function syncCustomerToBrevo(customer) {
  const brevoData = {
    email: customer.email,
    attributes: {
      FIRSTNAME: customer.firstName,
      LASTNAME: customer.lastName,
      PHONE: customer.phone,
      LOYALTY_ID: customer.loyaltyId,
      LOYALTY_POINTS: customer.points,
      LOYALTY_TIER: customer.tier,
      SIGNUP_DATE: customer.createdAt,
      TOTAL_SPENT: customer.totalSpent,
      PREFERRED_CATEGORIES: customer.categories,
      BIRTHDAY: customer.birthday
    },
    listIds: [getListForTier(customer.tier)]
  };


  const response = await fetch('https://api.brevo.com/v3/contacts', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'api-key': process.env.BREVO_API_KEY
    },
    body: JSON.stringify(brevoData)
  });


  return response.json();
}

Sincronização de Eventos de Compra

Sincronize compras automaticamente para acionar campanhas de fidelidade:

// Sincronizar conclusão de pedido
async function syncOrderToBrevo(order, customer) {
  // Criar pedido no Brevo
  const orderData = {
    id: order.id,
    email: customer.email,
    products: order.items.map(item => ({
      id: item.productId,
      name: item.name,
      quantity: item.quantity,
      price: item.price,
      category: item.category
    })),
    revenue: order.total,
    date: order.createdAt
  };


  await fetch('https://api.brevo.com/v3/ecommerce/orders', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'api-key': process.env.BREVO_API_KEY
    },
    body: JSON.stringify(orderData)
  });


  // Criar evento de fidelidade
  const eventData = {
    email: customer.email,
    event: 'Purchase Completed',
    properties: {
      order_id: order.id,
      amount: order.total,
      points_earned: order.pointsEarned,
      loyalty_tier: customer.tier,
      tier_upgraded: order.tierUpgraded,
      products: order.items.map(i => i.name).join(', ')
    }
  };


  await fetch('https://api.brevo.com/v3/events', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'api-key': process.env.BREVO_API_KEY
    },
    body: JSON.stringify(eventData)
  });
}

Passo 3: Configuração de Campanhas Automatizadas

Campanha de Boas-vindas para Novos Clientes

Crie uma série de boas-vindas automatizada para novos membros de fidelidade:

{
  "campaign_name": "Série de Boas-vindas Tajo Loyalty",
  "trigger": {
    "event": "Contact Created",
    "conditions": {
      "LOYALTY_ID": "exists",
      "SIGNUP_DATE": "today"
    }
  },
  "emails": [
    {
      "delay": "immediate",
      "template_id": 101,
      "subject": "Bem-vindo ao Tajo Loyalty! Aqui está o seu bónus de {{params.welcome_bonus}} pontos",
      "params": {
        "welcome_bonus": "500",
        "loyalty_tier": "Bronze",
        "next_tier_points": "1000"
      }
    },
    {
      "delay": "3 days",
      "template_id": 102,
      "subject": "Não se esqueça de usar os seus {{params.welcome_bonus}} pontos de bónus!"
    },
    {
      "delay": "1 week",
      "template_id": 103,
      "subject": "Eis como ganhar pontos mais rapidamente com o Tajo"
    }
  ]
}

Campanha de Upgrade de Nível

Celebre automaticamente upgrades de nível:

// Handler de webhook para upgrades de nível
app.post('/webhook/tier-upgrade', (req, res) => {
  const { customer, previousTier, newTier } = req.body;


  const campaignData = {
    email: customer.email,
    template_id: getTierUpgradeTemplate(newTier),
    params: {
      customer_name: customer.firstName,
      new_tier: newTier,
      previous_tier: previousTier,
      new_benefits: getTierBenefits(newTier),
      points_balance: customer.points
    }
  };


  // Enviar e-mail de parabéns
  sendBrevoEmail(campaignData);


  // Adicionar à lista específica do nível
  addToBrevoList(customer.email, getTierListId(newTier));


  res.status(200).json({ success: true });
});

Passo 4: Rastreamento de Eventos de Fidelidade

Eventos Chave a Rastrear

Configure o rastreamento para estes eventos essenciais de fidelidade:

const loyaltyEvents = {
  // Eventos de Conta
  'Account Created': {
    properties: ['signup_source', 'referral_code', 'welcome_bonus']
  },
  'Profile Updated': {
    properties: ['updated_fields', 'marketing_consent']
  },


  // Eventos de Compra
  'Purchase Completed': {
    properties: ['order_total', 'points_earned', 'loyalty_tier', 'products']
  },
  'Product Returned': {
    properties: ['return_reason', 'points_deducted', 'refund_amount']
  },


  // Eventos de Fidelidade
  'Points Earned': {
    properties: ['points_amount', 'earning_reason', 'total_balance']
  },
  'Points Redeemed': {
    properties: ['points_used', 'reward_type', 'remaining_balance']
  },
  'Tier Upgraded': {
    properties: ['previous_tier', 'new_tier', 'upgrade_benefits']
  },


  // Eventos de Envolvimento
  'Email Opened': {
    properties: ['campaign_type', 'subject_line', 'device']
  },
  'Reward Browsed': {
    properties: ['reward_category', 'reward_name', 'points_required']
  },
  'Referral Made': {
    properties: ['referral_method', 'referee_email', 'referral_bonus']
  }
};

Implementação de Rastreamento de Eventos 

class TajoBrevoEventTracker {
  constructor(apiKey) {
    this.apiKey = apiKey;
    this.baseUrl = 'https://api.brevo.com/v3';
  }


  async trackEvent(customerEmail, eventName, properties = {}) {
    const eventData = {
      email: customerEmail,
      event: eventName,
      properties: {
        timestamp: new Date().toISOString(),
        source: 'tajo_platform',
        ...properties
      }
    };


    try {
      const response = await fetch(`${this.baseUrl}/events`, {
        method: 'POST',
        headers: {
          'Content-Type': 'application/json',
          'api-key': this.apiKey
        },
        body: JSON.stringify(eventData)
      });


      if (!response.ok) {
        throw new Error(`Event tracking failed: ${response.statusText}`);
      }


      return await response.json();
    } catch (error) {
      console.error('Brevo event tracking error:', error);
      throw error;
    }
  }


  // Métodos de conveniência para eventos comuns
  async trackPurchase(customer, order) {
    return this.trackEvent(customer.email, 'Purchase Completed', {
      order_id: order.id,
      order_total: order.total,
      currency: order.currency,
      points_earned: order.pointsEarned,
      loyalty_tier: customer.tier,
      items_count: order.items.length,
      first_purchase: customer.orderCount === 1
    });
  }


  async trackTierUpgrade(customer, previousTier) {
    return this.trackEvent(customer.email, 'Tier Upgraded', {
      previous_tier: previousTier,
      new_tier: customer.tier,
      points_balance: customer.points,
      benefits_unlocked: getTierBenefits(customer.tier),
      upgrade_date: new Date().toISOString()
    });
  }
}

Passo 5: Estratégia de Segmentação

Segmentos de Clientes

Crie segmentos direcionados no Brevo para campanhas personalizadas:

const loyaltySegments = [
  // Segmentos baseados em nível
  {
    name: "Membros Bronze",
    conditions: { LOYALTY_TIER: "Bronze" },
    campaigns: ["tier_upgrade_promotion", "engagement_boost"]
  },
  {
    name: "Membros Silver",
    conditions: { LOYALTY_TIER: "Silver" },
    campaigns: ["premium_offers", "early_access"]
  },
  {
    name: "Membros Gold",
    conditions: { LOYALTY_TIER: "Gold" },
    campaigns: ["vip_treatment", "exclusive_rewards"]
  },
  {
    name: "Membros Platinum",
    conditions: { LOYALTY_TIER: "Platinum" },
    campaigns: ["luxury_experiences", "personal_offers"]
  },


  // Segmentos baseados em comportamento
  {
    name: "Grandes Gastadores",
    conditions: { TOTAL_SPENT: ">1000" },
    campaigns: ["luxury_catalog", "big_spender_rewards"]
  },
  {
    name: "Compradores Frequentes",
    conditions: { PURCHASE_FREQUENCY: "weekly" },
    campaigns: ["convenience_offers", "bulk_discounts"]
  },
  {
    name: "Clientes em Risco",
    conditions: { LAST_PURCHASE: ">90 days" },
    campaigns: ["win_back", "special_incentives"]
  },
  {
    name: "Mês de Aniversário",
    conditions: { BIRTHDAY: "this_month" },
    campaigns: ["birthday_specials", "bonus_points"]
  }
];

Passo 6: Testes e Monitorização

Lista de Verificação de Testes de Integração

  • Sincronização de Contactos: Novos clientes aparecem no Brevo
  • Sincronização de Pedidos: As compras acionam eventos corretamente
  • Rastreamento de Eventos: Todos os eventos de fidelidade são registados
  • Acionadores de Campanha: Os e-mails automatizados são enviados corretamente
  • Segmentação: Os clientes movem-se entre listas corretamente
  • Entrega de Webhook: A sincronização em tempo real funciona de forma fiável

Configuração de Monitorização 

// Endpoint de verificação de saúde
app.get('/integration/health', async (req, res) => {
  const checks = {
    brevo_api: await checkBrevoConnection(),
    webhook_delivery: await checkWebhookDelivery(),
    event_tracking: await checkEventTracking(),
    campaign_triggers: await checkCampaignTriggers()
  };


  const allHealthy = Object.values(checks).every(check => check.status === 'ok');


  res.status(allHealthy ? 200 : 503).json({
    status: allHealthy ? 'healthy' : 'degraded',
    checks,
    timestamp: new Date().toISOString()
  });
});

Resolução de Problemas Comuns

Limites de Taxa de API

O Brevo tem limites de taxa, implemente lógica de retry:

async function makeBrevoRequest(url, options, retries = 3) {
  try {
    const response = await fetch(url, options);


    if (response.status === 429) {
      const retryAfter = response.headers.get('Retry-After') || 60;
      await new Promise(resolve => setTimeout(resolve, retryAfter * 1000));
      return makeBrevoRequest(url, options, retries - 1);
    }


    return response;
  } catch (error) {
    if (retries > 0) {
      await new Promise(resolve => setTimeout(resolve, 5000));
      return makeBrevoRequest(url, options, retries - 1);
    }
    throw error;
  }
}

Problemas de Sincronização de Dados

Monitorize e resolva conflitos de sincronização:

// Resolução de conflitos de sincronização
async function resolveSyncConflict(tajoData, brevoData) {
  // Usar o timestamp mais recente como fonte de verdade
  const tajoUpdated = new Date(tajoData.updatedAt);
  const brevoUpdated = new Date(brevoData.modifiedAt);


  if (tajoUpdated > brevoUpdated) {
    // Atualizar Brevo com dados Tajo
    await updateBrevoContact(brevoData.id, tajoData);
  } else {
    // Atualizar Tajo com dados Brevo
    await updateTajoCustomer(tajoData.id, brevoData);
  }
}

Próximos Passos

  1. Configurar Webhooks para sincronização em tempo real
  2. Criar Templates de E-mail para campanhas de fidelidade
  3. Configurar Automação SMS para notificações urgentes
  4. Configurar Análise para monitorizar o desempenho

Suporte e Recursos

Assistente AI

Olá! Pergunte-me qualquer coisa sobre a documentação.

Comece grátis com Brevo