Um agente de IA para Magento que conhece seu catálogo e opera suas APIs

O Magento ocupa uma posição única no ecommerce. É a plataforma que os lojistas escolhem quando o catálogo deles é complexo demais para soluções mais simples — quando os produtos vêm em dezenas de combinações de atributos, quando a mesma loja atende compradores atacadistas B2B e clientes de varejo B2C, quando configurações multi-loja abrangem diferentes marcas ou regiões sob um único painel de administração. Essa complexidade é o que torna o Magento poderoso. É também o que torna o suporte ao cliente em uma loja Magento excepcionalmente difícil de automatizar.

Um catálogo típico do Magento não é uma lista simples de produtos com um nome, preço e descrição. É uma teia de tipos de produtos, cada um com uma lógica estrutural diferente. Um produto configurável — digamos, uma jaqueta de corrida de performance — pode ter 48 filhos de produtos simples representando todas as combinações de tamanho (do PP ao XGG) e cor (preto, azul-marinho, carmesim, cinza-carvão, oliva, aço). Um produto em pacote permite que o cliente escolha componentes — um sistema de home theater onde ele seleciona o receiver, as caixas de som e o subwoofer de listas de opções selecionadas, cada uma com seu próprio preço. Produtos agrupados vinculam itens relacionados — um conjunto de móveis onde a mesa de jantar, as cadeiras e o banco são exibidos juntos, mas comprados individualmente. Toda conversa de suporte sobre um desses produtos exige a compreensão não apenas do produto em si, mas de seu tipo, seus filhos, seus atributos e como eles se mapeiam para o que o cliente está realmente perguntando.

Quando um cliente entra em contato com o suporte e pergunta: "a Jaqueta Alpine Performance tem na cor vermelha no tamanho G?" — isso não é uma simples consulta. No modelo de dados do Magento, o cliente está perguntando se um produto simples específico existe dentro da matriz de atributos de um produto configurável. Um agente de suporte precisaria encontrar o configurável, olhar seus simples associados e verificar se a interseção de cor=vermelho e tamanho=G existe e está habilitada. Um chatbot de FAQ não tem chance de responder isso com precisão. Ele daria uma resposta genérica como "por favor, verifique a página do produto" ou erraria o palpite. Um agente de IA que rastreou a vitrine e entende a estrutura do produto pode dar uma resposta direta — "Sim, a Jaqueta Alpine Performance está disponível em Vermelho / Grande. Custa $129,00 e é enviada em até 2 dias úteis" — porque aprendeu a matriz de atributos do produto rastreando a mesma página de detalhes do produto que o cliente vê.

O agente de IA da Asyntai se aproxima de um catálogo Magento da mesma forma que um agente de suporte bem treinado faria: lendo a vitrine. Ele rastreia suas páginas de produtos, páginas de categorias, páginas de conteúdo CMS e páginas de políticas. Ele lê as descrições dos produtos, as tabelas de atributos, as estruturas de categorias, as opções de navegação em camadas. Ele lê os blocos CMS que você incorporou nos cabeçalhos de categoria e as páginas estáticas com suas políticas de envio e procedimentos de devolução. Quando um cliente faz uma pergunta, o agente utiliza esta base de conhecimento rastreada — a mesma informação que o cliente poderia encontrar navegando em seu site, mas entregue instantaneamente em um formato conversacional sem o esforço de navegação.

Mas o conteúdo rastreado cobre apenas metade da equação de suporte. A outra metade — e a metade que gera a maioria dos tickets de suporte — envolve dados ao vivo. "Onde está meu pedido?" "Este SKU está em estoque?" "Qual é o saldo da minha conta?" "Ainda posso devolver isto?" Essas perguntas não podem ser respondidas a partir de uma base de conhecimento estática porque as respostas mudam a cada transação, a cada envio, a cada ajuste de inventário. É aqui que a API REST do Magento se torna o ponto de integração crítico, e onde as Ferramentas Personalizadas da Asyntai transformam a IA de um assistente experiente em um agente operacional.

