Integração com Magento

Conecte a sua loja Magento 2 (Open Source / Adobe Commerce) ao Conviro para que o seu chatbot possa rastrear pedidos, lidar com cancelamentos e devoluções e responder a perguntas sobre produtos dentro do chat.

Há duas formas de conectar, e ambas desbloqueiam os mesmos recursos de fluxo:

1. Com a extensão oficial do Conviro – uma instalação automatizada com um clique. Recomendada para a maioria dos lojistas.
2. Sem nenhuma extensão – uma configuração manual usando a API REST nativa do Magento mais um pequeno snippet do widget. Use isto se não puder (ou não quiser) instalar módulos de terceiros.

> Ponto-chave: a extensão é uma camada de conveniência, não um requisito. Rastreamento de pedidos, cancelamento, devoluções e busca de produtos passam pela API REST nativa do Magento no backend do Conviro – portanto funcionam de qualquer das duas formas. A extensão apenas automatiza a configuração, a injeção do widget e os webhooks de eventos.

Requisitos

• Plano Pro ou superior
• Magento 2.4+ (Open Source / Community ou Adobe Commerce)
• Acesso de administrador à sua loja Magento
• A sua chave de API do Conviro (gere uma em Dashboard -> Settings -> API Keys)

Método A – Com a extensão oficial (recomendado)

O caminho mais rápido. Um campo, um clique e tudo fica conectado.

Instalação

1. Instale o módulo via Composer:

composer config repositories.conviro composer https://repo.conviro.io
composer config http-basic.repo.conviro.io api <YOUR_CONVIRO_API_KEY>
composer require conviro/module-aichat
php bin/magento module:enable Conviro_AiChat
php bin/magento setup:upgrade
php bin/magento setup:di:compile
php bin/magento cache:flush

(Ou faça upload do ZIP da extensão pelo painel do Conviro se você não usa o Composer.)

1. No admin do Magento, vá em Stores -> Configuration -> Conviro -> AI Chat.
2. Cole a sua chave de API do Conviro e clique em Save Config.

O que acontece automaticamente

Ao salvar a chave de API, a extensão:

• Cria uma integração do Magento chamada “Conviro AI Chat” com permissões REST de privilégio mínimo (Sales orders, Catalog products, Customers, Carts) e gera um token de acesso.
• Registra a sua loja no Conviro (URL da loja + token) para que os fluxos possam ler os seus dados.
• Injeta o widget de chat automaticamente em todas as páginas da loja – sem editar o tema.
• Envia webhooks de eventos (pedido feito, status do pedido alterado, produto salvo, cliente registrado) para que os dados permaneçam atualizados quase em tempo real.
• Armazena um segredo de webhook assinado para que os eventos de entrada/saída sejam verificados.

É isso – os seus fluxos estão no ar.

Método B – Sem a extensão (configuração manual)

Nenhuma instalação de módulo é necessária. Em ~5 minutos você fará o que a extensão faz automaticamente: criar um token de API e colar o snippet do widget.

Passo 1 – Criar uma integração do Magento (para os fluxos)

1. No admin do Magento, vá em System -> Extensions -> Integrations.
2. Clique em Add New Integration.
3. Dê um nome (ex.: “Conviro”) e informe a sua senha de administrador.
4. Abra a aba API e conceda acesso a estes recursos:

• Sales -> Operations -> Orders (busca de pedidos, status, cancelamento)
• Catalog -> Inventory -> Products (busca de produtos)
• Customers -> Customer (verificação de titularidade do cliente/pedido)
• (opcional) Sales -> Operations -> Returns se você usa o fluxo de devoluções

1. Clique em Save e depois em Activate.
2. Copie o Access Token exibido após a ativação.

Passo 2 – Conectar no Conviro

1. Vá em Dashboard -> Settings -> Integrations -> Magento.
2. Informe a URL da sua loja (ex.: https://your-store.com) e cole o Access Token.
3. Clique em Connect. O Conviro verifica o token e habilita os fluxos de e-commerce.

Passo 3 – Adicionar o widget de chat

Como não há uma extensão que injete o widget automaticamente, adicione o snippet você mesmo. Coloque-o logo antes da tag body de fechamento do seu tema, ou carregue-o via Google Tag Manager:

<script src="https://cdn.conviro.io/widget/widget.iife.js"></script>
<script>
  cw('init', { publicKey: 'pk_YOUR_PUBLIC_KEY' });
</script>

No Magento, o lugar mais limpo é Content -> Design -> Configuration -> [seu tema] -> HTML Head / Footer, ou um bloco Miscellaneous HTML. O GTM também funciona e sobrevive a atualizações de tema.

O que cada método oferece

Em resumo: todos os fluxos voltados ao cliente funcionam nos dois modos. Sem a extensão você abre mão apenas da configuração com um clique, da injeção automática do widget e da sincronização por webhooks em tempo real – tudo isso tem equivalentes manuais simples.

Segurança: verificação de titularidade do pedido

Ambos os métodos incluem a mesma proteção contra a adivinhação de números de pedido. Antes de revelar qualquer detalhe do pedido, o fluxo pede ao cliente o e-mail do pedido:

1. O cliente fornece um número de pedido.
2. O bot pede o e-mail usado no checkout.
3. O Conviro só revela os detalhes do pedido se o e-mail corresponder ao pedido.
4. Se não corresponder, o bot responde exatamente como se o pedido não tivesse sido encontrado – assim um atacante não consegue saber se um número de pedido é real.

Isso é aplicado no backend do Conviro, independentemente da extensão, por meio da etapa de verificação de e-mail do fluxo de pedidos. Os modelos de fluxo de e-commerce prontos já coletam o e-mail antes de qualquer busca.

Fluxos de e-commerce

Use os modelos prontos em Dashboard -> Flows -> New Flow -> Use Template -> E-Commerce:

• Order Status – consultar status, envio e rastreamento por número do pedido + e-mail.
• Cancel & Refund – verificar a titularidade e, em seguida, cancelar um pedido elegível.
• Returns & Exchanges – verificar a titularidade, capturar o motivo e iniciar um RMA.
• Product Search – encontrar produtos por nome/SKU e compartilhar detalhes no chat.

Tudo isso chama a API REST nativa do Magento usando o token do Método A ou B – nenhum endpoint personalizado é necessário.

Dicas

• Use a extensão se puder – ela remove cada passo manual e mantém os dados atualizados via webhooks.
• Use o modo manual em lojas restritas, marketplaces, ou quando uma política de segurança proíbe novos módulos.
• Conceda à integração apenas os recursos mínimos que você realmente usa – você sempre pode adicionar Returns depois.
• Comece pelo fluxo Order Status; ele responde à pergunta nº 1 do e-commerce e prova que a conexão funciona.
• Após conectar, teste pedindo ao bot um pedido real (com o e-mail correspondente) e um produto/SKU real.