Stone Catalog API

Authentication

Geração e gestão de tokens de autenticação

Gerar token de acesso

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 <token> nas chamadas à API.

post

Body

application/x-www-form-urlencoded
grant_typestringrequired

Allowed values:client_credentials

Example:client_credentials

client_idstringrequired

Client ID da aplicação

Example:22st50f99o3uan9forfrb6h3uh

client_secretstringrequired

Client Secret da aplicação

Example:your-client-secret

Response

application/json

Token gerado com sucesso

access_tokenstringrequired

Bearer token JWT para uso nas chamadas à API

token_typestringrequired

Allowed values:Bearer

Example:Bearer

expires_inintegerrequired

Tempo de expiração em segundos

Example:86400

post/auth/realms/payments/oauth2/token

Body

{ "grant_type": "client_credentials", "client_id": "22st50f99o3uan9forfrb6h3uh", "client_secret": "your-client-secret" }
 
application/json

Gerar token de acesso

DEPRECATED

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.

get

Response

application/json

Token gerado com sucesso

tokenstringrequired

Token JWT para ser usado como Bearer token

Example:eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJhcHBsaWNhdGlvbklkIjoiNjYwZTg0MDAtZTI5Yi00MWQ0LWE3MTYtNDQ2NjU1NDQwMDAxIiwiaWF0IjoxNjQyMjUyODAwLCJleHAiOjE2NDIyNTY0MDB9.abcd1234

expiresAtstring(date-time)required

Data e hora de expiração do token

Example:2024-01-15T11:30:00.000Z

prefixstringrequired

Prefixo do tipo de autenticação a ser usado no header Authorization

Allowed values:Bearer

Example:Bearer

get/auth/generate-token
 
application/json

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

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
 
application/json