Shopify

Esta página é para quem vende no Shopify e quer o agente respondendo “cadê meu pedido” e “vocês têm esse produto?” sem passar por uma pessoa.

Comece pelo aviso — ele muda o que você pode planejar.

Atenção: a instalação pela loja não funciona nesta versão. As telas que rodariam dentro do painel do Shopify vêm de um módulo separado que está vazio neste sistema — conferi os dois diretórios do módulo e não há um único arquivo neles. As rotas continuam registradas, mas não têm o que renderizar.

O que existe e funciona é a outra metade: o back-end e as ferramentas do agente. Se uma loja estiver conectada, o agente consulta produto e pedido normalmente. O que não existe é o caminho de tela para conectar essa loja.

O que o agente sabe fazer

Seis ferramentas, e é o maior conjunto do sistema:

Ferramenta	O que faz
Listar produtos	Traz uma lista de produtos da loja
Ver um produto	Detalhe de um produto específico
Buscar produtos	Busca por texto, com filtro de preço mínimo, preço máximo e marca
Buscar pedidos	Por e-mail do cliente, por número do pedido ou por texto livre
Ver o estado de um pedido	Situação de pagamento e de envio
Recomendar produtos	Sugere semelhantes a partir de um produto, de um tipo ou de etiquetas

Alguns detalhes que importam no atendimento:

• A busca de produto só devolve produto ativo e com estoque. O agente não oferece o que você não pode vender.
• A busca de pedido exige pelo menos um critério. Sem nenhum, o agente é instruído a perguntar ao cliente o número do pedido ou o e-mail em vez de inventar uma busca.
• O número do pedido é reconhecido com ou sem o # na frente.
• A recomendação usa até 3 etiquetas do produto de referência e nunca recomenda o próprio produto de volta.
• Os produtos consultados ficam em cache por 5 minutos por conversa, e só um resumo enxuto de cada produto vai para o modelo — id, título, preço, moeda, marca, tipo, estoque e etiquetas. A ficha inteira não é enviada.

Do lado do agente, no painel, existe a seção Shopify — orders & products (“Shopify — pedidos e produtos”), com o interruptor Enable Shopify Features (“Ligar recursos do Shopify”) e a explicação “Enable Shopify product information and features for this agent”.

Atenção: esse interruptor fica inerte enquanto não houver uma loja conectada. A seção mostra “Shopify is not connected” e um botão Connect Shopify (“Conectar o Shopify”) — que leva ao caminho descrito abaixo.

O que a tela de integrações oferece hoje

Em Settings → Integrations (“Configurações → Integrações”) existe o cartão Shopify, com a legenda E-COMMERCE e a descrição “Install from Shopify App Store to integrate your store with ChatterMate.”

O botão dele não é Connect como nos outros — é Install (“Instalar”). E clicando nele, abre uma aba levando ao painel de administração do Shopify, para instalar o aplicativo publicado.

Atenção: esse botão aponta para o aplicativo hospedado do ChatterMate, com o identificador de aplicativo deles. Numa instalação própria do ChatMade, ele não leva ao seu aplicativo. E, mesmo instalando, a tela de retorno é uma das que não renderizam nesta versão. Não trate esse botão como um caminho funcional.

Para desconectar, o cartão abre o painel de aplicativos da sua loja com o recado de que a desinstalação precisa ser feita lá.

O que é preciso para fazer funcionar mesmo assim

Se você é desenvolvedor e quer as ferramentas do agente funcionando na sua instalação, o caminho é este — e é trabalho de integração, não de configuração:

1. Criar o seu próprio aplicativo no Shopify Partners.
2. Preencher SHOPIFY_API_KEY e SHOPIFY_API_SECRET no .env do backend, e VITE_SHOPIFY_API_KEY no .env do frontend.
3. Fazer a troca de token: a API POST /api/v1/shopify/exchange-token recebe um token de sessão do App Bridge do Shopify e devolve um token de acesso permanente para a loja, que é o que as ferramentas usam.
4. Ligar a loja à sua organização e ao agente pelas rotas de configuração da API.

Não há rota clássica de instalação por OAuth (/install e /callback) no back-end: todo o caminho de instalação foi desenhado assumindo o aplicativo embutido no painel do Shopify — que é justamente a parte ausente.

A versão da API do Shopify usada nas consultas é a 2025-10, fixa no código.

O que não existe nesta versão

Sendo explícito, para você não planejar em cima do que não tem:

• Não há tela de conectar loja que funcione.
• Não há caixa de entrada embutida dentro do painel do Shopify.
• Não há seleção de agente dentro do Shopify.

O widget de chat na sua loja, esse funciona — ele é o mesmo widget do site, só embarcado na vitrine.

Próximo passo

Se o que você quer é o agente respondendo sobre produto usando o seu catálogo, o caminho que funciona hoje é a base de conhecimento. Se o que você precisa é abrir chamado quando o pedido dá problema, veja Chamados.