Magento 2 vem com uma API REST abrangente. Os dados de pedidos ficam em /rest/V1/orders. O estoque pode ser consultado através de /rest/V1/stockItems/{sku}. Os dados do cliente ficam em /rest/V1/customers. Conteúdo CMS, regras de catálogo, dados do carrinho, rastreamento de remessa — quase todas as entidades na arquitetura do Magento são acessíveis via API. As Ferramentas Personalizadas permitem que o agente de IA chame esses endpoints no meio da conversa. Um cliente pergunta sobre o pedido dele. O agente extrai o ID de incremento do pedido da mensagem, chama seu endpoint de pedido do Magento, recebe o status do pedido, detalhes do item, rastreamento de remessa e informações de pagamento, e compõe uma resposta completa. Todo o ciclo — análise da pergunta, chamada da API, interpretação da resposta, geração da réplica — acontece em segundos.

A diferença prática que isso cria é significativa. Sem acesso à API, o melhor que uma IA pode fazer com uma pergunta sobre um pedido é recitar suas instruções genéricas de rastreamento: "Você pode encontrar o status do seu pedido em Minha Conta, em Pedidos e Devoluções." Com as Ferramentas Personalizadas conectadas à API de pedidos do Magento, o agente diz: "Seu pedido #100000042 foi enviado em 17 de junho via UPS Ground — código de rastreamento 1Z999AA10123456784. Ele está atualmente em trânsito em Chicago e a previsão de chegada é 21 de junho. O pedido inclui a Jaqueta de Performance Alpine em Azul Marinho / Média e o Boné de Corrida em Carvão." Isso não é assistência. Isso é resolução. O cliente obteve a resposta. O chamado foi encerrado. Nenhum humano esteve envolvido.

As perguntas sobre estoque são particularmente valiosas em lojas Magento devido à complexidade do catálogo. Um cliente navegando em um produto configurável com 48 variantes quer saber se sua combinação específica está em estoque antes de finalizar a compra. Em muitas lojas Magento, a página do produto mostra "Em Estoque" no nível configurável, mesmo quando combinações específicas de tamanho e cor estão esgotadas — o cliente só descobre isso depois de selecionar suas opções e ver "Fora de Estoque" em texto vermelho. Isso gera frustração e tickets de suporte. O agente de IA pode encurtar todo esse processo. "A Jaqueta Alpine Performance está disponível em Oliva, GG?" — o agente chama o endpoint de inventário para o SKU específico daquele produto simples, verifica a quantidade e responde: "O Oliva / GG atualmente tem 7 unidades em estoque. Está pronto para envio." Ou, se estiver esgotado: "O Oliva / GG está atualmente esgotado, mas o Oliva em G e XG estão disponíveis. O Azul Marinho / GG também está em estoque se você for flexível na cor." O agente não apenas responde à pergunta — ele oferece alternativas, porque entende a estrutura do produto.

Devoluções são outra área onde a complexidade do Magento multiplica a carga de suporte. Uma loja Magento pode ter políticas de devolução diferentes para tipos de produtos diferentes — eletrônicos com um prazo de 15 dias, vestuário com 30 dias, itens personalizados ou customizados que são venda final. A política de devolução pode estar em uma página de CMS. Os dados do pedido vivem no banco de dados, acessível via API. Uma solicitação de devolução requer ambos: verificar a data do pedido em relação à política aplicável e, em seguida, processar o RMA. Com as Ferramentas Personalizadas, o agente de IA lida com o fluxo de trabalho completo. Ele chama a API de pedidos para obter a data da compra e os detalhes do item. Ele verifica isso em relação à política de devolução que aprendeu ao rastrear o conteúdo do seu CMS. Se o cliente for elegível, ele pode chamar um endpoint de devoluções para iniciar o RMA — capturando o item, o motivo e as informações de contato do cliente. O cliente obtém uma resolução em uma conversa. Sua equipe de suporte recebe um RMA concluído em sua fila em vez de um e-mail não estruturado que eles precisam pesquisar.

