Consultar produto

Retorna o cadastro completo de um produto pelo id, com preço, estoque, categorias e imagens.

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.0/products/{id}Autenticada

Consultar um produto

Autenticação: HTTP Basic com e-mail:chave_de_api, ou Authorization: Bearer <JWT>; a leitura aceita qualquer usuário autenticado. A rota também responde em /api/products/{id}; nessa forma o {id} e todos os ids da resposta são decimais em string (por exemplo "77051560"), e o UUID continua aceito.

Parâmetros de caminho

idstringobrigatório

Id do produto: o product_id, em UUID. Na rota /api/products/{id} também aceita o id decimal. Um valor que não é UUID na rota /api/v1.0 responde 500.

Exemplo de requisição

bash

curl -u "$EMAIL:$API_KEY" \
  "$BASE_URL/api/v1.0/products/0497b6a8-c868-43be-ac21-2abddd24cd3c"

Resposta

200Produto encontrado

json

{
  "product_id": "0497b6a8-c868-43be-ac21-2abddd24cd3c",
  "product": "Caneca Esmaltada 350 ml",
  "product_code": "CAN-350-AZ",
  "product_type": "P",
  "status": "A",
  "company_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
  "price": "49.90",
  "list_price": "59.90",
  "amount": 12,
  "tracking": "Y",
  "weight": "0.350",
  "length": "12.00",
  "width": "9.00",
  "height": "9.00",
  "free_shipping": "N",
  "min_qty": 0,
  "max_qty": 0,
  "qty_step": 1,
  "full_description": "<p>Caneca esmaltada azul.</p>",
  "short_description": "",
  "main_category": "7ebc648d-6091-4511-8ea2-f86f7b3b4dd9",
  "category_ids": ["7ebc648d-6091-4511-8ea2-f86f7b3b4dd9"],
  "seo_name": "caneca-esmaltada-350-ml",
  "page_title": "",
  "meta_description": "",
  "meta_keywords": "",
  "search_words": "",
  "promo_text": "",
  "popularity": 0,
  "position": 0,
  "master_product_id": "",
  "zero_price_action": "R",
  "shipping_freight": 0,
  "timestamp": 1791751867,
  "updated_timestamp": 1791752114,
  "main_pair": {
    "pair_id": "acd51513-0264-46c7-a667-504e3ec77e19",
    "image_id": "acd51513-0264-46c7-a667-504e3ec77e19",
    "detailed": { "image_path": "/uploads/caneca-azul.png", "alt": "" },
    "icons": { "image_path": "/uploads/caneca-azul.png?w=100", "alt": "" }
  },
  "image_pairs": {},
  "product_features": [],
  "product_options": [],
  "prices": [],
  "brand": "",
  "tax_ids": [],
  "category_names": [],
  "variation_features": {}
}

Campos da resposta

product_idstring

Id do produto. UUID em /api/v1.0; decimal em string em /api/.

productstring

Nome do produto.

product_codestring

Código do produto (o SKU). Vazio quando o produto não tem código.

product_typestring

Sempre P (produto).

statusstring

ADH

Status em letra: A ativo, D desativado, H oculto. Produto aguardando aprovação (R) aparece como H e rejeitado (X) como D.

company_idstring

Id do seller dono do produto. "0" quando o produto não tem seller.

pricestring

Preço de venda em string decimal com ponto e duas casas ("49.90" = R$ 49,90).

list_pricestring

Preço "de" (riscado), string decimal. "0.00" quando não existe.

amountinteger

Estoque, número inteiro (arredondado para baixo se o estoque for fracionado).

trackingstring

YN

Y quando o produto controla estoque.

weightstring

Peso em kg, string com 3 casas ("0.350").

lengthstring

Comprimento em cm, string com 2 casas. "0.00" quando não informado.

widthstring

Largura em cm, string com 2 casas.

heightstring

Altura em cm, string com 2 casas.

free_shippingstring

YN

Y quando o produto tem frete grátis.

min_qtyinteger

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

max_qtyinteger

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

qty_stepinteger

Múltiplo de compra (a quantidade tem de ser múltipla deste valor). Padrão 1.

full_descriptionstring

Descrição completa, em HTML.

short_descriptionstring

Descrição curta.

main_categorystring

Id da categoria principal. Vazio sem categoria.

category_idsarray

Ids de todas as categorias: a principal primeiro, depois as adicionais.

seo_namestring

Slug da URL do produto.

page_titlestring

Título SEO (tag title).

meta_descriptionstring

