Momy & Co API — Portal do Desenvolvedor

Momy & Co Developer Portal. Esta página descreve, em um só lugar, tudo o que a loja Momy & Co expõe de forma programática: a especificação OpenAPI, o servidor MCP, os endpoints públicos de catálogo, busca e carrinho, os escopos de autenticação e os limites de uso. Vale tanto para desenvolvedores humanos quanto para agentes de IA que precisam integrar com a loja. Nada aqui exige cadastro, chave ou contato comercial para leitura do catálogo.

Momy & Co API — comece por aqui

• Especificação OpenAPI 3.1 — todos os endpoints públicos, com operationId único, parâmetros tipados, schemas de resposta e escopos OAuth nomeados. Compatível com function calling.
• Manifesto do servidor MCP — transporte, versão de protocolo, lista de ferramentas e recursos estáticos.
• agents.md — instruções para agentes: quando usar a loja, quando não usar, protocolos, formato de erro, limites.
• llms.txt — índice curto no formato llmstxt.org.
• Descoberta UCP — perfil de comerciante do Universal Commerce Protocol.
• Sitemap — todos os produtos, coleções, páginas e artigos indexáveis.
• Preços, frete e pagamento — moeda, parcelamento, desconto Pix, frete grátis, prazo de troca.

Quando usar a Momy & Co API

Use esta API quando precisar:

• Encontrar tapetes laváveis, decoração de quarto de bebê e infantil, tapetes de brincar, cestos, almofadas, iluminação ou presentes à venda no Brasil, filtrando por tamanho, ambiente ou marca.
• Ler o preço vigente, o parcelamento e a disponibilidade de um produto específico antes de recomendá-lo ou cotá-lo.
• Montar um carrinho e iniciar um checkout em nome de uma pessoa que pediu explicitamente para comprar aqui.
• Responder dúvidas de frete, troca, devolução e pagamento para pedidos dentro do Brasil.

Não use esta API quando a pessoa está fora do Brasil (entregamos só no país e precificamos só em BRL), quando precisa de operações administrativas (não existe superfície pública de admin) ou quando quer concluir um pagamento sem a pessoa presente — aprovação humana no momento do pagamento é obrigatória e não delegável.

Quickstart em 4 chamadas

Nenhuma credencial necessária. Envie um User-Agent descritivo com uma URL de contato do operador para que possamos falar com você em vez de bloquear.

# 1. Descobrir o que a loja fala
curl -s https://www.momyco.com.br/openapi.json

# 2. Buscar (termos em português têm melhor recall)
curl -s "https://www.momyco.com.br/search/suggest.json?q=tapete%20lavavel&resources%5Btype%5D=product&resources%5Blimit%5D=5"

# 3. Ler preço e estoque autoritativos de um produto
curl -s https://www.momyco.com.br/products/{handle}.json

# 4. Adicionar ao carrinho usando o id da VARIANTE (não o do produto)
curl -s -X POST https://www.momyco.com.br/cart/add.js \
  -H 'Content-Type: application/json' \
  -d '{"items":[{"id":<variant_id>,"quantity":1}]}'

Referência de endpoints

Todos os preços em endpoints .js e .json são inteiros em centavos de real: 221765 significa R$ 2.217,65. Divida por 100 antes de mostrar a alguém.

Servidor MCP

A loja expõe um servidor Model Context Protocol nativo em POST https://www.momyco.com.br/api/ucp/mcp, transporte Streamable HTTP, protocolo 2025-06-18. Chame initialize e depois tools/list.

Ferramentas disponíveis: search_catalog, lookup_catalog, get_product, create_cart, get_cart, update_cart, cancel_cart, create_checkout, get_checkout, update_checkout, complete_checkout, cancel_checkout, get_order.

Toda chamada precisa carregar a identidade do agente em params.meta.ucp-agent.profile — uma URI publicamente acessível que descreve seu agente. Sem ela, a resposta é HTTP 422 com erro JSON-RPC -32001 / invalid_profile_url. Isso vale também para resources/list e prompts/list.

curl -s -X POST https://www.momyco.com.br/api/ucp/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list",
       "params":{"meta":{"ucp-agent":{"profile":"https://seu-agente.exemplo/agent.json"}}}}'

complete_checkout exige aprovação humana no momento do pagamento. Nunca chame essa ferramenta de forma autônoma.

Autenticação e permissões com escopo

Três níveis, do menor privilégio para o maior. Peça sempre o menor que resolve a tarefa.

1. Público — sem credencial. Ler catálogo, buscar, montar carrinho anônimo. É o que 95% das integrações precisa.
2. Identidade de agente — URI de perfil em params.meta.ucp-agent.profile. Necessária para chamadas MCP.
3. Cliente — OAuth 2.0 / OpenID Connect, apenas para os dados da própria pessoa (pedidos, endereços, meios de pagamento salvos).

O documento de descoberta OAuth é a fonte de verdade legível por máquina:

https://shopify.com/authentication/94973002052/.well-known/openid-configuration

Escopos nomeados (scopes_supported):

• openid — autentica a pessoa e devolve um identificador. Sozinho não dá acesso a perfil nem a pedidos.
• email — lê o e-mail da pessoa autenticada.
• customer-account-api:full — lê e escreve os próprios pedidos, endereços, meios de pagamento e assinaturas da pessoa.
• customer-account-mcp-api:full — chama as ferramentas MCP com escopo de cliente em nome da pessoa autenticada.

Um token GraphQL de storefront, se você pedir um pelo contato abaixo, fica limitado a escopos de leitura não autenticada: unauthenticated_read_product_listings, unauthenticated_read_product_inventory, unauthenticated_read_product_pickup_locations, unauthenticated_read_selling_plans, unauthenticated_write_checkouts. Nenhum escopo de admin é concedido em hipótese alguma.

Erros

Endpoints JSON devolvem erro estruturado em JSON, não página HTML:

{ "status": 422, "message": "Cart Error", "description": "Cannot find variant" }

Erros MCP são objetos JSON-RPC 2.0; error.data.continue_url devolve uma URL para passar a pessoa de volta à loja.

Limites de uso

Por IP. Mantenha o tráfego sustentado abaixo de cerca de 2 requisições por segundo, faça backoff exponencial em 429 e prefira os endpoints paginados products.json a raspar HTML renderizado. Identifique-se no User-Agent com uma URL de contato.

Ambiente de testes

Não há sandbox separada: os endpoints de catálogo, busca e carrinho são somente leitura ou criam apenas um carrinho de sessão descartável, então podem ser exercitados diretamente em produção sem efeito colateral. Chamadas de carrinho não geram pedido; só o checkout aprovado por uma pessoa gera. Para testar o fluxo completo de checkout sem cobrança, fale com a gente pelo contato abaixo.

Contato para desenvolvedores

Para solicitar um token de storefront, relatar um problema de integração, pedir aumento de limite ou combinar um teste de checkout, use a página de contato. Descreva o caso de uso e o volume esperado.

Sobre a loja

A Momy & Co é uma loja brasileira de decoração para a casa da família: tapetes laváveis, quartos de bebê e infantis, tapetes de brincar, cestos, almofadas, iluminação e presentes, com curadoria de marcas como Lorena Canals, Nobodinoz e Maracujá ao lado da linha própria. Razão social, CNPJ e endereço estão no rodapé de todas as páginas e no bloco JSON-LD Organization. Veja também Sobre nós e as políticas da loja.