Multi-store é um recurso definidor do Magento e cria um desafio de suporte exclusivo. Uma única instalação do Magento pode atender a vários sites, cada um com várias visualizações de loja — marcas diferentes, regiões diferentes, idiomas diferentes, catálogos diferentes, preços diferentes. Um comerciante que executa uma vitrine B2C e um portal de atacado B2B da mesma instância do Magento precisa de suporte que entenda em qual loja o cliente está e aplique o catálogo, os preços e as políticas corretas. A Asyntai lida com isso permitindo que cada visualização de loja tenha sua própria configuração de widget. A loja B2C obtém um agente respondendo usando páginas de produtos de consumo com políticas de varejo padrão. O portal B2B obtém um agente respondendo usando catálogos de atacado com lógica de preços negociados e fluxos de trabalho de contas de empresas. Cada widget rastreia sua própria vitrine. Cada um se conecta ao escopo de API relevante. O cliente no seu portal de atacado pergunta sobre o preço negociado de sua empresa — o agente sabe desse contexto porque está operando dentro dessa visualização de loja.

A dimensão B2B do Magento — especialmente no Adobe Commerce — adiciona outra camada de complexidade de suporte. Compradores B2B têm contas de empresa, catálogos compartilhados com preços personalizados, listas de requisição, pedidos de compra e fluxos de trabalho de solicitação de cotação. Estes não são casos extremos; são centrais para a forma como os compradores B2B interagem com a plataforma. Um agente de IA conectado aos endpoints da API REST B2B do Magento pode consultar o catálogo compartilhado de uma empresa para confirmar o preço negociado em um produto específico. Ele pode verificar uma lista de requisição e informar ao comprador se algum item ficou sem estoque desde a última vez que ele a atualizou. Ele pode recuperar o status de uma cotação pendente ou de um pedido de compra aguardando aprovação. Para comerciantes B2B, isso não é conveniência — é substituir uma parte significativa do trabalho de gerenciamento de contas que, de outra forma, exigiria que um representante de vendas ou agente de atendimento ao cliente dedicado o tratasse manualmente.

O desempenho é uma preocupação perene para os comerciantes Magento, e com razão. Lojas Magento geralmente rodam atrás do cache de página inteira do Varnish, muitas vezes com Fastly ou Cloudflare como camada de CDN. Eles gastaram tempo configurando o aquecimento de cache, o "hole-punching" para conteúdo dinâmico e regras de TTL para diferentes tipos de página. Qualquer ferramenta adicionada ao site precisa funcionar dentro desta infraestrutura, não contra ela. O snippet JS da Asyntai carrega de forma assíncrona — ele não bloqueia a renderização da página, não interfere nas regras de cache do Varnish e não requer nenhuma configuração de purga de cache ou "hole-punching". O snippet é uma única tag de script async. O crawler lê as mesmas páginas em cache que seus visitantes veem. Sua pilha de desempenho Magento cuidadosamente ajustada permanece intocada.

O processo de instalação reflete como as lojas Magento realmente operam. Você tem dois caminhos. O caminho do desenvolvedor: adicione a tag de script ao arquivo de layout default_head_blocks.xml do seu tema, implante, e pronto. O caminho do administrador: cole o script em um bloco estático de CMS que é referenciado no seu cabeçalho, salve, limpe o cache, pronto. Se você já está usando o Google Tag Manager na sua loja, você pode adicionar o snippet como uma tag HTML personalizada — sem alterações de tema, sem implantação, sem atualizações do Composer. O ponto é que adicionar o agente de IA não toca no seu código Magento. Não há módulo para instalar, nenhum setup:upgrade para executar, nenhuma configuração de DI, nenhuma etapa de compilação. É apenas front-end — um arquivo JavaScript carregado no navegador, falando com o backend da Asyntai. Sua versão do Magento, seus módulos personalizados, seu pipeline de implantação — nada disso muda.

