On this page

Guia de Integração Magento / Adobe Commerce

Este guia explica como integrar o Tajo com Magento Open Source ou Adobe Commerce para desbloquear capacidades de envolvimento com clientes, programas de fidelidade e automação de marketing.

Visão Geral

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

  • Sincronizar dados de clientes automaticamente da sua loja Magento
  • Rastrear pedidos e produtos para marketing personalizado
  • Executar programas de fidelidade com pontos, níveis e recompensas
  • Automatizar campanhas de marketing via Brevo (e-mail, SMS, WhatsApp)
  • Suportar configurações multi-site e multi-loja
  • Gerir catálogos de produtos complexos com produtos configuráveis

Pré-requisitos

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

  • Magento 2.4+ ou Adobe Commerce (Cloud ou On-Premise)
  • Conta Tajo com uma subscrição ativa
  • Conta Brevo (opcional, para automação de marketing)
  • Acesso de administrador à sua instância Magento
  • Composer para gestão de dependências
  • PHP 8.1+ com as extensões necessárias

Passo 1: Instalar a Extensão Tajo

Via Composer (Recomendado)

Terminal window
# Adicionar repositório Tajo
composer config repositories.tajo composer https://packages.tajo.io


# Instalar a extensão
composer require tajo/module-magento:^2.0


# Ativar o módulo
bin/magento module:enable Tajo_Core Tajo_Sync Tajo_Loyalty


# Executar configuração
bin/magento setup:upgrade
bin/magento setup:di:compile
bin/magento cache:flush

Instalação Manual

Terminal window
# Descarregar e extrair para app/code
mkdir -p app/code/Tajo
cd app/code/Tajo
wget https://downloads.tajo.io/magento/tajo-magento-latest.zip
unzip tajo-magento-latest.zip


# Ativar e configurar
bin/magento module:enable Tajo_Core Tajo_Sync Tajo_Loyalty
bin/magento setup:upgrade
bin/magento setup:di:compile
bin/magento cache:flush

Configuração

Navegue até Lojas → Configuração → Tajo → Definições Gerais:

<!-- app/etc/env.php ou via Painel de Administração -->
'tajo' => [
    'api_key' => 'your_tajo_api_key',
    'api_secret' => 'your_tajo_api_secret',
    'environment' => 'production',
    'debug_mode' => false
],
'brevo' => [
    'api_key' => 'your_brevo_api_key'
]

Passo 2: Configurar Sincronização de Dados

Definições de Sincronização de Clientes

Configure em Lojas → Configuração → Tajo → Sincronização de Dados:

{
  "sync_settings": {
    "customers": {
      "enabled": true,
      "sync_frequency": "real-time",
      "fields": [
        "email",
        "firstname",
        "lastname",
        "telephone",
        "group_id",
        "store_id",
        "website_id",
        "created_at",
        "addresses",
        "custom_attributes"
      ]
    },
    "orders": {
      "enabled": true,
      "sync_frequency": "real-time",
      "include_items": true,
      "include_shipping": true,
      "include_payment": true
    },
    "products": {
      "enabled": true,
      "sync_frequency": "hourly",
      "include_configurable": true,
      "include_images": true,
      "include_categories": true
    }
  }
}

Observadores de Eventos

O Tajo observa estes eventos do Magento:

EventoPropósito
customer_save_afterSincronizar atualizações de clientes para Tajo e Brevo
customer_register_successSincronizar novos clientes, atribuir pontos de registo
sales_order_place_afterRastrear compras, atribuir pontos de fidelidade
sales_order_save_afterAtualizar estado do pedido, acionar campanhas
checkout_cart_save_afterRastrear carrinho para recuperação de abandono
catalog_product_save_afterManter catálogo de produtos sincronizado

Configuração Multi-Site

Para configurações Magento multi-site:

<?php
// di.xml - Configurar definições por site
namespace Tajo\Core\Model;


class WebsiteConfig
{
    public function getConfigForWebsite($websiteId): array
    {
        return [
            'api_key' => $this->scopeConfig->getValue(
                'tajo/general/api_key',
                ScopeInterface::SCOPE_WEBSITE,
                $websiteId
            ),
            'loyalty_program' => $this->scopeConfig->getValue(
                'tajo/loyalty/program_id',
                ScopeInterface::SCOPE_WEBSITE,
                $websiteId
            )
        ];
    }
}

