Consultar produto

Retorna o cadastro completo de um produto pelo id, com preço, estoque, categorias, imagens, idiomas e o número de pedidos vinculados.

Use esta operação quando você já sabe qual produto quer ver: depois de criar para conferir o resultado, antes de alterar para ler o valor atual, ou para abrir o detalhe de um item que apareceu na lista. A consulta de administração devolve o produto em qualquer status (ativo, oculto, desativado, aguardando aprovação ou rejeitado), diferente da API da vitrine, que só mostra os ativos.

As características, as opções, as variações, as faixas de preço e os anexos não vêm neste corpo: cada um tem a sua rota, nas seções Variações e opções, Preço e estoque e Conteúdo e características.

GET/api/v1/admin/products/{id}Admin

Consulta um produto

Autenticação: Authorization: Bearer <token> de um usuário administrador com o privilégio view_catalog ou manage_catalog. Não há filtro de status: produto pendente, rejeitado, desativado e rascunho voltam normalmente.

Path parameters

idstringobrigatório

UUID do produto. A consulta também aceita o slug do produto (caneca-esmaltada-350-ml). O display_id e o SKU não servem: voltam 404.

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/admin/products/0497b6a8-c868-43be-ac21-2abddd24cd3c" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Produto encontrado

json

{
  "id": "0497b6a8-c868-43be-ac21-2abddd24cd3c",
  "display_id": 10643,
  "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
  "category_id": "7ebc648d-6091-4511-8ea2-f86f7b3b4dd9",
  "additional_category_ids": ["345ac33e-4dcd-4d60-bedf-a2c2d47897d9"],
  "name": "Caneca Esmaltada 350 ml",
  "slug": "caneca-esmaltada-350-ml",
  "sku": "CAN-350-AZ",
  "description": "<p>Caneca esmaltada azul.</p>",
  "short_description": "",
  "price": 4990,
  "list_price": 5990,
  "cost_price": 2000,
  "track_inventory": true,
  "quantity": 12,
  "low_stock_alert": 0,
  "min_quantity": 0,
  "max_quantity": 0,
  "quantity_step": 1,
  "sale_unit": "un",
  "zero_price_action": "R",
  "popularity": 0,
  "out_of_stock_action": "S",
  "weight": 0.35,
  "width": 9,
  "height": 9,
  "length": 12,
  "status": "A",
  "intended_status": "A",
  "approval_status": "approved",
  "view_count": 0,
  "sales_count": 0,
  "rating_avg": 0,
  "rating_count": 0,
  "free_shipping": false,
  "shipping_freight": 0,
  "requires_shipping": true,
  "vendor_name": "Loja Seller Teste",
  "vendor_slug": "loja-seller-teste",
  "is_variation": false,
  "has_unified_variations": false,
  "created_at": "2026-10-11T20:51:07.858767Z",
  "updated_at": "2026-10-11T20:55:14.612402Z",
  "descriptions": {
    "pt-BR": {
      "lang_code": "pt-BR",
      "name": "Caneca Esmaltada 350 ml",
      "description": "<p>Caneca esmaltada azul.</p>",
      "short_description": "",
      "promo_text": "",
      "highlight_text": "",
      "seo_title": "",
      "seo_description": "",
      "meta_keywords": ""
    }
  },
  "images": [
    {
      "id": "acd51513-0264-46c7-a667-504e3ec77e19",
      "image_url": "/uploads/caneca-azul.png",
      "alt_text": "",
      "position": 0,
      "is_primary": true
    }
  ],
  "price_tiers": [],
  "linked_orders_count": 0,
  "product_id": "0497b6a8-c868-43be-ac21-2abddd24cd3c",
  "product": "Caneca Esmaltada 350 ml",
  "product_code": "CAN-350-AZ",
  "seo_name": "caneca-esmaltada-350-ml",
  "full_description": "<p>Caneca esmaltada azul.</p>",
  "price_str": "49.90",
  "list_price_str": "59.90",
  "weight_str": "0.350",
  "amount": 12,
  "company_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
  "company_name": "Loja Seller Teste",
  "supplier": "Loja Seller Teste",
  "main_category": "7ebc648d-6091-4511-8ea2-f86f7b3b4dd9",
  "timestamp": 1791751867,
  "updated_timestamp": 1791752114
}

Campos da resposta

iduuid

Id do produto.

display_idinteger

Número curto mostrado no painel. Só para leitura humana; não serve como {id}.

vendor_iduuid

Seller dono do produto. Ausente em produto sem seller.

vendor_namestring

Nome do seller.

vendor_slugstring

Slug do seller (para montar a URL da página dele).

category_iduuid

Categoria principal.

additional_category_idsarray

Ids das categorias adicionais. Ausente quando não há.

namestring

Nome (no idioma padrão da loja).

slugstring

Slug da URL do produto. Único na loja.

skustring

Código do produto. Ausente quando não tem.

barcodestring

EAN/GTIN. Ausente quando não tem.

eanstring

EAN do cadastro. Ausente quando não tem.

vendor_internal_skustring

Código interno do seller.

ncm_codestring

Código NCM (8 dígitos), usado na NF-e.

descriptionstring

Descrição completa, em HTML.

short_descriptionstring

Descrição curta.

promo_textstring

Texto promocional acima do botão de compra.

highlight_textstring

Linha curta sob o nome do produto na página (por exemplo "Entrega em 24h").

search_wordsstring

Termos extras para a busca.

seo_titlestring