Descrição SEO.

meta_keywordsstring

Palavras-chave SEO.

search_wordsstring

Termos extras para a busca da loja (sinônimos, apelidos).

promo_textstring

Texto promocional mostrado acima do botão de compra.

popularityinteger

Índice de popularidade usado na ordenação "mais populares".

positioninteger

Sempre 0 (campo mantido por compatibilidade).

master_product_idstring

Id do produto mestre a que esta oferta está ligada. Vazio quando não está ligada.

zero_price_actionstring

PRA

O que fazer quando o preço é zero: P vender por zero, R bloquear a compra online, A pedir orçamento.

shipping_freightinteger

Frete fixo do produto, em centavos (inteiro). É o único valor monetário inteiro desta resposta.

timestampinteger

Criação, Unix timestamp em segundos (UTC).

updated_timestampinteger

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

main_pairobject

Imagem principal: pair_id e image_id (iguais), detailed.image_path (imagem grande), icons.image_path (miniatura, a mesma URL com ?w=100) e alt. Ausente quando o produto não tem imagem.

image_pairsobject

Demais imagens, num objeto cujas chaves são a posição ("0", "1"...) e os valores têm o mesmo formato de main_pair. {} quando não há outras.

product_featuresarray

Valores de características que distinguem variações: [{"feature_id","variant_id","value"}]. Vazio em produto comum. As demais características têm rota própria em Conteúdo e características.

product_optionsarray

Sempre [] aqui. As opções do produto saem em Variações e opções.

pricesarray

Sempre [] aqui. As faixas de preço por quantidade saem em Preço e estoque.

brandstring

Sempre "" (campo mantido por compatibilidade).

tax_idsarray

Sempre [].

category_namesarray

Sempre [].

variation_featuresobject

Sempre {}.

Erros

Status	Quando	Corpo
401	Sem credenciais, chave de API inválida ou token expirado	`{"message":"Authentication required. Use HTTP Basic with email:api_key or Bearer <jwt>.","status":401}`
404	O produto não existe, foi excluído ou o `{id}` é um SKU ou `display_id`	`{"message":"Product not found","status":404}`
400	(rota `/api/products`) `{id}` que não é UUID nem decimal	`{"message":"Invalid id","status":400}`
500	(rota `/api/v1.0`) `{id}` que não é UUID, ou falha interna	`{"message":"Failed to retrieve product","status":500}`

Veja também

Consultar produto

Retorna o cadastro completo de um produto pelo id, com preço, estoque, categorias e imagens.

GET/api/v1.0/products/{id}Autenticada

Consultar um produto

Parâmetros de caminho

idstringobrigatório

Id do produto: o product_id, em UUID. Na rota /api/products/{id} também aceita o id decimal. Um valor que não é UUID na rota /api/v1.0 responde 500.

Exemplo de requisição

bash

curl -u "$EMAIL:$API_KEY" \
  "$BASE_URL/api/v1.0/products/0497b6a8-c868-43be-ac21-2abddd24cd3c"

Resposta

200Produto encontrado

json

{
  "product_id": "0497b6a8-c868-43be-ac21-2abddd24cd3c",
  "product": "Caneca Esmaltada 350 ml",
  "product_code": "CAN-350-AZ",
  "product_type": "P",
  "status": "A",
  "company_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
  "price": "49.90",
  "list_price": "59.90",
  "amount": 12,
  "tracking": "Y",
  "weight": "0.350",
  "length": "12.00",
  "width": "9.00",
  "height": "9.00",
  "free_shipping": "N",
  "min_qty": 0,
  "max_qty": 0,
  "qty_step": 1,
  "full_description": "<p>Caneca esmaltada azul.</p>",
  "short_description": "",
  "main_category": "7ebc648d-6091-4511-8ea2-f86f7b3b4dd9",
  "category_ids": ["7ebc648d-6091-4511-8ea2-f86f7b3b4dd9"],
  "seo_name": "caneca-esmaltada-350-ml",
  "page_title": "",
  "meta_description": "",
  "meta_keywords": "",
  "search_words": "",
  "promo_text": "",
  "popularity": 0,
  "position": 0,
  "master_product_id": "",
  "zero_price_action": "R",
  "shipping_freight": 0,
  "timestamp": 1791751867,
  "updated_timestamp": 1791752114,
  "main_pair": {
    "pair_id": "acd51513-0264-46c7-a667-504e3ec77e19",
    "image_id": "acd51513-0264-46c7-a667-504e3ec77e19",
    "detailed": { "image_path": "/uploads/caneca-azul.png", "alt": "" },
    "icons": { "image_path": "/uploads/caneca-azul.png?w=100", "alt": "" }
  },
  "image_pairs": {},
  "product_features": [],
  "product_options": [],
  "prices": [],
  "brand": "",
  "tax_ids": [],
  "category_names": [],
  "variation_features": {}
}