Importação Inicial de Dados

Importe dados existentes via CLI:

Terminal window
# Importar todos os clientes
bin/magento tajo:sync:customers --all


# Importar pedidos dos últimos 90 dias
bin/magento tajo:sync:orders --from="90 days ago"


# Importar catálogo de produtos
bin/magento tajo:sync:products --all


# Sincronização completa com barra de progresso
bin/magento tajo:sync:full --verbose

Ou programaticamente:

<?php
namespace Tajo\Sync\Console\Command;


use Magento\Customer\Api\CustomerRepositoryInterface;
use Tajo\Core\Api\CustomerSyncInterface;


class SyncCustomersCommand extends Command
{
    public function execute(InputInterface $input, OutputInterface $output)
    {
        $searchCriteria = $this->searchCriteriaBuilder->create();
        $customers = $this->customerRepository->getList($searchCriteria);


        foreach ($customers->getItems() as $customer) {
            $this->customerSync->sync($customer);
            $output->writeln("Sincronizado: " . $customer->getEmail());
        }
    }
}

Passo 3: Configurar Programa de Fidelidade

Configurar Sistema de Pontos

Configure em Lojas → Configuração → Tajo → Fidelidade:

<?php
// Configuração de fidelidade
$pointsConfig = [
    // Pontos por unidade de moeda gasta
    'purchase_points' => [
        'enabled' => true,
        'rate' => 1, // 1 ponto por $1
        'rounding_mode' => 'floor',
        'include_tax' => false,
        'include_shipping' => false
    ],


    // Ações de bónus
    'bonus_points' => [
        'account_creation' => 100,
        'first_purchase' => 200,
        'review_submitted' => 50,
        'referral_made' => 500,
        'birthday_bonus' => 100,
        'newsletter_signup' => 25,
        'wishlist_share' => 15
    ],


    // Multiplicadores por grupo de clientes
    'group_multipliers' => [
        'General' => 1.0,
        'Wholesale' => 0.5,
        'Retailer' => 0.75,
        'VIP' => 2.0
    ]
];

Bloco de Fidelidade nos Templates

Adicione widgets de fidelidade ao seu tema:

<!-- No seu template .phtml -->
<?php
/** @var \Tajo\Loyalty\Block\Customer\Points $block */
?>


<div class="tajo-loyalty-widget">
    <h3><?= __('As Suas Recompensas') ?></h3>


    <div class="points-balance">
        <span class="label"><?= __('Saldo de Pontos:') ?></span>
        <span class="value"><?= $block->getPointsBalance() ?></span>
    </div>


    <div class="loyalty-tier">
        <span class="label"><?= __('O Seu Nível:') ?></span>
        <span class="value tier-<?= strtolower($block->getCurrentTier()) ?>">
            <?= $block->getCurrentTier() ?>
        </span>
    </div>


    <div class="points-to-next-tier">
        <?= __('%1 pontos até %2', $block->getPointsToNextTier(), $block->getNextTier()) ?>
    </div>
</div>

Níveis de Fidelidade 

<?php
$loyaltyTiers = [
    [
        'name' => 'Bronze',
        'min_points' => 0,
        'customer_group' => 'General',
        'benefits' => [
            '1 ponto por $1 gasto',
            'Pontos bónus de aniversário',
            'Promoções exclusivas para membros'
        ]
    ],
    [
        'name' => 'Silver',
        'min_points' => 1000,
        'customer_group' => 'Silver Members',
        'benefits' => [
            'Multiplicador de pontos 1,25x',
            'Envio gratuito em pedidos acima de $50',
            'Acesso antecipado a saldos'
        ]
    ],
    [
        'name' => 'Gold',
        'min_points' => 5000,
        'customer_group' => 'Gold Members',
        'benefits' => [
            'Multiplicador de pontos 1,5x',
            'Envio gratuito em todos os pedidos',
            'Acesso exclusivo a produtos',
            'Suporte prioritário'
        ]
    ],
    [
        'name' => 'Platinum',
        'min_points' => 15000,
        'customer_group' => 'VIP',
        'benefits' => [
            'Multiplicador de pontos 2x',
            'Envio expresso gratuito',
            'Assistente de compras pessoal',
            'Oferta anual'
        ]
    ]
];

Recompensas como Regras de Preço do Carrinho 

