Ações do Shopify

Conecte uma loja Shopify para que seu agente possa pesquisar seu catálogo e consultar o status de pedidos no chat.

Conecte uma loja Shopify ao seu agente, e ele poderá responder perguntas sobre produtos usando seu catálogo em tempo real e consultar o status de um pedido durante uma conversa. Isso é diferente de colocar o widget de chat na sua loja — veja incorporação do Shopify para isso.

Conecte Sua Loja Primeiro

As duas ações precisam de uma loja conectada.

Acesse a aba Ações do seu agente
Abra Integrações e encontre o card Shopify
Digite o domínio da sua loja no formato store-name.myshopify.com
Conclua a tela de consentimento do Shopify

O card então mostra o estado da conexão e permite Reconectar ou Desconectar. Se a conexão precisar de atenção, um banner âmbar aparece com um aviso para reconectar.

A conexão é por agente. Cada agente conecta sua própria loja, então um agente que deve responder por uma loja diferente recebe sua própria conexão, em vez de compartilhar uma.

Qual Acesso é Solicitado

Na tela de consentimento, o Agentkit solicita exatamente dois scopes de leitura:

Scope	Usado para
`read_products`	Pesquisar seu catálogo
`read_orders`	Consultar o status de um pedido

Nenhum scope de escrita é solicitado. A conexão também usa o token offline padrão do Shopify — a solicitação omite deliberadamente a opção de concessão por usuário — para que o agente continue funcionando depois que a pessoa que conectou a loja sair.

Esses são os scopes que a implementação atual solicita. O Shopify decide separadamente quais dados um app tem permissão de receber: alguns campos de cliente e pedido são protegidos, e receber read_orders não garante, por si só, que todos os campos sejam retornados.

As Duas Ações

Cada ação é adicionada e configurada individualmente em Ações.

Pesquisar produtos

Permite que o agente pesquise o catálogo da loja conectada quando um visitante pergunta sobre produtos, preços ou disponibilidade. É possível restringir os resultados por consulta, um preço máximo opcional e um limite de resultados.

Os resultados incluem apenas produtos ativos publicados na sua loja virtual. A disponibilidade vem do estoque total do produto no Shopify e inclui produtos que não têm controle de estoque.

A instrução padrão de "quando usar" é "Use when the user wants to find products, compare prices, or check whether an item is available." Edite-a para corresponder à forma como seus visitantes realmente perguntam.

Consultar status do pedido

Consulta um único pedido. O visitante deve fornecer tanto o número do pedido quanto o e-mail do checkout, e ambos devem corresponder ao mesmo pedido antes que algo seja retornado.

Esse pareamento é uma medida de privacidade: um número de pedido sozinho é fácil de adivinhar ou ouvir por acaso, então nunca é suficiente. Se o pedido não existir, ou se o e-mail não corresponder ao pedido, o agente recebe a mesma resposta genérica "We could not find an order matching those details." — ele não consegue saber qual dos dois estava errado, e o visitante também não.

Pedidos mais antigos podem gerar a mesma resposta de "não encontrado" mesmo quando o número e o e-mail estão corretos: o Agentkit solicita o scope padrão read_orders do Shopify, que cobre os pedidos recentes da loja (aproximadamente os últimos 60 dias), e não o histórico completo de pedidos, aprovado separadamente. Se consultas de pedidos antigos forem importantes para sua loja, espere ter que direcionar visitantes com pedidos antigos para o seu canal de suporte.

A instrução padrão de "quando usar" é "Use when the user asks for an order status or tracking details and can provide the order number and checkout email."

Duas Condições para Ativar uma Ação

Ambas devem ser verdadeiras antes que uma ação possa ser ativada:

Uma loja conectada - sem uma, o botão de ativação mostra um aviso inline com link para Ações → Integrações
Um plano pago - o mesmo requisito de Custom API, Web Search, Ler links de documentos e as ações de agendamento

Você ainda pode criar, editar e salvar qualquer uma das ações enquanto estiver desativada, mesmo sem nenhum dos pré-requisitos. As condições se aplicam apenas para ativá-la.

Solução de Problemas

OAuth concluído, mas as consultas de pedido não retornam nada. Verifique o formato do número de pedido que sua loja usa e confirme se o e-mail que você está testando é o e-mail de checkout daquele pedido. Em seguida, verifique a elegibilidade do app para dados protegidos de cliente e pedido na loja — o acesso a esses dados precisa ser necessário para o app e pode ser restringido pelo Shopify. Solicitar scopes mais amplos não muda isso, e reconectar não garante aprovação.

O agente responde com base no conteúdo de treinamento em vez do catálogo. Refine a instrução de "quando usar" para que perguntas sobre produtos, preços e disponibilidade sejam claramente direcionadas para a ação de pesquisa.

O card mostra um aviso para reconectar. A autorização armazenada não é mais utilizável. Clique em Reconectar e conclua a tela de consentimento novamente. Reconectar restaura a conexão, mas não as ações: quando a autorização armazenada falha, as duas ações do Shopify são desativadas automaticamente, e a tela de consentimento não as reativa. Depois de reconectar, volte para Ações e reative cada ação que você quiser ativa.