Pular para o conteúdo principal
Versão: 1.0

Catálogo

Autenticação: X-API-Key (ou token de aluno no painel).

Listar produtos​

GET/v1/products🔒 X-API-Key

Aceita search, categoryId, brandId, state, minPrice, maxPrice, page, pageSize.

curl "$BASE/products?search=fone&page=1&pageSize=20" \
  -H "X-API-Key: $API_KEY" -H "X-Student-RM: RM550001"

Detalhar produto (traz variantes)​

GET/v1/products/:id🔒 X-API-Key
A unidade vendável está aqui

Use variants[].id para carrinho e variants[].price para exibir o preço.

Criar produto​

POST/v1/products🔒 X-API-Key
{ "type": "SIMPLE", "name": "Carregador Turbo", "sku": "CARR-001", "price": 79.9, "stock": 60 }

Atualizar produto e variante​

PUT/v1/products/:id🔒 X-API-Key
PATCH/v1/variants/:id🔒 X-API-Key
PUT /v1/products/:id (dados base)
{ "name": "Novo nome", "state": "PUBLISHED", "categoryId": null }
PATCH /v1/variants/:id (preço)
{ "price": 149.9 }
Estoque não é editado aqui

Preço vai no PATCH /variants/:id; estoque usa os endpoints de estoque (/v1/variants/:id/stock/receive e /adjust).

Remover produto​

DELETE/v1/products/:id🔒 X-API-Key

Retorna 204 No Content.

Fotos e vídeos​

POST/v1/uploads🔒 X-API-Key
POST/v1/products/:id/media🔒 X-API-Key

Os dois recebem multipart/form-data com o arquivo no campo file. O primeiro só sobe para a biblioteca da loja; o segundo sobe e já vincula ao produto.

sobe e vincula (uma chamada)
curl -X POST "$BASE/products/$ID/media" \
  -H "X-API-Key: sk_live_..." \
  -F "file=@foto.jpg" -F "isPrimary=true"
resposta do POST /v1/uploads
{
  "id": "cmu0...",
  "kind": "IMAGE",
  "url": "https://mockmerce-media.s3.us-east-1.amazonaws.com/groups/.../a1b2c3.jpg",
  "mimeType": "image/png",
  "sizeBytes": 48213
}
POST/v1/products/:id/images🔒 X-API-Key
PATCH/v1/images/:id🔒 X-API-Key
DELETE/v1/images/:id🔒 X-API-Key

Vincula uma mídia já enviada (mediaId) ou uma URL externa (url); o PATCH troca a capa ou a ordem; o DELETE desvincula (o arquivo continua na biblioteca).

POST /v1/products/:id/images
{ "mediaId": "cmu0...", "isPrimary": true }
GET/v1/media🔒 X-API-Key
GET/v1/media/usage🔒 X-API-Key
DELETE/v1/media/:id🔒 X-API-Key

Biblioteca da loja, espaço usado e remoção definitiva (?force=true quando o arquivo estiver em uso por algum produto).

Detalhes e armadilhas

Formatos, limites, capa e o erro clássico do Content-Type estão no guia Fotos e vídeos.

Avaliações​

GET/v1/products/:id/reviews🔒 X-API-Key
GET/v1/products/:id/reviews/can-review🔒 Bearer (cliente)
POST/v1/products/:id/reviews🔒 Bearer (cliente)

Só quem comprou avalia (pedido pago com o produto), e cada cliente avalia um produto uma vez. A listagem é pública dentro da loja e já traz o resumo.

POST /v1/products/:id/reviews
{ "rating": 5, "title": "Recomendo", "comment": "Chegou antes do prazo.", "mediaIds": ["cmu0..."] }
resumo que acompanha a listagem
{
  "summary": {
    "average": 4.5,
    "count": 12,
    "distribution": { "5": 8, "4": 2, "3": 1, "2": 0, "1": 1 }
  }
}
PATCH/v1/reviews/:id🔒 Bearer (cliente)
DELETE/v1/reviews/:id🔒 Bearer (cliente)
GET/v1/me/reviews🔒 Bearer (cliente)

Editar e apagar valem só para a própria avaliação (403 na dos outros).

GET/v1/store/reviews🔒 X-API-Key
PATCH/v1/store/reviews/:id🔒 X-API-Key

A loja vê tudo (inclusive o que ocultou) e modera com { "hidden": true } — a avaliação sai da vitrine e da média.

A nota já vem no produto

GET /products e GET /products/:id devolvem rating — não precisa buscar as avaliações só para desenhar as estrelinhas do card. Detalhes no guia Avaliações.

Categorias, marcas e coleções​

GET/v1/categories🔒 X-API-Key
POST/v1/categories🔒 X-API-Key
POST /v1/categories
{ "name": "Periféricos" }

O mesmo padrão vale para /v1/brands e /v1/collections.