GETConsultar produto

Retorna a página completa de um produto ativo, por UUID ou slug, com SEO, breadcrumb, imagens, vídeos, escadas de preço e regras de estoque.

Use esta rota quando o comprador abre um produto. Ela devolve o que a lista já mostra (veja Listar produtos para o significado dos campos de preço e estoque) mais o que só a página precisa: texto completo, seo, breadcrumb, a cadeia de categories, videos, price_tiers e, em produto com variações em produtos-filhos, a lista variations.

O {id} aceita o UUID ou o slug do produto. Se o slug mudou, a rota consulta a tabela de redirecionamentos da loja e, havendo um, responde 200 com {"redirect": "/products/novo-slug", "slug": "novo-slug"} em vez de 404, para o cliente seguir o novo endereço.

A rota devolve 404 (product not found) quando o produto não existe, não está ativo, está restrito a um grupo de usuário do qual o visitante não faz parte, pertence a um vendedor que não entrega na região do comprador, ou é escondido pelas regras da loja de "preço zero" e "sem estoque".

GET/api/v1/storefront/products/{id}Pública

Consultar um produto da vitrine

Parâmetros de caminho

idstringobrigatório

UUID ou slug do produto. Para um slug, use exatamente o valor do campo slug.

Parâmetros de consulta

langstring

Idioma dos textos (pt-BR, en, es). Também vale Accept-Language. Sem tradução, o texto base.

Cabeçalhos

Authorizationstring

Opcional. Bearer $TOKEN de um cliente: libera produto restrito ao grupo dele e aplica o preço do grupo.

X-Tenant-IDstring

Identifica a loja quando a requisição não vai ao domínio dela.

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/storefront/products/zz-doc-midia-teste?lang=pt-BR"

Resposta

200Produto retornado

json

{
  "id": "34a3bed9-c40d-4519-801f-5cae027eac2a",
  "display_id": 10655,
  "name": "ZZ Doc Midia Teste",
  "slug": "zz-doc-midia-teste",
  "sku": "ZZ-DOCMEDIA-1",
  "description": "",
  "short_description": "",
  "category_id": "345ac33e-4dcd-4d60-bedf-a2c2d47897d9",
  "categories": [
    { "id": "345ac33e-4dcd-4d60-bedf-a2c2d47897d9", "name": "Escritório", "slug": "escritorio", "depth": 0 }
  ],
  "breadcrumb": [
    { "label": "Escritório", "url": "/c/escritorio" },
    { "label": "ZZ Doc Midia Teste" }
  ],
  "seo": {
    "meta_title": "ZZ Doc Midia Teste | Test Admin's Store",
    "meta_description": "",
    "canonical_url": "/products/zz-doc-midia-teste"
  },
  "price": 3780,
  "price_str": "37.80",
  "price_tiers": [],
  "track_inventory": true,
  "quantity": 5,
  "amount": 5,
  "low_stock_alert": 8,
  "out_of_stock_action": "B",
  "min_quantity": 0,
  "max_quantity": 0,
  "quantity_step": 1,
  "sale_unit": "un",
  "zero_price_action": "R",
  "free_shipping": false,
  "requires_shipping": true,
  "dispatch_days": 2,
  "has_unified_variations": false,
  "is_variation": false,
  "images": [
    { "id": "04e96211-43e2-41bc-98b2-2a53624d955a", "image_url": "https://example.com/img/c.jpg", "alt_text": "", "is_primary": true, "position": 0 },
    { "id": "b377cd92-f66b-4b4f-9702-0694dd60fb24", "image_url": "https://example.com/img/b.jpg", "alt_text": "Lado", "is_primary": false, "position": 1 }
  ],
  "videos": [
    {
      "id": "acdd41ba-4f0d-4afe-bb5e-79b15cb2d8b4",
      "video_type": "youtube",
      "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
      "thumbnail_url": "https://img.youtube.com/vi/dQw4w9WgXcQ/hqdefault.jpg",
      "title": "Novo título",
      "position": 2
    }
  ],
  "vendor_id": "9d9d9d56-eb43-4719-889d-055632f7c7da",
  "vendor_name": "Loja Otávio",
  "vendor_slug": "loja-ot-vio-2",
  "rating_avg": 0,
  "rating_count": 0,
  "status": "A",
  "created_at": "2026-10-11T20:54:44.466233Z",
  "updated_at": "2026-10-11T20:56:33.015589Z"
}

