Products
Endpoints para busca e recuperação de produtos
Buscar produto por código de barras ou nome
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.
Busca por nome: consulta apenas o cache — se não encontrado, retorna 404 sem acionar discovery.
Códigos de teste (SDX):
7898486077400— produto não encontrado (404)7898486077417— produto em fila de retry (404)7898486077424— produto em discovery (422)
get
Query Parameters
barcodestring
Código de barras EAN-13 do produto (12 ou 13 dígitos numéricos).
Match pattern:^\d{12,13}$
Example:7891000100103
namestring
Nome do produto para busca. A busca por nome retorna produtos fictícios em ambiente sandbox.
Comportamento de busca:
- Consulta apenas o cache L2 (PostgreSQL)
- Se nenhum produto for encontrado, retorna 404 imediatamente (sem discovery).
Match pattern:^[a-zA-ZÀ-ÿ\s\d./-]+$
Example:Coca-Cola 2L
Headers
x-merchant-documentstringrequired
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.
Match pattern:^(\d{11}|\d{14}|[A-Za-z0-9]{12}\d{2})$
Example:12345678901234, 12345678901 ou 12ABC34501DE35
Response
application/json
Response
application/json
Produtos encontrados com sucesso
idstring(uuid)required
Identificador único do produto
Example:550e8400-e29b-41d4-a716-446655440000
barcodestring | null
Código de barras EAN-13
Match pattern:^\d{12,13}$
Example:7891000100103
namestringrequired
Nome do produto
Example:Coca-Cola 2L
shortDescriptionstring | null
Descrição curta do produto
Example:Refrigerante Coca-Cola 2 Litros
longDescriptionstring | null
Descrição detalhada do produto
Example:Refrigerante Coca-Cola sabor original em garrafa PET de 2 litros. Produto ideal para toda a família.
brandstring | null
Marca do produto
Example:Coca-Cola
manufacturerstring | null
Fabricante do produto
Example:Coca-Cola Brasil
categoryPathstringrequired
Caminho completo da categoria
Example:Alimentos e Bebidas > Bebidas > Refrigerantes
imagesarray[string](uri)required
Lista de URLs das imagens do produto
Example:https://s3.amazonaws.com/stone-catalog/products/550e8400-e29b-41d4-a716-446655440000/image1.jpg
attributesobject | null
Atributos específicos do produto (pares chave-valor)
Example:{"volume":"2L","sabor":"Original","tipo":"Refrigerante"}
weightKgnumber | null(float)
Peso do produto em quilogramas
Example:2.1
heightCmnumber | null(float)
Altura do produto em centímetros
Example:32.5
widthCmnumber | null(float)
Largura do produto em centímetros
Example:10.5
depthCmnumber | null(float)
Profundidade do produto em centímetros
Example:10.5
pricestring | null(string)
Faixa de preço do produto em reais. Retorna null quando não disponível.
Example:R$ 7.50
metadataobjectrequired
Show Child Parameters
get/products
Authentication
Query Parameters
Headers
application/json
Recuperar imagem de produto
Retorna a imagem do produto a partir do caminho especificado. As imagens são servidas com cache de longa duração (1 ano).
get
Path Parameters
imagePathstringrequired
Caminho da imagem (incluindo subpastas e nome do arquivo)
Example:550e8400-e29b-41d4-a716-446655440000/image1.jpg
Response
Response
Imagem retornada com sucesso
string
get/products/images/{imagePath}
Path Parameters
MCP
Model Context Protocol - Integração para agentes de IA e assistentes inteligentes via MCP Server. Requer autenticação OAuth2.
Buscar produto via MCP (Model Context Protocol)
Endpoint MCP (Model Context Protocol) para integração com agentes de IA (Claude Desktop, Cursor, Zed, etc.). Requer autenticação OAuth2 via Scalekit.
post
Body
application/json
Body
application/json
Forneça ‘barcode’ ou ‘name’ para buscar o produto. Se ambos forem fornecidos, ‘barcode’ terá prioridade.
barcodestring
Código de barras EAN-13 do produto (12 ou 13 dígitos numéricos)
Match pattern:^[0-9]{12,13}$
Example:7891234567890
namestring
Nome do produto para busca textual
>= 3 characters
Example:Smartphone Samsung Galaxy
Response
application/json
Response
application/json
Produto encontrado com sucesso
idstring(uuid)required
Identificador único do produto
Example:550e8400-e29b-41d4-a716-446655440000
barcodestring | null
Código de barras EAN-13
Match pattern:^\d{12,13}$
Example:7891000100103
namestringrequired
Nome do produto
Example:Coca-Cola 2L
shortDescriptionstring | null
Descrição curta do produto
Example:Refrigerante Coca-Cola 2 Litros
longDescriptionstring | null
Descrição detalhada do produto
Example:Refrigerante Coca-Cola sabor original em garrafa PET de 2 litros. Produto ideal para toda a família.
brandstring | null
Marca do produto
Example:Coca-Cola
manufacturerstring | null
Fabricante do produto
Example:Coca-Cola Brasil
categoryPathstringrequired
Caminho completo da categoria
Example:Alimentos e Bebidas > Bebidas > Refrigerantes
imagesarray[string](uri)required
Lista de URLs das imagens do produto
Example:https://s3.amazonaws.com/stone-catalog/products/550e8400-e29b-41d4-a716-446655440000/image1.jpg
attributesobject | null
Atributos específicos do produto (pares chave-valor)
Example:{"volume":"2L","sabor":"Original","tipo":"Refrigerante"}
weightKgnumber | null(float)
Peso do produto em quilogramas
Example:2.1
heightCmnumber | null(float)
Altura do produto em centímetros
Example:32.5
widthCmnumber | null(float)
Largura do produto em centímetros
Example:10.5
depthCmnumber | null(float)
Profundidade do produto em centímetros
Example:10.5
pricestring | null(string)
Faixa de preço do produto em reais. Retorna null quando não disponível.
Example:R$ 7.50
metadataobjectrequired
Show Child Parameters
post/products/mcp
Authentication
Body
{
"barcode": "7891234567890"
}
application/json