← All Articles

Voce Construiu Seu Catalogo Shopify para Humanos. Agora Ele Precisa Funcionar para Crawlers Agenticos Tambem.

Tony Castillo

Tony Castillo

Published: March 23, 2026

Available in: English | Deutsch | Español | Français | हिन्दी | Italiano | Bahasa Melayu | Nederlands | Polski | Türkçe | Українська

Aqui Esta o Melhor Guia para Comecar a Trabalhar com o Catalog MCP e a Catalog API da Shopify

A Tese

Seu catalogo de produtos Shopify esta sendo lido por dois publicos fundamentalmente diferentes: humanos que navegam na sua vitrine e agentes de IA que consultam seus dados de produtos programaticamente para fazer recomendacoes em nome de outra pessoa.

A maioria das marcas passou anos otimizando para o primeiro publico. Descricoes ricas de produtos, fotografia lifestyle, PDPs otimizadas para conversao. Nada disso ajuda muito o segundo publico.

Este artigo usa um produto real, o creme para olhos Full Orbit da Glossier, para mostrar como essa lacuna se parece na pratica e o que ela significa para marcas que estao pensando em comercio agentico.

A Camada de Infraestrutura que a Maioria das Marcas Ainda Nao Percebeu

A Shopify construiu o Catalog MCP, um servidor Model Context Protocol que serve como a principal infraestrutura de descoberta de produtos para comercio agentico na plataforma Shopify. Ele e construido em torno do Universal Commerce Protocol (UCP), um padrao para como agentes de IA encontram, avaliam e realizam transacoes com produtos.

O Catalog MCP encapsula a Catalog REST API da Shopify e oferece a qualquer agente construido segundo o padrao UCP uma forma de:

  1. Pesquisar em todos os produtos Shopify elegiveis com base em palavras-chave, faixa de preco e local de entrega
  2. Consultar detalhes completos de variantes em produtos especificos, incluindo descricoes, recursos, especificacoes e URLs de checkout

Lojistas Shopify elegiveis ja estao neste catalogo. A questao nao e se seus produtos estao sendo consultados. E o que os agentes encontram quando os consultam.

Agentic storefronts

Your active products are automatically discoverable.

✦
ChatGPT···
Microsoft Copilot···

Review how your product data is sent to the Shopify Catalog for agentic storefronts

A visualizacao de Agentic storefronts no admin da Shopify: ChatGPT e Microsoft Copilot sao as duas primeiras superficies de IA conectadas.

›ChatGPT
More actions ▾
✦

ChatGPT

Free

By selling on this sales channel, you agree to Agentic Storefronts Supplemental Terms

Checkout

Customers complete purchases on your checkout

Products

Publishing

Shopify catalog is used to send product data to this sales channel

Ao clicar no ChatGPT, voce ve os detalhes do canal de vendas: o checkout permanece na sua vitrine e os dados do produto fluem pelo Shopify Catalog.

Ambas as telas sao encontradas em Configuracoes > Canais de vendas no admin da Shopify.

Existem tres caminhos que um agente pode seguir para acessar seu catalogo:

Caminho Escopo Autenticacao Necessaria
Catalog MCP Todos os lojistas Shopify elegiveis globalmente Sim (JWT)
Storefront MCP Apenas uma unica loja Nao
Catalog REST API Todos os lojistas Shopify elegiveis globalmente Sim

A Shopify descreve o Catalog MCP como o caminho recomendado para a maioria das implementacoes de comercio agentico.

Dois Endpoints. Duas Imagens Muito Diferentes.

Quando um agente de IA quer saber sobre um produto na sua loja Shopify, ele tem dois caminhos principais para seus dados. O caminho legado e o endpoint publico /products.json. Ele e acessivel sem autenticacao, estruturado como JSON e a forma padrao como bots e scrapers leem catalogos Shopify ha anos. O caminho moderno e o Catalog MCP e a Catalog API, construidos especificamente para consumo agentico.

Aqui esta a comparacao completa lado a lado do Glossier Full Orbit, extraida diretamente de ambos os endpoints:

Campo /products.json Catalog API Status do Campo na Catalog API
Product ID 8185258410229 gid://shopify/p/5vhkcE78u4c7P2hhO30zEh Obrigatorio
Titulo Full Orbit Full Orbit Obrigatorio
Fornecedor Glossier Glossier Obrigatorio
Descricao Bloco HTML de 4.000 caracteres “A hydrating, brightening eye cream that smooths fine lines and reduces dark circles and puffiness.” (98 caracteres) Gerado por IA (sem controle do lojista)
Proposta de Valor Unica Nao presente “Combines brightening, hydrating, and smoothing effects in one tube-packaged eye cream.” Gerado por IA (sem controle do lojista)
Recurso Principal 1 Nao presente Brightening formula reduces the appearance of dark circles for a more awake look Gerado por IA (sem controle do lojista)
Recurso Principal 2 Nao presente Hydrating ingredients keep the under-eye area moisturized and comfortable Gerado por IA (sem controle do lojista)
Recurso Principal 3 Nao presente Smoothing action helps minimize fine lines for a youthful appearance Gerado por IA (sem controle do lojista)
Recurso Principal 4 Nao presente Depuffing effect soothes and refreshes tired eyes Gerado por IA (sem controle do lojista)
Recurso Principal 5 Nao presente Tube dispenser allows for easy, mess-free application Gerado por IA (sem controle do lojista)
Espec. Tecnica: Tipo de Dispensador Nao presente Tube Gerado por IA (sem controle do lojista)
Espec. Tecnica: Forma do Produto Nao presente Cream Gerado por IA (sem controle do lojista)
Espec. Tecnica: Efeitos para Pele Nao presente Brightening, Hydrating, Smoothing, Anti-dark circle, Anti-puffiness Gerado por IA (sem controle do lojista)
Espec. Tecnica: Marca Nao presente Glossier Gerado por IA (sem controle do lojista)
Secondhand Nao presente False Gerado por IA (sem controle do lojista)
Descricao da Variante Nao presente 2.312 caracteres em texto simples (HTML removido) Opcional
Preco $28.00 $28.00 USD Obrigatorio
Disponivel para Venda Nao presente True Obrigatorio
URL de Checkout Nao presente URL direta de checkout da variante Obrigatorio
URL da Variante Nao presente URL da pagina do produto com parametro de variante Obrigatorio
Avaliacao Nao presente Nao presente Opcional
Quantidade de Imagens 10 10 Obrigatorio
SKU FOE-000-00-00 Nao presente —
Codigo de Barras 810086254095 Nao presente —
Tags 11 tags internas (bfcm-eligible, pricing_export, etc.) Nao presente —
Tipo de Produto Skincare Nao presente —

Gerado por IA (sem controle do lojista) significa que a IA da Shopify gera o valor. Os lojistas nao tem mecanismo direto para declarar ou sobrescrever esses campos. Campos Obrigatorios sao controlados pelo lojista ou pela plataforma e tem presenca garantida. Campos Opcionais estao presentes quando disponiveis. Campos marcados com — existem apenas no /products.json e nao tem equivalente na Catalog API.

O endpoint /products.json entrega ao agente um bloco de HTML mais campos de logistica interna. A Catalog API entrega um resumo estruturado, livre de tags internas, focado no que um agente precisa para fazer uma recomendacao e concluir uma compra.

Um agente tentando responder “qual e um bom creme para olhos leve para olheiras” precisa trabalhar significativamente mais quando tudo que tem e HTML bruto. Os resultados tem mais chance de perder seu posicionamento real.

Como a Descricao em HTML Realmente Aparece para um Agente

A descricao HTML do Full Orbit comeca assim, exatamente como aparece no /products.json:

<p class="pv-details__info-item pv-details__tagline">
  <strong>A 360° reset for every, single eye.</strong>
</p>
<p id="description-item" class="pv-details__info-item">
  A multi-benefit, 360° eye cream that tackles the concerns
  you care about mostâimmediately hydrating for up to 24 hours...

Antes que um agente consiga extrair uma unica frase util, ele precisa remover nomes de classes CSS, tags span, declaracoes de charset inline e artefatos de codificacao quebrados como ° e â. Os dados de estudos clinicos estao embutidos inline junto com as alegacoes do produto. Os destaques de ingredientes estao em itens de lista misturados com copy de marketing.