200Slug antigo com redirecionamento

json

{ "redirect": "/products/novo-slug", "slug": "novo-slug" }

Campos da resposta

(campos do cartão)object

Todos os campos de Listar produtos também vêm aqui.

descriptionstring

Descrição completa, pode conter HTML. Sanitize antes de injetar na página.

categoriesarray

Cadeia de categorias da raiz até a categoria do produto: id, name, slug, depth (0 = raiz).

breadcrumbarray

Migalhas prontas. Cada item tem label e url (relativa); o último é o próprio produto e não tem url.

seoobject

meta_title, meta_description e canonical_url, já com o texto padrão da loja quando o produto não define os seus. canonical_url é relativa à loja.

slugsobject

Mapa idioma para slug ({"en": "my-product"}), em lojas multilíngues. Use para hreflang. Omitido nas demais.

price_tiersarray

Escada de preço por quantidade, só preços universais (sem tabelas de grupo). Zerada se a loja esconde preço de visitante.

videosarray

Vídeos da galeria, por position: id, video_type (upload, youtube, vimeo, live_clip), url, thumbnail_url, title, position. Omitido se não há.

variationsarray

Produtos-filhos ativos, quando as variações são produtos separados (veja Variações). Omitido se não há.

feature_valuesobject

Em um produto-filho, os valores que o distinguem do pai ({"<id da característica>": {"variant_id": "...", "value": "Vermelho"}}).

dispatch_daysinteger

Prazo estimado de despacho do vendedor, em dias. Omitido em produto da própria loja.

low_stock_alertinteger

Limite de "restam poucas unidades" definido pela loja. Use para mostrar o aviso quando quantity ficar abaixo dele.

promo_textstring

Texto promocional acima do botão de compra. Omitido se vazio.

highlight_textstring

Frase curta sob o nome ("Feito à mão"). Omitido se vazio.

redirectstring

Só na resposta de slug antigo: caminho para onde seguir. Vem junto com slug.

Erros

Status	Quando	Exemplo de corpo
401	A loja exige login para navegar e a requisição é anônima	`{"error":"shopping_requires_login","message":"this storefront requires login to browse"}`
403	Chave de API sem o escopo `storefront:read`	`{"error":"missing_scope","required":"storefront:read"}`
404	Produto inexistente, inativo, restrito, fora da região de entrega ou escondido por preço zero/sem estoque, e sem redirecionamento	`{"error":"product not found"}`
500	Falha ao consultar	`{"error":"failed to get product","detail":"..."}`

Veja também

GETConsultar produto

Retorna a página completa de um produto ativo, por UUID ou slug, com SEO, breadcrumb, imagens, vídeos, escadas de preço e regras de estoque.

GET/api/v1/storefront/products/{id}Pública

Consultar um produto da vitrine

Parâmetros de caminho

idstringobrigatório

UUID ou slug do produto. Para um slug, use exatamente o valor do campo slug.

Parâmetros de consulta

langstring

Idioma dos textos (pt-BR, en, es). Também vale Accept-Language. Sem tradução, o texto base.

Cabeçalhos

Authorizationstring

Opcional. Bearer $TOKEN de um cliente: libera produto restrito ao grupo dele e aplica o preço do grupo.

X-Tenant-IDstring

Identifica a loja quando a requisição não vai ao domínio dela.

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/storefront/products/zz-doc-midia-teste?lang=pt-BR"

Resposta

200Produto retornado

json