A configuração da Ferramenta Personalizada para Magento segue um padrão previsível porque a API REST do Magento é bem documentada e padronizada. A primeira ferramenta que a maioria dos lojistas Magento cria é o status do pedido: endpoint /rest/V1/orders?searchCriteria[filterGroups][0][filters][0][field]=increment_id&searchCriteria[filterGroups][0][filters][0][value]={order_number}, com um token de integração no cabeçalho de autenticação. O agente extrai o número do pedido da conversa, faz a chamada e retorna os campos relevantes — status, itens, rastreamento de envio. A segunda ferramenta é tipicamente o inventário: /rest/V1/stockItems/{sku}, onde o SKU é extraído da pergunta do cliente sobre o produto e mapeado para a fonte de inventário. A partir daí, os lojistas adicionam ferramentas com base em seus padrões de suporte específicos — consulta de conta do cliente, processamento de devolução, saldo de pontos de recompensa, saldo de vale-presente, status da cotação. Cada ferramenta leva cinco minutos para ser configurada no painel. Sem código. Sem middleware. Apenas um URL de endpoint, parâmetros, um token de autenticação e uma descrição em linguagem simples de quando a IA deve usá-la.

O modelo de autenticação para ferramentas da API do Magento é direto. O Magento suporta tokens de integração — tokens de API de longa duração criados no painel de administração em Sistema > Integrações. Você cria uma integração com acesso aos recursos específicos da API que o agente de IA precisa (pedidos, inventário, clientes), copia o token de acesso e o cola no campo de autenticação da Ferramenta Personalizada no painel do Asyntai como Authorization: Bearer seu-token-de-integração. O token nunca chega ao navegador do cliente — o Asyntai chama seu servidor da API do Magento, recebe a resposta e usa os dados para compor a resposta do chat. Seu token de integração permanece entre a infraestrutura do Asyntai e seu backend do Magento. Você pode limitar o acesso da integração a recursos somente leitura se quiser que o agente consulte dados, mas não os modifique — um ponto de partida razoável antes de você habilitar operações de gravação, como a criação de RMA.

Padrões de tráfego sazonais afetam as lojas Magento particularmente. Black Friday, Cyber Monday, compras de fim de ano, liquidações sazonais — esses eventos podem multiplicar o tráfego e o volume de pedidos por 5x ou 10x em questão de horas. O volume de tíquetes de suporte segue o mesmo caminho. "Onde está meu pedido?" dispara no dia seguinte a uma grande promoção. "Isto ainda está em estoque?" aumenta durante promoções relâmpago. "Posso devolver isto?" atinge o pico em janeiro. Contratar pessoal de suporte sazonal para uma janela de três semanas é caro e o tempo de adaptação significa que eles mal estão treinados antes que o pico passe. Um agente de IA não precisa de treinamento, não precisa aprender sua política de devolução e não desacelera quando o volume aumenta. Ele responde ao milésimo "onde está meu pedido?" da mesma forma que respondeu ao primeiro — chamando sua API do Magento, obtendo os dados ao vivo e fornecendo uma resposta completa. Sua equipe de suporte se concentra nos problemas complexos — os casos extremos, as escaladas, os clientes irritados que precisam de um toque humano — enquanto o agente lida com o volume repetitivo que compõe 70-80% dos tíquetes durante a alta temporada.

A dimensão multilíngue é digna de nota porque a arquitetura multi-loja do Magento é comumente usada para visualizações de loja baseadas em idioma. Um comerciante que atende aos EUA, Alemanha e França pode ter três visualizações de loja com conteúdo traduzido para cada idioma. O agente de IA lida com isso naturalmente. Ao rastrear a visualização da loja alemã, ele aprende as descrições de produtos alemãs, as páginas de políticas alemãs e o conteúdo CMS alemão. Quando um cliente nessa visualização de loja faz uma pergunta em alemão, o agente responde em alemão — usando o conteúdo alemão que rastreou. As respostas de Ferramentas Personalizadas da API do Magento (que normalmente retornam dados no idioma padrão da API) são traduzidas em tempo real pela IA para o idioma do cliente. O cliente alemão recebe respostas em alemão, mesmo quando a API subjacente retorna nomes de campos e valores de status em inglês. Nenhum trabalho adicional de localização no lado do Magento. A IA lida com a camada de tradução automaticamente.

