A maioria dos comerciantes trata seu catálogo de produtos como dados, um corpo de registros armazenados em um PIM, sincronizado com uma vitrine, exportado como um feed. Essa estrutura não é mais suficiente. Um agente não consome seus dados como dados; ele consome seu catálogo como se fosse uma API. Uma vez que você percebe a mudança, a prática operacional muda de acordo.
A estrutura
APIs têm quatro propriedades que os catálogos geralmente não têm: contrato, versionamento, documentação e garantias de confiabilidade. Os agentes exploram todas as quatro. Se seu catálogo não as possui, o agente compensa com suposições, scraping e confiança reduzida, o que penaliza sua visibilidade.
Contrato
Um contrato de API define quais campos existem, quais tipos eles contêm, quais intervalos eles aceitam. Um contrato de catálogo significa:
- Todo produto tem campos de identificação (GTIN, MPN+Marca).
- Campos de preço são tipados (número + moeda), não strings.
- A disponibilidade é enumerada (em_estoque / fora_de_estoque / pré_venda / pedido_pendente).
- As políticas são objetos estruturados, não prosa.
- Atributos personalizados têm tipos e unidades declarados.
O contrato pode residir em vários lugares: o JSON-LD em seus PDPs, seu esquema de feed e, idealmente, um esquema legível por máquina publicado em uma URL estável. Trate-o como fonte de verdade.
Versionamento
APIs versionam. Catálogos raramente o fazem. O resultado: quando um comerciante muda o significado de um atributo ("Tempo de envio" costumava significar manuseio + trânsito, agora apenas trânsito), todo consumidor a jusante quebra silenciosamente. Agentes que armazenaram em cache interpretações mais antigas estão errados.
Um contrato de catálogo deve ter um número de versão. Mudanças que quebram a compatibilidade devem aumentá-lo. Adições que não quebram a compatibilidade devem ser claras. Depreciações devem ser anunciadas. A disciplina custa pouco e evita o modo de falha silenciosa mais comum em operações de feed.
Documentação
Documentação para um catálogo significa:
- Uma descrição pública de cada atributo que você expõe.
- Convenções de unidades (cm vs polegadas, gramas vs oz).
- Valores enumerados e seus significados (estados de disponibilidade).
- SLAs de atualização ("inventário atualizado a cada 10 minutos").
- Esquemas de política (quais campos sua estrutura de devoluções contém).
A maioria dos comerciantes não escreve nada disso. Os líderes publicam. Fazer isso alinha mercados, parceiros afiliados, agentes e suas próprias equipes internas.
Confiabilidade
APIs se comprometem com a confiabilidade. Os catálogos também deveriam. Os dois compromissos mensuráveis:
- Paridade entre as superfícies (feed, PDP, checkout). A inconsistência é tratada pelos agentes como falta de confiabilidade.
- Atualização: uma cadência de atualização declarada que você cumpre.
"Nosso feed é atualizado a cada 15 minutos" é um compromisso. "Atualizamos o feed quando lembramos" é um modo de falha que os agentes medem.
Implicações para as operações
- Tenha um registro de alterações do catálogo. Publique-o onde parceiros e agentes possam encontrá-lo. Mesmo um simples arquivo Markdown datado em
/catalog/changelogé melhor do que o silêncio. - Alinhe as fontes. O PIM é a fonte da verdade. O feed e o PDP renderizam a partir dele. Qualquer divergência é um bug.
- Tipifique seus atributos personalizados. Se você tem "Warranty_Length" como uma string de formato livre, converta para um inteiro com unidades.
- Exponha um endpoint de leitura. Se os orquestradores de agentes quiserem chamá-lo diretamente (via MCP, por exemplo), publique um endpoint de catálogo simples.
- Meça a paridade. Trabalho noturno: amostre 100 SKUs, compare feed vs PDP vs checkout, alerte sobre deltas >1%.
A mudança de mentalidade
"Catálogo" soa como um artefato estático. "API" soa como um sistema vivo com usuários. Uma vez que você vê seu catálogo como um sistema vivo com usuários externos, usuários que o citarão, compararão e transacionarão com você, o nível de disciplina ambiente aumenta. Os campos são nomeados melhor. As unidades são explicitamente declaradas. As depreciações são anunciadas. A paridade é medida. Esse é o objetivo de toda a estrutura.
Para onde ir em seguida
- Leia catálogos de produtos para IA para o formato de dados alvo.
- Internalize as melhores práticas.
- Aplique a disciplina através da lista de verificação de prontidão do comerciante.