{"openapi":"3.1.0","info":{"title":"API pública da loja USMARK","version":"1.0.0","summary":"Catálogo da loja USMARK: produtos, preços, variações, categorias, cores e tamanhos.","description":"Endpoints públicos e somente leitura do catálogo da loja USMARK. Não precisam de chave nem de login. Preços em reais (BRL); preços e estoque mudam, então consulte antes de responder. Criar pedido e pagar exigem o comprador no fluxo da loja e não fazem parte desta API. Guia para agentes: https://usmark.com.br/llms.txt. Portal do desenvolvedor: https://usmark.com.br/developers.","contact":{"name":"Atendimento USMARK","url":"https://usmark.com.br/usmark/contato"}},"servers":[{"url":"https://usmark.com.br","description":"Loja USMARK"}],"security":[],"externalDocs":{"description":"Portal do desenvolvedor","url":"https://usmark.com.br/developers"},"tags":[{"name":"Catálogo","description":"Produtos, categorias, cores e tamanhos da loja."}],"paths":{"/api/usm/pub/products":{"get":{"tags":["Catálogo"],"operationId":"listarProdutos","summary":"Lista os produtos à venda","description":"Lista paginada (24 por página) dos produtos ativos que têm alguma variação com estoque disponível.","parameters":[{"name":"search","in":"query","description":"Parte do nome do produto.","schema":{"type":"string"}},{"name":"categorySlug","in":"query","description":"Slug da categoria (ver /api/usm/pub/categories). Categoria raiz inclui as subcategorias.","schema":{"type":"string"}},{"name":"colorId","in":"query","description":"Id da cor (ver /api/usm/pub/colors).","schema":{"type":"integer"}},{"name":"sizeId","in":"query","description":"Id do tamanho (ver /api/usm/pub/sizes).","schema":{"type":"integer"}},{"name":"featured","in":"query","description":"Só produtos em destaque.","schema":{"type":"string","enum":["true"]}},{"name":"isNew","in":"query","description":"Só novidades.","schema":{"type":"string","enum":["true"]}},{"name":"isOffer","in":"query","description":"Só ofertas.","schema":{"type":"string","enum":["true"]}},{"name":"sort","in":"query","description":"Ordem; sem o parâmetro, os mais novos primeiro.","schema":{"type":"string","enum":["price_asc","price_desc"]}},{"name":"page","in":"query","description":"Página, a partir de 1.","schema":{"type":"integer","minimum":1,"default":1}}],"responses":{"200":{"description":"Página de produtos.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginaDeProdutos"}}}},"429":{"description":"Muitas requisições em pouco tempo. Espere alguns segundos e repita.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}},"500":{"description":"Erro interno.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}}}}},"/api/usm/pub/products/{slug}":{"get":{"tags":["Catálogo"],"operationId":"detalharProduto","summary":"Detalhe de um produto","description":"Produto com variações (cor, tamanho, estoque), fotos e categorias. A página do produto fica em https://usmark.com.br/usmark/produto/{slug}.","parameters":[{"$ref":"#/components/parameters/Slug"}],"responses":{"200":{"description":"Produto.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProdutoDetalhe"}}}},"404":{"description":"Produto não encontrado ou fora de venda.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}},"429":{"description":"Muitas requisições em pouco tempo. Espere alguns segundos e repita.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}},"500":{"description":"Erro interno.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}}}}},"/api/usm/pub/products/{slug}/related":{"get":{"tags":["Catálogo"],"operationId":"produtosRelacionados","summary":"Produtos relacionados","description":"Prioriza produtos ativos das mesmas categorias. Se faltarem produtos para atingir limit, preenche a lista com outros produtos ativos, primeiro os destaques e depois os mais recentes, mesmo que pertençam a outras categorias. Produto inexistente devolve lista vazia.","parameters":[{"$ref":"#/components/parameters/Slug"},{"name":"limit","in":"query","description":"Quantidade (até 20).","schema":{"type":"integer","minimum":1,"maximum":20,"default":8}}],"responses":{"200":{"description":"Lista de produtos.","content":{"application/json":{"schema":{"type":"object","required":["rows"],"properties":{"rows":{"type":"array","items":{"$ref":"#/components/schemas/ProdutoRelacionado"}}}}}}},"429":{"description":"Muitas requisições em pouco tempo. Espere alguns segundos e repita.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}},"500":{"description":"Erro interno.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}}}}},"/api/usm/pub/categories":{"get":{"tags":["Catálogo"],"operationId":"listarCategorias","summary":"Categorias com produto em estoque","description":"Árvore de categorias (raízes e subcategorias, ligadas por parentId). Só aparecem as que têm produto com estoque.","responses":{"200":{"description":"Categorias.","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Categoria"}}}}},"429":{"description":"Muitas requisições em pouco tempo. Espere alguns segundos e repita.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}},"500":{"description":"Erro interno.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}}}}},"/api/usm/pub/colors":{"get":{"tags":["Catálogo"],"operationId":"listarCores","summary":"Cores com produto em estoque","description":"Lista as cores associadas a variações com estoque disponível em produtos ativos. Os nomes são apresentados sem o código interno da cor.","responses":{"200":{"description":"Cores.","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Cor"}}}}},"429":{"description":"Muitas requisições em pouco tempo. Espere alguns segundos e repita.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}},"500":{"description":"Erro interno.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}}}}},"/api/usm/pub/sizes":{"get":{"tags":["Catálogo"],"operationId":"listarTamanhos","summary":"Tamanhos","description":"Lista todos os tamanhos cadastrados, sem filtrar por estoque. Ordena pelo campo sortOrder e depois pelo nome.","responses":{"200":{"description":"Tamanhos.","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Tamanho"}}}}},"429":{"description":"Muitas requisições em pouco tempo. Espere alguns segundos e repita.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}},"500":{"description":"Erro interno.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Erro"}}}}}}}},"components":{"parameters":{"Slug":{"name":"slug","in":"path","required":true,"description":"Slug do produto, como vem na listagem.","schema":{"type":"string"}}},"schemas":{"Erro":{"type":"object","required":["error","message"],"properties":{"error":{"type":"object","required":["status","code","message"],"properties":{"status":{"type":"integer","description":"Status HTTP."},"code":{"type":"string","description":"Código estável do erro, como not_found ou rate_limited."},"message":{"type":"string","description":"Mensagem em português."},"hint":{"type":"string","description":"O que fazer."},"docs":{"type":"string","description":"Onde está a documentação."}}},"message":{"type":"string","description":"A mesma mensagem, no campo de sempre."}}},"Variacao":{"type":"object","additionalProperties":true,"properties":{"id":{"type":"integer"},"colorId":{"type":["integer","null"]},"sizeId":{"type":["integer","null"]},"colorName":{"type":["string","null"]},"colorHex":{"type":["string","null"]},"sizeName":{"type":["string","null"]},"stockQuantity":{"type":"integer","description":"Disponível para venda (estoque menos reservado)."}}},"ProdutoResumo":{"type":"object","additionalProperties":true,"required":["id","name","basePrice"],"properties":{"id":{"type":"integer"},"name":{"type":"string"},"slug":{"type":["string","null"]},"sku":{"type":["string","null"]},"description":{"type":["string","null"]},"basePrice":{"type":"number","description":"Preço em BRL."},"promoPrice":{"type":["number","null"],"description":"Preço promocional em BRL, quando houver."},"isNew":{"type":"boolean"},"isOffer":{"type":"boolean"},"isFeatured":{"type":"boolean"},"mainImage":{"type":["string","null"],"description":"Endereço da foto principal (relativo ao servidor)."},"variants":{"type":"array","items":{"$ref":"#/components/schemas/Variacao"}}}},"PaginaDeProdutos":{"type":"object","required":["rows","total","page","pageSize"],"properties":{"rows":{"type":"array","items":{"$ref":"#/components/schemas/ProdutoResumo"}},"total":{"type":"integer","description":"Total de produtos no filtro."},"page":{"type":"integer"},"pageSize":{"type":"integer"}}},"ProdutoDetalhe":{"type":"object","additionalProperties":true,"required":["id","name","basePrice","variants"],"properties":{"id":{"type":"integer"},"name":{"type":"string"},"slug":{"type":["string","null"]},"sku":{"type":["string","null"]},"description":{"type":["string","null"]},"basePrice":{"type":"number","description":"Preço em BRL."},"promoPrice":{"type":["number","null"]},"variants":{"type":"array","items":{"type":"object","additionalProperties":true,"properties":{"id":{"type":"integer"},"colorId":{"type":["integer","null"]},"sizeId":{"type":["integer","null"]},"colorName":{"type":["string","null"]},"sizeName":{"type":["string","null"]},"stock":{"type":"integer"},"reserved":{"type":"integer","description":"Disponível para venda = stock − reserved."}}}},"images":{"type":"array","items":{"type":"object","additionalProperties":true}},"categoryIds":{"type":"array","items":{"type":"integer"}}}},"ProdutoRelacionado":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"slug":{"type":["string","null"]},"basePrice":{"type":"number"},"promoPrice":{"type":["number","null"]},"isNew":{"type":"boolean"},"isFeatured":{"type":"boolean"},"mainImage":{"type":["string","null"]},"segundaImagem":{"type":["string","null"]}}},"Categoria":{"type":"object","additionalProperties":true,"required":["id","name"],"properties":{"id":{"type":"integer"},"name":{"type":"string"},"slug":{"type":["string","null"]},"parentId":{"type":["integer","null"]},"imageUrl":{"type":["string","null"]}}},"Cor":{"type":"object","additionalProperties":true,"required":["id","name"],"properties":{"id":{"type":"integer"},"name":{"type":"string"},"hexCode":{"type":["string","null"]},"slug":{"type":["string","null"]}}},"Tamanho":{"type":"object","additionalProperties":true,"required":["id","name"],"properties":{"id":{"type":"integer"},"name":{"type":"string"},"sortOrder":{"type":"integer"}}}}}}