<?php
// Criar recompensa como regra de preço do carrinho Magento
namespace Tajo\Loyalty\Model\Reward;


class RewardGenerator
{
    public function createRewardCoupon(
        int $customerId,
        string $rewardType,
        float $value
    ): string {
        $rule = $this->ruleFactory->create();
        $rule->setName('Recompensa de Fidelidade - ' . $rewardType)
            ->setIsActive(true)
            ->setCustomerGroupIds([0, 1, 2, 3])
            ->setWebsiteIds([1])
            ->setCouponType(Rule::COUPON_TYPE_SPECIFIC)
            ->setUsesPerCoupon(1)
            ->setUsesPerCustomer(1)
            ->setSimpleAction($this->getActionType($rewardType))
            ->setDiscountAmount($value)
            ->setStopRulesProcessing(false);


        $this->ruleRepository->save($rule);


        // Gerar código de cupão único
        $coupon = $this->couponFactory->create();
        $coupon->setRuleId($rule->getRuleId())
            ->setCode($this->generateCouponCode($customerId))
            ->setUsageLimit(1)
            ->setUsagePerCustomer(1)
            ->setType(Coupon::TYPE_GENERATED);


        $this->couponRepository->save($coupon);


        return $coupon->getCode();
    }
}

Passo 4: Recuperação de Carrinho Abandonado

Observador de Rastreamento do Carrinho 

<?php
namespace Tajo\Sync\Observer;


use Magento\Framework\Event\Observer;
use Magento\Framework\Event\ObserverInterface;


class CartSaveObserver implements ObserverInterface
{
    public function execute(Observer $observer)
    {
        /** @var \Magento\Quote\Model\Quote $quote */
        $quote = $observer->getEvent()->getQuote();


        if ($quote->getItemsCount() === 0) {
            return;
        }


        $customerEmail = $quote->getCustomerEmail();
        if (!$customerEmail) {
            return;
        }


        $cartItems = [];
        foreach ($quote->getAllVisibleItems() as $item) {
            $cartItems[] = [
                'productId' => $item->getProductId(),
                'sku' => $item->getSku(),
                'name' => $item->getName(),
                'quantity' => $item->getQty(),
                'price' => $item->getPrice(),
                'rowTotal' => $item->getRowTotal(),
                'image' => $this->getProductImage($item->getProduct())
            ];
        }


        $this->tajoApi->trackCart([
            'email' => $customerEmail,
            'quoteId' => $quote->getId(),
            'items' => $cartItems,
            'subtotal' => $quote->getSubtotal(),
            'grandTotal' => $quote->getGrandTotal(),
            'currency' => $quote->getQuoteCurrencyCode(),
            'checkoutUrl' => $this->urlBuilder->getUrl('checkout')
        ]);
    }
}

Templates de E-mail de Recuperação

email_templates.xml
<template id="tajo_cart_recovery_1" label="Recuperação de Carrinho - Primeiro Lembrete" file="Tajo_Sync::email/cart_recovery_1.html"/>
<template id="tajo_cart_recovery_2" label="Recuperação de Carrinho - Com Desconto" file="Tajo_Sync::email/cart_recovery_2.html"/>

Passo 5: Automação de Marketing

Segmentos de Clientes 

<?php
// Criar segmentos com base nos dados do Magento
$magentoSegments = [
    // Comportamento de compra
    [
        'name' => 'Primeiras Compras',
        'conditions' => [
            'orders_count' => 1
        ]
    ],
    [
        'name' => 'Clientes Recorrentes',
        'conditions' => [
            'orders_count' => ['$gte' => 2]
        ]
    ],
    [
        'name' => 'Clientes de Alto Valor',
        'conditions' => [
            'lifetime_sales' => ['$gte' => 1000]
        ]
    ],


    // Grupos de clientes
    [
        'name' => 'Clientes Grossistas',
        'conditions' => [
            'group_id' => 2 // Grupo Grossista
        ]
    ],


    // Específico por loja/site
    [
        'name' => 'Clientes da Loja EUA',
        'conditions' => [
            'website_id' => 1
        ]
    ]
];

Automação de Eventos de Pedido 

<?php
namespace Tajo\Sync\Observer;