Compare isso com o que a Catalog API retorna como descricao curta:

“A hydrating, brightening eye cream that smooths fine lines and reduces dark circles and puffiness.”

Sao 98 caracteres. E direto, texto simples e imediatamente analisavel. Um agente pode usar isso numa recomendacao sem nenhum processamento.

A lacuna nao e apenas sobre comprimento. E sobre densidade de sinal. A descricao da Catalog API diz ao agente exatamente o que o produto faz. A descricao em HTML faz o agente adivinhar.

O Problema dos Campos “Inferred”: Quando a IA da Shopify Escreve o Copy do Seu Produto

Aqui esta a parte com a qual a maioria das marcas ainda nao lidou.

A Catalog API da Shopify marca certos campos com o rotulo “Inferred” na sua documentacao de referencia. Esses sao campos que a IA da Shopify gera automaticamente quando um lojista nao os forneceu explicitamente. A documentacao observa que campos inferidos podem nem sempre estar presentes e que a precisao varia dependendo dos dados de produto disponiveis.

Aqui estao os campos exatos marcados como Inferred nos endpoints de Search e Lookup:

Campo Endpoint Descricao
description Search + Lookup Descricao detalhada do produto
uniqueSellingPoint Search + Lookup A proposta de valor distintiva
topFeatures Search + Lookup Array de recursos principais do produto
techSpecs Search + Lookup Array de especificacoes tecnicas
options Search + Lookup Array de opcoes/variantes do produto
attributes Search Atributos do produto como pares nome-valor
secondhand Search + Lookup Se a variante e de segunda mao

Para contraste, os campos que a Shopify marca como Obrigatorios sao os transacionais: price, availableForSale, checkoutUrl, variantUrl, shop. A Shopify controla a camada de transacao. A camada de descricao e sua para preencher, ou a IA da Shopify preenche.

Os campos mais importantes para recomendacoes de agentes, description, uniqueSellingPoint, topFeatures e techSpecs, sao todos gerados por IA sem mecanismo de controle pelo lojista.

Se sua marca nao preencheu valores limpos e estruturados para esses campos, a versao voltada para agentes do seu produto esta sendo escrita pela IA da Shopify. Nao por voce.

Os dados da Catalog API do Full Orbit na nossa comparacao mostram todos esses campos preenchidos. Olhando os valores, eles se dividem em dois grupos que sugerem origens diferentes.

Alguns parecem dados estruturados de produto que a Glossier provavelmente forneceu diretamente:

  • secondhand: False, um sinalizador binario, nao algo que voce geraria a partir de uma descricao
  • techSpecs: Brand: Glossier, metadados basicos do produto
  • techSpecs: Dispenser Type: Tube, um atributo fisico do produto
  • techSpecs: Product Form: Cream, um atributo de categoria do produto

Outros parecem copy gerado a partir da descricao HTML:

  • uniqueSellingPoint: "Combines brightening, hydrating, and smoothing effects in one tube-packaged eye cream.", uma frase sintetizada, nao um campo padrao de produto
  • topFeatures, cinco declaracoes de beneficios que espelham de perto a linguagem na descricao HTML mas sao reestruturadas em linhas discretas
  • description: "A hydrating, brightening eye cream that smooths fine lines and reduces dark circles and puffiness.", uma versao comprimida em texto simples do paragrafo de abertura HTML

Esse padrao sugere que as especificacoes tecnicas e sinalizadores binarios podem vir da taxonomia de produtos da Shopify e campos padrao de produto, enquanto os campos mais textuais (USP, recursos principais, descricao curta) sao mais provavelmente gerados a partir da descricao do produto. Nenhum dos dois e confirmado: apenas a Glossier e a Shopify conhecem o mecanismo de entrada real. Mas os dados sao consistentes com essa divisao.

De qualquer forma, a saida do Full Orbit e coerente e util para um agente. O risco esta em produtos onde o material de origem e mais fino. Considere o que acontece com:

  • Um produto onde a descricao HTML e principalmente linguagem de marketing com poucos detalhes especificos
  • Um produto novo onde a descricao ainda nao foi totalmente desenvolvida
  • Um produto reformulado onde o copy antigo ainda esta no ar
  • Um produto onde seu posicionamento e sutil e requer contexto para transmitir com precisao