Título SEO.

seo_descriptionstring

Descrição SEO.

meta_keywordsstring

Palavras-chave SEO.

priceinteger

Preço de venda em centavos (4990 = R$ 49,90).

list_priceinteger

Preço "de" (riscado) em centavos. Ausente quando não existe.

cost_priceinteger

Custo em centavos. Ausente quando não informado.

track_inventoryboolean

Se o produto controla estoque.

quantitynumber

Estoque disponível, na unidade de venda. Pode ser fracionado (2.5) quando allow_fractional é verdadeiro.

low_stock_alertinteger

Limite de estoque baixo. 0 = sem limite.

min_quantitynumber

Quantidade mínima por compra. 0 = sem mínimo.

max_quantitynumber

Quantidade máxima por compra. 0 = sem máximo.

quantity_stepnumber

Múltiplo de compra. Padrão 1.

sale_unitstring

Unidade de venda: un, kg, cx, l, par ou texto livre.

sale_unit_labelstring

Rótulo da unidade de venda (por exemplo "Caixa com 12").

allow_fractionalboolean

Se aceita quantidades fracionadas. Ausente quando falso.

out_of_stock_actionstring

NBS

Sem estoque: N esconde o botão de compra, B aceita encomenda, S mostra o formulário "avise-me".

zero_price_actionstring

PRA

Preço zero: P vende por zero, R bloqueia a compra online, A pede orçamento.

avail_sincestring

Data de lançamento, RFC 3339. O produto só pode ser comprado a partir dela. Ausente quando não há.

usergroup_idsarray

Grupos de clientes que enxergam o produto (UUIDs ou all, guest, registered). Ausente = visível para todos.

popularityinteger

Índice de popularidade.

weightnumber

Peso em kg.

widthnumber

Largura em cm.

heightnumber

Altura em cm.

lengthnumber

Comprimento em cm.

free_shippingboolean

Frete grátis.

shipping_freightinteger

Frete fixo do produto, em centavos.

requires_shippingboolean

false para produto digital ou virtual, que não tem entrega.

statusstring

ADHRX

Status: veja a tabela na home da seção.

intended_statusstring

ADH

Status para o qual o produto vai quando for aprovado.

approval_statusstring

pendingapprovedrejected

Status de moderação derivado de status.

rejected_reasonstring

Motivo da rejeição, quando status é X.

moderated_atstring

Quando a moderação decidiu, RFC 3339.

moderated_byuuid

Usuário que moderou.

whatsapp_hiddenboolean

Se o produto fica fora do catálogo do WhatsApp. A vitrine ignora este campo.

view_countinteger

Visualizações da página do produto.

sales_countinteger

Unidades vendidas.

rating_avgnumber

Nota média das avaliações (0 a 5).

rating_countinteger

Número de avaliações.

master_product_iduuid

Produto mestre a que esta oferta está ligada. Ausente quando não está.

parent_product_iduuid

Produto-pai, quando este produto é uma variação filha.

variation_group_iduuid

Grupo de variações do produto-pai.

is_variationboolean

true quando o produto é uma variação filha de outro.

has_unified_variationsboolean

true quando o produto tem a matriz de variações unificadas (cor, tamanho).

feature_valuesobject

Valores de características que distinguem esta variação filha (feature_id → {variant_id, value}).

buy_now_urlstring

Link externo de "Comprar agora", para lojas em modo catálogo.

created_atstring

Criação, RFC 3339 em UTC.

updated_atstring

Última alteração, RFC 3339 em UTC.

descriptionsobject

Texto por idioma. A chave é o código do idioma (pt-BR, en...) e o valor traz lang_code, name, description, short_description, promo_text, highlight_text, seo_title, seo_description e meta_keywords. Vem um item para cada idioma ativo da loja.

imagesarray

Imagens do produto, em ordem de posição: id, image_url, alt_text, position e is_primary. Veja Mídia do produto.

price_tiersarray

Faixas de preço por quantidade (veja Preço e estoque). Neste corpo ela costuma vir vazia ([]): leia as faixas pela rota própria.

videosarray

Vídeos do produto, quando existem.

linked_orders_countinteger

Quantos itens de pedido já referenciam o produto. Serve para avisar, antes de excluir, que o produto tem histórico de vendas.

product_iduuid

Repete id.

productstring

Repete name.

product_codestring

Repete sku.

seo_namestring

Repete slug.

full_descriptionstring

Repete description.

price_strstring

price em string decimal ("49.90").

list_price_strstring

list_price em string decimal. Ausente quando não há preço de lista.

weight_strstring

weight em string decimal com 3 casas.

amountinteger

quantity arredondado para baixo, como inteiro.

company_iduuid

Repete vendor_id.

company_namestring

Repete vendor_name.

supplierstring

Nome do seller, para exibição.

main_categoryuuid

Repete category_id.

timestampinteger

Criação em Unix timestamp (segundos).

updated_timestampinteger

Última alteração em Unix timestamp (segundos).

Erros

Status	Quando	Corpo
401	Sem credenciais, chave de API inválida ou token expirado	`{"error":"missing authorization header"}` ou `{"error":"invalid or expired token"}`
403	Usuário sem `view_catalog` nem `manage_catalog`	`{"error":"insufficient privileges","privilege_required_any":["manage_catalog","view_catalog"]}`
404	O produto não existe, foi excluído, ou o `{id}` é um SKU ou `display_id`	`{"error":"product not found"}`

Veja também