class OrderPlaceAfterObserver implements ObserverInterface
{
    public function execute(Observer $observer)
    {
        /** @var \Magento\Sales\Model\Order $order */
        $order = $observer->getEvent()->getOrder();
        $customer = $this->getCustomerData($order);


        // Atribuir pontos de fidelidade
        $pointsEarned = $this->loyaltyCalculator->calculate($order, $customer);
        $this->tajoApi->awardPoints($customer['id'], $pointsEarned, [
            'reason' => 'purchase',
            'orderId' => $order->getIncrementId()
        ]);


        // Enviar para Brevo para campanhas
        $this->brevoApi->trackEvent($customer['email'], 'order_placed', [
            'order_id' => $order->getIncrementId(),
            'order_total' => $order->getGrandTotal(),
            'points_earned' => $pointsEarned,
            'loyalty_tier' => $customer['loyaltyTier'],
            'products' => $this->getOrderProducts($order),
            'store_id' => $order->getStoreId()
        ]);


        // Verificar atualização de nível
        $this->loyaltyService->checkTierUpgrade($customer['id']);
    }
}

Passo 6: Recomendações de Produtos

Configurar Motor de Recomendações 

<?php
$recommendationConfig = [
    'algorithms' => [
        [
            'name' => 'frequently_bought_together',
            'weight' => 0.3,
            'source' => 'magento_related'
        ],
        [
            'name' => 'similar_products',
            'weight' => 0.25,
            'source' => 'category_based'
        ],
        [
            'name' => 'customer_also_viewed',
            'weight' => 0.2,
            'source' => 'reports_viewed'
        ],
        [
            'name' => 'upsell_products',
            'weight' => 0.15,
            'source' => 'magento_upsell'
        ],
        [
            'name' => 'personalized',
            'weight' => 0.1,
            'source' => 'tajo_ml'
        ]
    ],
    'filters' => [
        'exclude_purchased' => true,
        'in_stock_only' => true,
        'same_website' => true
    ]
];

Widget de Recomendações

catalog_product_view.xml
<referenceContainer name="content.aside">
    <block class="Tajo\Recommendations\Block\Product\Recommendations"
           name="tajo.product.recommendations"
           template="Tajo_Recommendations::product/recommendations.phtml">
        <arguments>
            <argument name="algorithm" xsi:type="string">frequently_bought_together</argument>
            <argument name="limit" xsi:type="number">4</argument>
        </arguments>
    </block>
</referenceContainer>

Passo 7: Comandos CLI

O Tajo disponibiliza estes comandos CLI:

Terminal window
# Comandos de sincronização
bin/magento tajo:sync:customers [--all] [--from="date"]
bin/magento tajo:sync:orders [--all] [--from="date"]
bin/magento tajo:sync:products [--all]
bin/magento tajo:sync:full


# Comandos de fidelidade
bin/magento tajo:loyalty:recalculate [--customer-id=ID]
bin/magento tajo:loyalty:award --customer-id=ID --points=100 --reason="Manual"
bin/magento tajo:loyalty:tiers:update


# Comandos de depuração
bin/magento tajo:test:connection
bin/magento tajo:debug:customer --email="[email protected]"

Resolução de Problemas

Problemas Comuns

Conflitos de Extensão

Terminal window
# Verificar conflitos
bin/magento module:status | grep -i tajo
bin/magento setup:db:status


# Limpar caches
bin/magento cache:clean
bin/magento cache:flush
rm -rf generated/* var/cache/* var/page_cache/*

Problemas de Sincronização 

<?php
// Ativar registo de depuração
// Em app/etc/env.php
'tajo' => [
    'debug_mode' => true,
    'log_level' => 'debug'
]


// Verificar registos
// var/log/tajo.log
// var/log/tajo_sync.log

Otimização de Desempenho

di.xml
<?php
// Usar sincronização assíncrona para catálogos grandes
<type name="Tajo\Sync\Model\Queue\Publisher">
    <arguments>
        <argument name="async" xsi:type="boolean">true</argument>
        <argument name="batchSize" xsi:type="number">100</argument>
    </arguments>
</type>

Próximos Passos

  1. Configurar a Integração Brevo para campanhas de e-mail/SMS
  2. Configurar Webhooks para eventos em tempo real
  3. Criar Segmentos de Clientes para marketing direcionado
  4. Criar Modelos de E-mail para campanhas automatizadas

Suporte

Assistente AI

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

Comece grátis com Brevo