Em cada um desses casos, uma descricao inferida por IA pode perder completamente o ponto. Essa e a descricao que os agentes usam quando recomendam seu produto a alguem.

Voce nao tem a chance de revisar os valores dos campos inferidos antes que eles sejam servidos aos agentes. A unica maneira de garantir que os agentes trabalhem a partir de descricoes precisas e controladas pela marca e preencher os campos voce mesmo.

Como os Agentes Realmente Encontram Seus Produtos: Search e Depois Lookup

O fluxo de trabalho do Catalog MCP segue um padrao de duas etapas que tem implicacoes diretas em como seus dados de catalogo sao usados.

Etapa 1: Search. Um agente traduz um prompt do usuario como “encontre um creme para olhos leve que ajude com olheiras por menos de $30” numa consulta de busca no Catalog. Os resultados sao agrupados por Universal Product ID (UPID), o que evita duplicatas quando o mesmo produto e vendido por multiplos lojistas. Cada resultado de busca inclui:

  • Titulo e descricao do produto
  • Faixa de preco entre todos os vendedores
  • Opcoes disponiveis (tamanho, tom, etc.)
  • Uma lista de lojistas com seus precos especificos e URLs de checkout

Etapa 2: Lookup. Usando o UPID do resultado de busca, o agente recupera detalhes completos da variante para o produto especifico, incluindo descricoes completas, recursos principais, especificacoes tecnicas, todos os precos no nivel da variante e URLs de checkout para a oferta de cada lojista.

A implicacao do agrupamento por UPID vale uma pausa. Se seu produto e o mesmo SKU vendido por multiplos lojistas Shopify (atraves de atacado, revendedores autorizados ou acordos de marketplace), essas ofertas sao apresentadas juntas num unico resultado agrupado, com comparacao de precos. O agente (e o usuario) pode ver todos os precos disponiveis de uma vez. A qualidade do catalogo afeta nao apenas se seu produto aparece, mas se sua oferta e a selecionada quando multiplos lojistas estao vendendo o mesmo item.

Por Que Isso Importa Conforme os Agentes Se Tornam Compradores

A mudanca acontecendo agora e que agentes de IA estao passando de assistentes de pesquisa para participantes de transacoes. Agentes de compras nao estao apenas exibindo informacoes. Eles estao cada vez mais capazes de iniciar compras, usando exatamente o tipo de URL de checkout no nivel da variante que a Catalog API retorna.

Quando um agente pode adicionar um produto ao carrinho ou gerar um link de checkout, a qualidade dos dados que ele tem sobre seu produto afeta diretamente se seu produto e recomendado, e se a recomendacao e precisa.

Tres coisas estao em jogo:

Descoberta. Se um agente nao consegue analisar com confianca o que seu produto faz e para quem ele e, ele nao vai exibi-lo em resposta a consultas relevantes. Campos limpos e estruturados dao aos agentes a confianca para fazer uma recomendacao.

Precisao. Um agente trabalhando a partir de HTML pode gerar seu proprio resumo do seu produto com base no que consegue extrair. Esse resumo pode omitir alegacoes principais, caracterizar erroneamente o caso de uso ou descartar dados clinicamente validados inteiramente. Voce nao controla o que o agente diz sobre seu produto, mas controla os insumos com os quais ele trabalha.

Conversao. A Catalog API inclui uma URL direta de checkout para cada variante. Agentes com capacidade transacional precisam exatamente disso: um caminho legivel por maquina da recomendacao ate a compra. Se esse campo nao esta preenchido e preciso, o caminho de conversao se quebra antes mesmo de comecar.

Os Campos que Direcionam as Decisoes dos Agentes

Nem todos os campos do catalogo tem o mesmo peso para endpoints agenticos. Com base em como agentes de IA processam e classificam dados de produtos, estes sao os que mais importam:

Campo Nome do Campo na API Status Por Que Importa
Descricao curta description Gerado por IA (sem controle do lojista) Sinal principal para correspondencia de consulta e copy de recomendacao
Proposta de valor unica uniqueSellingPoint Gerado por IA (sem controle do lojista) Diferencia seu produto num contexto de comparacao
Recursos principais topFeatures Gerado por IA (sem controle do lojista) Mapeia para consultas de intencao do usuario como “melhor para olheiras”
Especificacoes tecnicas techSpecs Gerado por IA (sem controle do lojista) Permite filtragem por formato, ingrediente ou tipo de dispensador
Atributos do produto attributes Gerado por IA (sem controle do lojista) Pares nome-valor usados para filtragem estruturada
Disponivel para venda availableForSale Obrigatorio Agentes depriorizam ou pulam itens fora de estoque
URL de checkout checkoutUrl Obrigatorio Necessario para qualquer capacidade transacional do agente
URL da variante variantUrl Obrigatorio Caminho alternativo quando checkout nativo nao esta disponivel

Os campos inferidos sao os que descrevem o que seu produto e e por que alguem deveria compra-lo. Os campos obrigatorios sao os que concluem a transacao. A Shopify garante o segundo grupo. O primeiro grupo e sua responsabilidade.

O Que Auditar no Seu Catalogo Hoje

Se voce e um proprietario de marca gerenciando um catalogo Shopify, ha algumas coisas especificas que vale a pena verificar agora, antes que agentes de IA se tornem uma parcela maior do seu trafego e antes que a IA transacional se torne a norma.

Verifique sua descricao curta. Cada produto tem um resumo conciso em texto simples que comeca com o que o produto faz? Nao seu slogan. Nao seu gancho de marketing. Uma descricao funcional que um agente pode usar para combinar o produto com a solicitacao de um usuario.

Verifique seus campos de recursos. Voce esta preenchendo campos discretos de recursos principais, nativamente na Shopify ou atraves de um metafield ou feed da Catalog API? Se toda a informacao do seu produto esta num unico bloco de descricao HTML, voce esta dando aos agentes um bloco indiferenciado para trabalhar.

Verifique seus dados de disponibilidade. Produtos fora de estoque que ainda aparecem como disponiveis criam erros de recomendacao. Agentes que recomendam produtos que os usuarios nao podem comprar erodem a confianca no agente e na sua marca.

Verifique suas URLs de checkout. Se voce esta integrado com qualquer feed de compras ou plataforma de comercio de IA, verifique se as URLs de checkout no nivel da variante estao sendo preenchidas com precisao. Um link de checkout quebrado ou generico quebra completamente o caminho de conversao.

Verifique suas descricoes de variantes. Paginas de produtos frequentemente tem descricoes detalhadas que nao sao levadas ao nivel da variante. Para produtos com multiplos SKUs, agentes podem estar consultando no nivel da variante e encontrando campos vazios.

Verifique seus campos inferidos. O Catalog MCP da Shopify sinaliza campos como “Inferred” quando os lojistas nao os preencheram explicitamente. Para os campos que os agentes mais valorizam (descricao curta, proposta de valor unica, recursos principais), verifique se sua marca preencheu valores explicitos em vez de deixa-los para inferencia de IA. Nao ha mecanismo para revisar ou corrigir valores inferidos antes que sejam servidos aos agentes.

Verifique suas fontes de Catalog Mapping. Se voce esta no Plano Agentico, o Shopify Catalog Mapping (Configuracoes > Shopify Catalog Mapping) permite redirecionar a fonte de tres campos-chave para um metafield ou metaobject em vez do atributo padrao de produto. Esses sao os insumos que alimentam o pipeline de inferencia por ML.

Product fields

Change the sources for standard fields on the Shopify Catalog

Shopify standards i
Source i
Product title
Product title ⇅
Product description
Product description ⇅
Product category
Product category ⇅

Shopify Catalog Mapping (Configuracoes > Shopify Catalog Mapping). Cada fonte pode ser redirecionada para um metafield ou metaobject. Isso controla o que entra no pipeline de ML, nao o que o pipeline produz.

A Mudanca Mais Ampla: Catalogo como Infraestrutura

Durante a maior parte da era Shopify, o catalogo de produtos era material de vendas, conteudo que voce escrevia para humanos que navegavam na sua vitrine. A PDP era o ponto final.

