Para desenvolvedores e agentes de IA

Esta página reúne o que desenvolvedores, integradores e agentes de IA precisam para usar o catálogo e o checkout da Modern Mood por código. Tudo o que é leitura funciona sem cadastro, sem chave de API e sem token.

Comece por aqui

• /agents.md — instruções canônicas para agentes: quando usar a loja, permissões, endpoints, formato de erro e limites.
• /llms.txt e /llms-full.txt — versões espelhadas do mesmo documento.
• /sitemap.xml — índice de sitemaps com produtos, coleções, páginas e blog.

Catálogo e busca (somente leitura, sem autenticação)

Preços são retornados em BRL. Cacheie as leituras de catálogo: preço e disponibilidade mudam.

Representação em markdown

Envie Accept: text/markdown e a mesma URL devolve o conteúdo em markdown, com Content-Type: text/markdown. Navegadores continuam recebendo HTML.

Comércio para agentes (UCP / MCP)

A loja implementa o Universal Commerce Protocol:

• Descoberta: GET /.well-known/ucp — versões suportadas, serviços, capacidades e meios de pagamento.
• Endpoint MCP: POST /api/ucp/mcp com Content-Type: application/json (JSON-RPC 2.0).

Ferramentas disponíveis (descubra os schemas tipados com tools/list):

• Catálogo: search_catalog, lookup_catalog, get_product
• Carrinho: create_cart, get_cart, update_cart, cancel_cart
• Checkout: create_checkout, get_checkout, update_checkout, complete_checkout, cancel_checkout
• Pedidos: get_order

Toda chamada precisa identificar o agente em meta.ucp-agent.profile — uma URL HTTPS pública com o perfil do agente. O pagamento exige aprovação do comprador no momento da compra: agentes não finalizam pagamento sozinhos.

Erros

O endpoint MCP responde JSON-RPC 2.0 com erro estruturado — nunca HTML:

{
  "jsonrpc": "2.0",
  "id": 3,
  "error": {
    "code": -32001,
    "message": "UCP discovery failed",
    "data": {
      "code": "profile_unreachable",
      "content": "Unable to fetch agent profile: Http error",
      "continue_url": "https://www.modernmood.com.br/"
    }
  }
}

Ramifique por error.data.code (estável), não pela mensagem. Em 429, aplique backoff exponencial com jitter.

Especificação OpenAPI

O contrato legível por máquina fica em /openapi.json (OpenAPI 3.1), com operationId, parâmetros tipados, schemas de resposta e a lista de escopos (x-permission-scopes) para pedir acesso mínimo.

Ferramentas e CLI

A Modern Mood não publica CLI próprio: a integração é feita por UCP/MCP, pelos endpoints JSON e pelo CLI e pelas APIs da Shopify para operações administrativas.

Políticas e limites

• Uso permitido segundo os Termos de Serviço e a Política de Privacidade.
• O endpoint MCP tem limite por IP. Respeite 429 e evite varreduras agressivas.
• Não complete pagamento sem consentimento explícito do comprador.

Falar com a gente

Dúvidas de integração, parceria ou uso em produção: entre em contato. Para atendimento sobre pedidos, informe o número do pedido e o nome usado no cadastro — respondemos em até 1 dia útil.