--- title: "Stone Catalog API" url: "https://devcenter.stone.com.br/apis/stone-catalog/versions/502db258-cb08-4b38-8af1-b96a688b9a9e" --- # Stone Catalog API OpenAPI specification document. ```json {"openapi":"3.0.3","info":{"title":"Stone Catalog API","description":"API inteligente para descoberta e catalogação automática de produtos sob demanda usando agentes de IA especializados e web scraping. Busca informações detalhadas de produtos por código de barras (EAN-13) ou nome do produto.","version":"1.0.0","contact":{"name":"Stone Catalog Team"}},"servers":[{"url":"https://sdx.api.stone.com.br/v1/catalog","description":"Ambiente de Desenvolvimento (SDX)"},{"url":"https://api.stone.com.br/v1/catalog","description":"Ambiente de Produção (PRD)"}],"tags":[{"name":"Authentication","description":"Geração e gestão de tokens de autenticação"},{"name":"Products","description":"Endpoints para busca e recuperação de produtos"},{"name":"MCP","description":"Model Context Protocol - Integração para agentes de IA e assistentes inteligentes via MCP Server. Requer autenticação OAuth2."}],"paths":{"/auth/realms/payments/oauth2/token":{"post":{"tags":["Authentication"],"summary":"Gerar token de acesso","description":"Gera um Bearer token usando client_credentials flow do Cognito. Use o client_id e client_secret da aplicação fornecidos pelo time. O token retornado deve ser enviado como `Authorization: Bearer ` nas chamadas à API.","operationId":"generateExternalIdpToken","servers":[{"url":"https://sdx.api.stone.com.br","description":"SDX"},{"url":"https://api.stone.com.br","description":"PRD"}],"requestBody":{"required":true,"content":{"application/x-www-form-urlencoded":{"schema":{"type":"object","required":["grant_type","client_id","client_secret"],"properties":{"grant_type":{"type":"string","enum":["client_credentials"],"example":"client_credentials"},"client_id":{"type":"string","description":"Client ID da aplicação","example":"22st50f99o3uan9forfrb6h3uh"},"client_secret":{"type":"string","description":"Client Secret da aplicação","example":"your-client-secret"}}}}}},"responses":{"200":{"description":"Token gerado com sucesso","content":{"application/json":{"schema":{"type":"object","required":["access_token","token_type","expires_in"],"properties":{"access_token":{"type":"string","description":"Bearer token JWT para uso nas chamadas à API"},"token_type":{"type":"string","enum":["Bearer"],"example":"Bearer"},"expires_in":{"type":"integer","description":"Tempo de expiração em segundos","example":86400}}}}}},"400":{"description":"Credenciais inválidas ou parâmetros incorretos"}}}},"/auth/generate-token":{"get":{"tags":["Authentication"],"summary":"Gerar token de acesso","description":"Gera um token JWT válido por 1 hora via Basic Auth (API Key + API Secret). Mantido para compatibilidade com integrações legadas. Novas integrações devem usar o fluxo via IDP externo.","operationId":"generateToken","deprecated":true,"security":[{"BasicAuth":[]}],"responses":{"200":{"description":"Token gerado com sucesso","content":{"application/json":{"schema":{"type":"object","required":["token","expiresAt","prefix"],"properties":{"token":{"type":"string","description":"Token JWT para ser usado como Bearer token","example":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJhcHBsaWNhdGlvbklkIjoiNjYwZTg0MDAtZTI5Yi00MWQ0LWE3MTYtNDQ2NjU1NDQwMDAxIiwiaWF0IjoxNjQyMjUyODAwLCJleHAiOjE2NDIyNTY0MDB9.abcd1234"},"expiresAt":{"type":"string","format":"date-time","description":"Data e hora de expiração do token","example":"2024-01-15T11:30:00.000Z"},"prefix":{"type":"string","enum":["Bearer"],"description":"Prefixo do tipo de autenticação a ser usado no header Authorization","example":"Bearer"}}},"example":{"token":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJhcHBsaWNhdGlvbklkIjoiNjYwZTg0MDAtZTI5Yi00MWQ0LWE3MTYtNDQ2NjU1NDQwMDAxIiwiaWF0IjoxNjQyMjUyODAwLCJleHAiOjE2NDIyNTY0MDB9.example_signature","expiresAt":"2024-01-15T11:30:00.000Z","prefix":"Bearer"}}}},"401":{"description":"Credenciais inválidas","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing-auth":{"summary":"Cabeçalho de autenticação ausente","value":{"error":"Missing or invalid Authorization header"}},"invalid-credentials":{"summary":"API Key ou Secret inválidos","value":{"error":"Invalid application credentials"}}}}}},"403":{"description":"Aplicação inativa","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"inactive-app":{"summary":"Aplicação desativada","value":{"error":"Application is inactive"}},"inactive-account":{"summary":"Conta desativada","value":{"error":"Application account is inactive"}}}}}},"429":{"description":"Limite diário excedido","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"Daily limit exceeded"}}}},"500":{"description":"Erro interno do servidor","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"Internal server error"}}}}}}},"/products":{"get":{"tags":["Products"],"summary":"Buscar produto por código de barras ou nome","description":"Busca informações detalhadas de um produto por código de barras (EAN-8, EAN-12, EAN-13 e EAN-14) ou nome. Consulta o cache L2 (PostgreSQL) antes de acionar o pipeline de discovery via agentes de IA. Máximo de 20 produtos por requisição.\n\n**Busca por nome:** consulta apenas o cache — se não encontrado, retorna 404 sem acionar discovery.\n\n**Códigos de teste (SDX):**\n- `7898486077400` — produto não encontrado (404)\n- `7898486077417` — produto em fila de retry (404)\n- `7898486077424` — produto em discovery (422)","operationId":"getProduct","parameters":[{"name":"barcode","in":"query","description":"Código de barras EAN-13 do produto (12 ou 13 dígitos numéricos).","required":false,"schema":{"type":"string","pattern":"^\\d{12,13}$","example":"7891000100103"}},{"name":"name","in":"query","description":"Nome do produto para busca. A busca por nome retorna produtos fictícios em ambiente sandbox.\n\n**Comportamento de busca**:\n- Consulta apenas o cache L2 (PostgreSQL)\n- Se nenhum produto for encontrado, retorna 404 imediatamente (sem discovery).","required":false,"schema":{"type":"string","pattern":"^[a-zA-ZÀ-ÿ\\s\\d./-]+$","example":"Coca-Cola 2L"}},{"name":"x-merchant-document","in":"header","description":"CNPJ ou CPF do merchant (obrigatório). Aceita CPF numérico (11 dígitos), CNPJ numérico legado (14 dígitos) e CNPJ alfanumérico (12 caracteres alfanuméricos + 2 dígitos verificadores). Em caso de erro de validação, o campo `details[].message` pode retornar mensagens específicas como tamanho inválido, formato inválido, dígitos verificadores inválidos ou tipo não suportado.","required":true,"schema":{"type":"string","pattern":"^(\\d{11}|\\d{14}|[A-Za-z0-9]{12}\\d{2})$","example":"12345678901234, 12345678901 ou 12ABC34501DE35"}}],"security":[{"BearerAuth":[]}],"responses":{"200":{"description":"Produtos encontrados com sucesso","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/ProductResponse"}},"example":[{"id":"550e8400-e29b-41d4-a716-446655440000","barcode":"7891000100103","name":"Coca-Cola 2L","shortDescription":"Refrigerante Coca-Cola 2 Litros","longDescription":"Refrigerante Coca-Cola sabor original em garrafa PET de 2 litros. Produto ideal para toda a família.","brand":"Coca-Cola","manufacturer":"Coca-Cola Brasil","categoryPath":"Alimentos e Bebidas > Bebidas > Refrigerantes","images":["https://s3.amazonaws.com/stone-catalog/products/550e8400-e29b-41d4-a716-446655440000/image1.jpg","https://s3.amazonaws.com/stone-catalog/products/550e8400-e29b-41d4-a716-446655440000/image2.jpg"],"price":"R$ 7.99 - R$ 11.59","attributes":{"volume":"2L","sabor":"Original","tipo":"Refrigerante"},"weightKg":2.1,"heightCm":32.5,"widthCm":10.5,"depthCm":10.5,"metadata":{"version":1,"confidenceScore":0.95,"discoveredAt":"2024-01-15T10:30:00Z","updatedAt":"2024-01-15T10:30:00Z","lastScrapedAt":"2024-01-15T10:30:00Z"}}]}}},"400":{"description":"Parâmetros inválidos","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"},"examples":{"missing-params":{"summary":"Nenhum parâmetro fornecido","value":{"error":"Invalid parameters","details":[{"field":"query","message":"Exactly one parameter must be provided: barcode OR name"}]}},"invalid-barcode":{"summary":"Código de barras inválido","value":{"error":"Invalid parameters","details":[{"field":"barcode","message":"Barcode must contain exactly 12 or 13 numeric digits"}]}},"invalid-name":{"summary":"Nome do produto inválido","value":{"error":"Invalid parameters","details":[{"field":"name","message":"Name must have at least 3 characters"}]}}}}}},"401":{"description":"Não autenticado ou credenciais inválidas","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"Unauthorized","message":"Invalid or missing API credentials"}}}},"404":{"description":"Produto não encontrado","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"errorCode":{"type":"string","enum":["ErrProductNotFoundTemporarily","ErrProductNotFound"]},"error":{"type":"string"}}},"examples":{"product-not-found-temporary":{"summary":"Produto não encontrado - busca em andamento","description":"O produto não foi encontrado, mas o sistema continuará procurando. Tente novamente mais tarde.","value":{"errorCode":"ErrProductNotFoundTemporarily","error":"Product not found right now. We will continue to search for it. Try again later."}},"product-not-found-permanent":{"summary":"Produto não encontrado - sem resultados","description":"O produto não foi encontrado e não há resultados disponíveis.","value":{"errorCode":"ErrProductNotFound","error":"Product not found."}}}}}},"422":{"description":"Conflito de processamento","content":{"application/json":{"schema":{"type":"object","properties":{"errorCode":{"type":"string"},"error":{"type":"string"},"extraData":{"type":"object","nullable":true}}},"examples":{"product-in-discovery":{"summary":"Produto em processo de descoberta","value":{"errorCode":"ErrProductInDiscovery","error":"Product is already in discovery process. Try again later."}}}}}},"429":{"description":"Limite de requisições excedido","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"Too Many Requests","message":"Rate limit exceeded. Please try again later."}}}},"500":{"description":"Erro interno do servidor","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"Internal server error"}}}}}}},"/products/mcp":{"post":{"tags":["MCP"],"summary":"Buscar produto via MCP (Model Context Protocol)","description":"Endpoint MCP (Model Context Protocol) para integração com agentes de IA (Claude Desktop, Cursor, Zed, etc.). Requer autenticação OAuth2 via Scalekit.","operationId":"findProductsMcp","security":[{"OAuth2BearerMcp":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"barcode":{"type":"string","description":"Código de barras EAN-13 do produto (12 ou 13 dígitos numéricos)","pattern":"^[0-9]{12,13}$","example":"7891234567890"},"name":{"type":"string","description":"Nome do produto para busca textual","minLength":3,"example":"Smartphone Samsung Galaxy"}},"description":"Forneça 'barcode' ou 'name' para buscar o produto. Se ambos forem fornecidos, 'barcode' terá prioridade."},"examples":{"byBarcode":{"summary":"Busca por código de barras","value":{"barcode":"7891234567890"}},"byName":{"summary":"Busca por nome","value":{"name":"Smartphone Samsung Galaxy"}}}}}},"responses":{"200":{"description":"Produto encontrado com sucesso","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/ProductResponse"}},"example":[{"id":"550e8400-e29b-41d4-a716-446655440000","barcode":"7891234567890","name":"Smartphone Samsung Galaxy S24 Ultra 256GB","shortDescription":"Smartphone premium com câmera de 200MP","longDescription":"O Galaxy S24 Ultra redefine a experiência móvel premium...","brand":"Samsung","manufacturer":"Samsung Electronics","categoryPath":"Eletrônicos > Smartphones > Samsung","images":["https://api.catalog.stone.com.br/products/images/550e8400-e29b-41d4-a716-446655440000/image1.jpg"],"price":"R$ 7.299,99","attributes":{"cor":"Preto Titânio","memoria":"256GB","ram":"12GB"},"weightKg":0.233,"heightCm":16.2,"widthCm":7.9,"depthCm":0.86,"metadata":{"version":1,"confidenceScore":0.95,"discoveredAt":"2024-01-15T10:30:00Z","updatedAt":"2024-01-15T10:30:00Z","lastScrapedAt":"2024-01-15T10:30:00Z"}}]}}},"400":{"description":"Parâmetros inválidos","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"},"examples":{"invalidBarcode":{"summary":"Código de barras inválido","value":{"error":"Invalid parameters","details":[{"field":"barcode","message":"Barcode must contain exactly 12 or 13 numeric digits"}]}},"invalidName":{"summary":"Nome muito curto","value":{"error":"Invalid parameters","details":[{"field":"name","message":"Name must be at least 3 characters long"}]}},"missingParameters":{"summary":"Nenhum parâmetro fornecido","value":{"error":"Invalid parameters","details":[{"field":"barcode or name","message":"Either barcode or name must be provided"}]}}}}}},"401":{"description":"OAuth token inválido ou ausente","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"Invalid or missing OAuth token"}}},"headers":{"WWW-Authenticate":{"description":"Indica o método de autenticação necessário","schema":{"type":"string","example":"Bearer realm=\"MCP\""}}}},"404":{"description":"Produto não encontrado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"Product not found"}}}},"500":{"description":"Erro interno do servidor","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"Internal server error"}}}}}}},"/products/images/{imagePath}":{"get":{"tags":["Products"],"summary":"Recuperar imagem de produto","description":"Retorna a imagem do produto a partir do caminho especificado. As imagens são servidas com cache de longa duração (1 ano).","operationId":"getProductImage","parameters":[{"name":"imagePath","in":"path","description":"Caminho da imagem (incluindo subpastas e nome do arquivo)","required":true,"schema":{"type":"string","example":"550e8400-e29b-41d4-a716-446655440000/image1.jpg"}}],"responses":{"200":{"description":"Imagem retornada com sucesso","content":{"image/jpeg":{"schema":{"type":"string","format":"binary"}},"image/png":{"schema":{"type":"string","format":"binary"}},"image/webp":{"schema":{"type":"string","format":"binary"}},"image/gif":{"schema":{"type":"string","format":"binary"}}},"headers":{"Cache-Control":{"description":"Política de cache","schema":{"type":"string","example":"public, max-age=31536000, immutable"}},"Expires":{"description":"Data de expiração do cache","schema":{"type":"string","format":"date-time"}}}},"404":{"description":"Imagem não encontrada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"Image not found"}}}},"500":{"description":"Erro ao recuperar imagem","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"Failed to retrieve image"}}}}}}}},"components":{"securitySchemes":{"BasicAuth":{"type":"http","scheme":"basic","description":"Autenticação Basic com API Key como username e API Secret como password. Use este método apenas para o endpoint /auth/generate-token e somente para aplicações legadas."},"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Autenticação via Bearer token. Para aplicações legadas, obtenha um JWT através do endpoint /auth/generate-token usando Basic Auth. Para integrações novas, envie o access token emitido pelo IDP externo com o escopo usr_type/partner_stone_catalog."},"OAuth2BearerMcp":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Bearer token OAuth2 via Scalekit, exclusivo para o endpoint MCP. O token deve ter como audience o resource_id `/products/mcp`."},"ApiKeyAuth":{"type":"apiKey","in":"header","name":"x-api-key","description":"API Key fornecida no momento do cadastro do cliente (DEPRECATED - use BearerAuth)"}},"schemas":{"Partner":{"type":"object","required":["id","companyName","document","email","isActive","createdAt","updatedAt"],"properties":{"id":{"type":"string","format":"uuid","description":"Identificador único do parceiro","example":"550e8400-e29b-41d4-a716-446655440000"},"companyName":{"type":"string","description":"Nome da empresa parceira","example":"Acme Corp"},"document":{"type":"string","pattern":"^(\\d{11}|\\d{14}|[A-Za-z0-9]{12}\\d{2})$","description":"Documento do parceiro: CPF numérico, CNPJ numérico legado ou CNPJ alfanumérico. Em caso de erro de validação, o retorno inclui detalhe específico por motivo.","example":"12ABC34501DE35"},"email":{"type":"string","format":"email","description":"Email do parceiro","example":"contato@acmecorp.com"},"consoleId":{"type":"string","nullable":true,"description":"ID do console","example":"console-123"},"isActive":{"type":"boolean","description":"Indica se o parceiro está ativo","example":true},"createdAt":{"type":"string","format":"date-time","description":"Data de criação","example":"2024-01-15T10:30:00Z"},"updatedAt":{"type":"string","format":"date-time","description":"Data de última atualização","example":"2024-01-15T10:30:00Z"}}},"Application":{"type":"object","required":["id","name","partnerId","apiKey","isActive","createdAt","updatedAt"],"properties":{"id":{"type":"string","format":"uuid","description":"Identificador único da aplicação","example":"660e8400-e29b-41d4-a716-446655440001"},"name":{"type":"string","description":"Nome da aplicação","example":"App Mobile iOS"},"partnerId":{"type":"string","format":"uuid","description":"ID do parceiro","example":"550e8400-e29b-41d4-a716-446655440000"},"consoleId":{"type":"string","nullable":true,"description":"ID do console","example":"console-app-123"},"apiKey":{"type":"string","description":"API Key da aplicação","example":"key_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6"},"isActive":{"type":"boolean","description":"Indica se a aplicação está ativa","example":true},"dailyRequestLimit":{"type":"integer","nullable":true,"description":"Limite diário de requisições (null = ilimitado)","example":10000},"createdAt":{"type":"string","format":"date-time","description":"Data de criação","example":"2024-01-15T10:30:00Z"},"updatedAt":{"type":"string","format":"date-time","description":"Data de última atualização","example":"2024-01-15T10:30:00Z"}}},"Merchant":{"type":"object","required":["id","document","applicationId","isActive","createdAt","updatedAt"],"properties":{"id":{"type":"string","format":"uuid","description":"Identificador único do merchant","example":"770e8400-e29b-41d4-a716-446655440002"},"document":{"type":"string","pattern":"^(\\d{11}|\\d{14}|[A-Za-z0-9]{12}\\d{2})$","description":"Documento do merchant: CPF numérico, CNPJ numérico legado ou CNPJ alfanumérico. Em caso de erro de validação, o retorno inclui detalhe específico por motivo.","example":"12ABC34501DE35"},"applicationId":{"type":"string","format":"uuid","description":"ID da aplicação","example":"660e8400-e29b-41d4-a716-446655440001"},"isActive":{"type":"boolean","description":"Indica se o merchant está ativo","example":true},"createdAt":{"type":"string","format":"date-time","description":"Data de criação","example":"2024-01-15T10:30:00Z"},"updatedAt":{"type":"string","format":"date-time","description":"Data de última atualização","example":"2024-01-15T10:30:00Z"}}},"ProductResponse":{"type":"object","required":["id","name","categoryPath","images","metadata"],"properties":{"id":{"type":"string","format":"uuid","description":"Identificador único do produto","example":"550e8400-e29b-41d4-a716-446655440000"},"barcode":{"type":"string","nullable":true,"description":"Código de barras EAN-13","pattern":"^\\d{12,13}$","example":"7891000100103"},"name":{"type":"string","description":"Nome do produto","example":"Coca-Cola 2L"},"shortDescription":{"type":"string","nullable":true,"description":"Descrição curta do produto","example":"Refrigerante Coca-Cola 2 Litros"},"longDescription":{"type":"string","nullable":true,"description":"Descrição detalhada do produto","example":"Refrigerante Coca-Cola sabor original em garrafa PET de 2 litros. Produto ideal para toda a família."},"brand":{"type":"string","nullable":true,"description":"Marca do produto","example":"Coca-Cola"},"manufacturer":{"type":"string","nullable":true,"description":"Fabricante do produto","example":"Coca-Cola Brasil"},"categoryPath":{"type":"string","description":"Caminho completo da categoria","example":"Alimentos e Bebidas > Bebidas > Refrigerantes"},"images":{"type":"array","description":"Lista de URLs das imagens do produto","items":{"type":"string","format":"uri","example":"https://s3.amazonaws.com/stone-catalog/products/550e8400-e29b-41d4-a716-446655440000/image1.jpg"}},"attributes":{"type":"object","nullable":true,"description":"Atributos específicos do produto (pares chave-valor)","additionalProperties":{"type":"string"},"example":{"volume":"2L","sabor":"Original","tipo":"Refrigerante"}},"weightKg":{"type":"number","nullable":true,"format":"float","description":"Peso do produto em quilogramas","example":2.1},"heightCm":{"type":"number","nullable":true,"format":"float","description":"Altura do produto em centímetros","example":32.5},"widthCm":{"type":"number","nullable":true,"format":"float","description":"Largura do produto em centímetros","example":10.5},"depthCm":{"type":"number","nullable":true,"format":"float","description":"Profundidade do produto em centímetros","example":10.5},"price":{"type":"string","nullable":true,"format":"string","description":"Faixa de preço do produto em reais. Retorna null quando não disponível.","example":"R$ 7.50"},"metadata":{"type":"object","required":["version","confidenceScore","discoveredAt","updatedAt","lastScrapedAt"],"properties":{"version":{"type":"integer","description":"Versão do registro do produto","example":1},"confidenceScore":{"type":"number","format":"float","minimum":0,"maximum":1,"description":"Score de confiança dos dados (0.00 - 1.00)","example":0.95},"discoveredAt":{"type":"string","format":"date-time","description":"Data/hora em que o produto foi descoberto","example":"2024-01-15T10:30:00Z"},"updatedAt":{"type":"string","format":"date-time","description":"Data/hora da última atualização","example":"2024-01-15T10:30:00Z"},"lastScrapedAt":{"type":"string","format":"date-time","description":"Data/hora do último scraping","example":"2024-01-15T10:30:00Z"}}}}},"ValidationError":{"type":"object","required":["error","details"],"properties":{"error":{"type":"string","description":"Mensagem de erro","example":"Invalid parameters"},"details":{"type":"array","description":"Lista de erros de validação","items":{"type":"object","properties":{"field":{"type":"string","description":"Campo com erro","example":"barcode"},"message":{"type":"string","description":"Mensagem de erro específica","example":"Barcode must contain exactly 12 or 13 numeric digits"}}}}}},"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"string","description":"Mensagem de erro","example":"Internal server error"}}}}}} ```