Esse modelo esta mudando. Seu catalogo agora e infraestrutura que multiplos tipos de consumidores leem: humanos na sua vitrine, crawlers de motores de busca, motores de comparacao de precos e, cada vez mais, agentes de IA fazendo recomendacoes e compras em nome dos usuarios.

As marcas que investem na qualidade do catalogo agora (campos estruturados, texto limpo, metadados completos) terao uma vantagem cumulativa conforme o comercio agentico escala. As marcas que nao investirem verao seus produtos sendo resumidos de forma imprecisa, depriorizados por agentes que nao conseguem analisar os dados ou ausentes das recomendacoes por completo.

O exemplo da Glossier e instrutivo nao porque a Glossier tenha feito algo errado. Suas descricoes HTML sao ricas, detalhadas e claramente escritas para leitores humanos. E instrutivo porque mostra que conteudo escrito para leitura humana e dados estruturados para consumo de agentes sao duas coisas diferentes. Ambos importam agora.

Audite Seu Catalogo para Prontidao em Comercio Agentico

Referencia da Documentacao da Shopify

As seguintes paginas da documentacao para desenvolvedores da Shopify sao as fontes primarias para as informacoes sobre Catalog MCP e Catalog API neste artigo.

Visao geral do Catalogo

Referencias do MCP

Referencias da Catalog REST API

  • Catalog REST API overview, autenticacao, limites de taxa e indice de endpoints
  • Search endpoint, schema completo de campos para resultados de Search, incluindo quais campos sao marcados como Inferred
  • Lookup endpoint, schema completo de campos para respostas de detalhes de produtos, incluindo quais campos sao marcados como Inferred
  • Lookup by variant, schema de lookup no nivel da variante
  • Bulk lookup, recuperacao de detalhes de produtos em lote

Perguntas Frequentes

O que e comercio agentico?

Comercio agentico refere-se a agentes de IA que pesquisam, comparam e recomendam produtos autonomamente em nome dos usuarios, e cada vez mais, concluem compras.

  • Agentes de compras leem dados de produtos programaticamente, nao navegando numa vitrine
  • Eles geram recomendacoes baseadas em campos estruturados como descricoes, recursos e especificacoes
  • Agentes transacionais podem iniciar checkouts usando URLs de checkout no nivel da variante
  • A qualidade dos seus dados de produto afeta diretamente se seus produtos sao recomendados

Como os agentes de compras de IA leem um catalogo Shopify?

O Catalog MCP da Shopify e o caminho principal para comercio agentico. Ele segue um fluxo de Search, depois Lookup.

  • Catalog MCP: O caminho recomendado. Pesquisa todos os lojistas Shopify elegiveis globalmente; requer autenticacao JWT
  • Catalog REST API: Mesmos dados do MCP, consultaveis diretamente
  • Storefront MCP: Com escopo de uma unica loja; sem autenticacao necessaria; util para agentes de marca unica
  • /products.json: Endpoint publico legado; retorna HTML bruto; sem recursos estruturados ou URLs de checkout
  • Agentes usando o Catalog MCP seguem um fluxo de duas etapas: Search por palavra-chave/preferencia para obter UPIDs, depois Lookup por UPID para recuperar detalhes completos da variante

Quais campos de produto importam mais para agentes de IA?

Os campos de maior sinal para endpoints agenticos sao aqueles que mapeiam diretamente para como os agentes combinam produtos com a intencao do usuario.

  • Descricao curta em texto simples (o exemplo do Full Orbit tem 98 caracteres)
  • Proposta de valor unica
  • Recursos principais discretos
  • Especificacoes tecnicas estruturadas
  • Status de disponibilidade
  • URL de checkout no nivel da variante

Importa se minhas descricoes de produtos sao escritas em HTML?

Sim. A marcacao HTML adiciona ruido que os agentes precisam remover antes de processar.

  • Uma descricao HTML de 4.000 caracteres com classes CSS e tags inline e mais dificil de analisar do que um resumo de 100 caracteres em texto simples
  • A Catalog API remove o HTML mas nao pode corrigir descricoes que sao semanticamente confusas depois que a marcacao e removida
  • Descricoes escritas para apresentacao visual podem nao ser eficazes quando renderizadas como texto simples
  • As melhores descricoes sao claras e escaneaveis tanto em contextos de leitura humana quanto de maquina