Campos da resposta

product_idstring

Id do produto. UUID em /api/v1.0; decimal em string em /api/.

productstring

Nome do produto.

product_codestring

Código do produto (o SKU). Vazio quando o produto não tem código.

product_typestring

Sempre P (produto).

statusstring

ADH

Status em letra: A ativo, D desativado, H oculto. Produto aguardando aprovação (R) aparece como H e rejeitado (X) como D.

company_idstring

Id do seller dono do produto. "0" quando o produto não tem seller.

pricestring

Preço de venda em string decimal com ponto e duas casas ("49.90" = R$ 49,90).

list_pricestring

Preço "de" (riscado), string decimal. "0.00" quando não existe.

amountinteger

Estoque, número inteiro (arredondado para baixo se o estoque for fracionado).

trackingstring

YN

Y quando o produto controla estoque.

weightstring

Peso em kg, string com 3 casas ("0.350").

lengthstring

Comprimento em cm, string com 2 casas. "0.00" quando não informado.

widthstring

Largura em cm, string com 2 casas.

heightstring

Altura em cm, string com 2 casas.

free_shippingstring

YN

Y quando o produto tem frete grátis.

min_qtyinteger

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

max_qtyinteger

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

qty_stepinteger

Múltiplo de compra (a quantidade tem de ser múltipla deste valor). Padrão 1.

full_descriptionstring

Descrição completa, em HTML.

short_descriptionstring

Descrição curta.

main_categorystring

Id da categoria principal. Vazio sem categoria.

category_idsarray

Ids de todas as categorias: a principal primeiro, depois as adicionais.

seo_namestring

Slug da URL do produto.

page_titlestring

Título SEO (tag title).

meta_descriptionstring

Descrição SEO.

meta_keywordsstring

Palavras-chave SEO.

search_wordsstring

Termos extras para a busca da loja (sinônimos, apelidos).

promo_textstring

Texto promocional mostrado acima do botão de compra.

popularityinteger

Índice de popularidade usado na ordenação "mais populares".

positioninteger

Sempre 0 (campo mantido por compatibilidade).

master_product_idstring

Id do produto mestre a que esta oferta está ligada. Vazio quando não está ligada.

zero_price_actionstring

PRA

O que fazer quando o preço é zero: P vender por zero, R bloquear a compra online, A pedir orçamento.

shipping_freightinteger

Frete fixo do produto, em centavos (inteiro). É o único valor monetário inteiro desta resposta.

timestampinteger

Criação, Unix timestamp em segundos (UTC).

updated_timestampinteger

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

main_pairobject

Imagem principal: pair_id e image_id (iguais), detailed.image_path (imagem grande), icons.image_path (miniatura, a mesma URL com ?w=100) e alt. Ausente quando o produto não tem imagem.

image_pairsobject

Demais imagens, num objeto cujas chaves são a posição ("0", "1"...) e os valores têm o mesmo formato de main_pair. {} quando não há outras.

product_featuresarray

Valores de características que distinguem variações: [{"feature_id","variant_id","value"}]. Vazio em produto comum. As demais características têm rota própria em Conteúdo e características.

product_optionsarray

Sempre [] aqui. As opções do produto saem em Variações e opções.

pricesarray

Sempre [] aqui. As faixas de preço por quantidade saem em Preço e estoque.

brandstring

Sempre "" (campo mantido por compatibilidade).

tax_idsarray

Sempre [].

category_namesarray

Sempre [].

variation_featuresobject

Sempre {}.

Erros

Status	Quando	Corpo
401	Sem credenciais, chave de API inválida ou token expirado	`{"message":"Authentication required. Use HTTP Basic with email:api_key or Bearer <jwt>.","status":401}`
404	O produto não existe, foi excluído ou o `{id}` é um SKU ou `display_id`	`{"message":"Product not found","status":404}`
400	(rota `/api/products`) `{id}` que não é UUID nem decimal	`{"message":"Invalid id","status":400}`
500	(rota `/api/v1.0`) `{id}` que não é UUID, ou falha interna	`{"message":"Failed to retrieve product","status":500}`