Os dados dos logs de chamadas de ferramentas personalizadas fornecem inteligência operacional que vai além da análise básica de chatbots. Quando você vê que 300 clientes neste mês ligaram para a ferramenta de status do pedido, e 40% deles o fizeram em até 24 horas após o pedido ter sido feito, você sabe que seus e-mails de confirmação de pedido não estão dando aos clientes confiança suficiente de que a compra foi concluída. Quando as chamadas de verificação de estoque aumentam para um SKU específico que está listado como "em estoque" na página do produto, mas consistentemente retorna quantidade zero da API, você encontrou um problema de sincronização entre sua fonte de estoque e seu índice de estoque do Magento. Quando as solicitações de devolução se concentram em uma determinada categoria de produto, você identificou um problema de qualidade ou de desalinhamento de expectativas antes que seu relatório de devoluções o detecte no próximo trimestre. O histórico de chamadas de ferramentas do agente de IA se torna uma camada de diagnóstico em tempo real em sua operação Magento — uma que revela não apenas o que os clientes estão perguntando, mas o que eles estão tentando fazer e onde sua loja está falhando em atender às expectativas deles.

Comerciantes Magento que já investiram em sua API REST — construindo endpoints para aplicativos móveis, front-ends headless, integrações de ERP ou conectores de marketplace de terceiros — obtêm valor desproporcional com as Ferramentas Personalizadas porque esses endpoints já existem. Eles não constroem nada novo. Eles apontam o agente de IA para o mesmo endpoint de status de pedido que o aplicativo móvel usa, o mesmo endpoint de inventário que o sistema de PDV verifica, o mesmo endpoint de cliente com o qual o CRM sincroniza. O agente de IA se torna mais um consumidor da mesma infraestrutura de API — um que, por acaso, possui uma interface conversacional e atende o cliente diretamente. O investimento que fizeram em sua API paga um dividendo que não planejaram: suporte ao cliente com tecnologia de IA que resolve tickets usando as mesmas fontes de dados que alimentam o restante de sua operação.

A realidade competitiva para comerciantes Magento é que as expectativas dos clientes não se ajustam à complexidade da plataforma. Um cliente comprando em uma loja Magento com 50.000 produtos configuráveis e um sistema de inventário multi-armazém espera a mesma experiência de suporte instantânea e precisa que obtém de uma loja Shopify com 50 produtos. Ele espera perguntar sobre seu pedido e receber um número de rastreamento. Ele espera perguntar sobre a disponibilidade do produto e obter uma resposta real. Ele espera solicitar uma devolução e que ela seja processada sem enviar três e-mails. A complexidade da plataforma é o problema do comerciante, não do cliente. Um agente de IA que entende as estruturas de catálogo do Magento e se conecta à sua API REST fecha essa lacuna de expectativas — entregando a experiência de suporte instantânea e orientada por dados que os clientes exigem, independentemente da complexidade estrutural por trás das cenas.

O caminho da instalação até um agente de IA totalmente operacional em uma loja Magento geralmente segue uma progressão clara. Semana um: adicione o trecho de código, deixe o agente rastrear o catálogo e o conteúdo e ative-o para perguntas básicas sobre produtos e políticas. O agente lida imediatamente com "qual é a sua política de devolução?", "vocês enviam para o Canadá?" e "fale-me sobre a Jaqueta Alpine Performance" — a camada de base de conhecimento funciona desde o primeiro dia. Semana dois: conecte a API de status do pedido e os endpoints de verificação de estoque. Agora o agente lida com "onde está meu pedido?" e "isso está em estoque?" — as duas perguntas de suporte de maior volume no ecommerce. Semana três: adicione o processamento de devoluções, a consulta de conta do cliente e quaisquer endpoints especializados que sua loja precise. Ao final do mês, o agente de IA estará lidando com a maior parte do seu volume de suporte autonomamente, seus agentes humanos se concentrarão em problemas complexos que realmente precisam de uma pessoa, e sua fila de suporte parecerá fundamentalmente diferente do que era trinta dias atrás. Não porque você implementou uma plataforma de IA empresarial. Porque você adicionou uma tag de script e apontou algumas ferramentas de API para endpoints que já existiam.