{
  "id": "34a3bed9-c40d-4519-801f-5cae027eac2a",
  "display_id": 10655,
  "name": "ZZ Doc Midia Teste",
  "slug": "zz-doc-midia-teste",
  "sku": "ZZ-DOCMEDIA-1",
  "description": "",
  "short_description": "",
  "category_id": "345ac33e-4dcd-4d60-bedf-a2c2d47897d9",
  "categories": [
    { "id": "345ac33e-4dcd-4d60-bedf-a2c2d47897d9", "name": "Escritório", "slug": "escritorio", "depth": 0 }
  ],
  "breadcrumb": [
    { "label": "Escritório", "url": "/c/escritorio" },
    { "label": "ZZ Doc Midia Teste" }
  ],
  "seo": {
    "meta_title": "ZZ Doc Midia Teste | Test Admin's Store",
    "meta_description": "",
    "canonical_url": "/products/zz-doc-midia-teste"
  },
  "price": 3780,
  "price_str": "37.80",
  "price_tiers": [],
  "track_inventory": true,
  "quantity": 5,
  "amount": 5,
  "low_stock_alert": 8,
  "out_of_stock_action": "B",
  "min_quantity": 0,
  "max_quantity": 0,
  "quantity_step": 1,
  "sale_unit": "un",
  "zero_price_action": "R",
  "free_shipping": false,
  "requires_shipping": true,
  "dispatch_days": 2,
  "has_unified_variations": false,
  "is_variation": false,
  "images": [
    { "id": "04e96211-43e2-41bc-98b2-2a53624d955a", "image_url": "https://example.com/img/c.jpg", "alt_text": "", "is_primary": true, "position": 0 },
    { "id": "b377cd92-f66b-4b4f-9702-0694dd60fb24", "image_url": "https://example.com/img/b.jpg", "alt_text": "Lado", "is_primary": false, "position": 1 }
  ],
  "videos": [
    {
      "id": "acdd41ba-4f0d-4afe-bb5e-79b15cb2d8b4",
      "video_type": "youtube",
      "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
      "thumbnail_url": "https://img.youtube.com/vi/dQw4w9WgXcQ/hqdefault.jpg",
      "title": "Novo título",
      "position": 2
    }
  ],
  "vendor_id": "9d9d9d56-eb43-4719-889d-055632f7c7da",
  "vendor_name": "Loja Otávio",
  "vendor_slug": "loja-ot-vio-2",
  "rating_avg": 0,
  "rating_count": 0,
  "status": "A",
  "created_at": "2026-10-11T20:54:44.466233Z",
  "updated_at": "2026-10-11T20:56:33.015589Z"
}

200Slug antigo com redirecionamento

json

{ "redirect": "/products/novo-slug", "slug": "novo-slug" }

Campos da resposta

(campos do cartão)object

Todos os campos de Listar produtos também vêm aqui.

descriptionstring

Descrição completa, pode conter HTML. Sanitize antes de injetar na página.

categoriesarray

Cadeia de categorias da raiz até a categoria do produto: id, name, slug, depth (0 = raiz).

breadcrumbarray

Migalhas prontas. Cada item tem label e url (relativa); o último é o próprio produto e não tem url.

seoobject

meta_title, meta_description e canonical_url, já com o texto padrão da loja quando o produto não define os seus. canonical_url é relativa à loja.

slugsobject

Mapa idioma para slug ({"en": "my-product"}), em lojas multilíngues. Use para hreflang. Omitido nas demais.

price_tiersarray

Escada de preço por quantidade, só preços universais (sem tabelas de grupo). Zerada se a loja esconde preço de visitante.

videosarray

Vídeos da galeria, por position: id, video_type (upload, youtube, vimeo, live_clip), url, thumbnail_url, title, position. Omitido se não há.

variationsarray

Produtos-filhos ativos, quando as variações são produtos separados (veja Variações). Omitido se não há.

feature_valuesobject

Em um produto-filho, os valores que o distinguem do pai ({"<id da característica>": {"variant_id": "...", "value": "Vermelho"}}).

dispatch_daysinteger

Prazo estimado de despacho do vendedor, em dias. Omitido em produto da própria loja.

low_stock_alertinteger

Limite de "restam poucas unidades" definido pela loja. Use para mostrar o aviso quando quantity ficar abaixo dele.

promo_textstring

Texto promocional acima do botão de compra. Omitido se vazio.

highlight_textstring

Frase curta sob o nome ("Feito à mão"). Omitido se vazio.

redirectstring

Só na resposta de slug antigo: caminho para onde seguir. Vem junto com slug.

Erros

Status	Quando	Exemplo de corpo
401	A loja exige login para navegar e a requisição é anônima	`{"error":"shopping_requires_login","message":"this storefront requires login to browse"}`
403	Chave de API sem o escopo `storefront:read`	`{"error":"missing_scope","required":"storefront:read"}`
404	Produto inexistente, inativo, restrito, fora da região de entrega ou escondido por preço zero/sem estoque, e sem redirecionamento	`{"error":"product not found"}`
500	Falha ao consultar	`{"error":"failed to get product","detail":"..."}`