Obter — Produtos
Consulte os dados de “Produtos”. O resultado depende dos parâmetros desta operação.
GET/api/v1/products/{product_id}
- Autenticação
Bearer- Disponível a partir de
- STANDARD
- Permissões necessárias
catalog.product:read
Exemplos de código
Exemplo de requisição
cURL
: "${SHOPENTLY_SHOP_URL:?}"
curl --disable --globoff --fail-with-body --silent --show-error \
--proto '=https' --connect-timeout 5 --max-time 30 \
--request GET \
--header "Authorization: Bearer ${SHOPENTLY_ACCESS_TOKEN:?}" \
--url "${SHOPENTLY_SHOP_URL%/}"/api/v1/products/example
PHP
<?php
declare(strict_types=1);
$baseUrl = rtrim(getenv('SHOPENTLY_SHOP_URL') ?: '', '/');
$origin = parse_url($baseUrl);
if (!$origin || ($origin['scheme'] ?? '') !== 'https' || empty($origin['host']) ||
isset($origin['user'], $origin['pass']) || isset($origin['user']) || isset($origin['path']) ||
isset($origin['query']) || isset($origin['fragment'])) {
throw new RuntimeException('SHOPENTLY_SHOP_URL must be an HTTPS origin');
}
$credential = getenv('SHOPENTLY_ACCESS_TOKEN') ?: '';
if ($credential === '' || strpbrk($credential, "\r\n") !== false) {
throw new RuntimeException('Invalid credential');
}
$headers = [];
$headers[] = 'Authorization: Bearer ' . $credential;
$responseHeaders = [];
$handle = curl_init($baseUrl . '/api/v1/products/example');
curl_setopt_array($handle, [
CURLOPT_CUSTOMREQUEST => 'GET',
CURLOPT_HTTPHEADER => $headers,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_FOLLOWLOCATION => false,
CURLOPT_PROTOCOLS => CURLPROTO_HTTPS,
CURLOPT_SSL_VERIFYPEER => true,
CURLOPT_SSL_VERIFYHOST => 2,
CURLOPT_CONNECTTIMEOUT => 5,
CURLOPT_TIMEOUT => 30,
CURLOPT_HEADERFUNCTION => static function ($handle, string $line) use (&$responseHeaders): int {
if (str_contains($line, ':')) {
[$name, $value] = explode(':', $line, 2);
$responseHeaders[strtolower(trim($name))] = trim($value);
}
return strlen($line);
},
]);
$raw = curl_exec($handle);
$status = curl_getinfo($handle, CURLINFO_RESPONSE_CODE);
$error = curl_error($handle);
curl_close($handle);
if ($raw === false) {
throw new RuntimeException('Transport error: ' . $error);
}
if ($status < 200 || $status >= 300) {
throw new RuntimeException('HTTP ' . $status . '; request_id=' .
($responseHeaders['x-request-id'] ?? '') . '; retry_after=' . ($responseHeaders['retry-after'] ?? ''));
}
$result = $raw === '' ? null : json_decode($raw, true, 512, JSON_THROW_ON_ERROR | JSON_BIGINT_AS_STRING);
echo json_encode($result, JSON_THROW_ON_ERROR | JSON_PRETTY_PRINT | JSON_UNESCAPED_UNICODE), PHP_EOL;
Python
from contextlib import ExitStack
import json
import os
from urllib.parse import urlsplit
import requests # python -m pip install requests
base_url = os.environ["SHOPENTLY_SHOP_URL"].rstrip("/")
origin = urlsplit(base_url)
if origin.scheme != "https" or not origin.hostname or origin.username or origin.password or origin.path or origin.query or origin.fragment:
raise ValueError("SHOPENTLY_SHOP_URL must be an HTTPS origin")
credential = os.environ['SHOPENTLY_ACCESS_TOKEN']
if not credential or "\r" in credential or "\n" in credential:
raise ValueError("Invalid credential")
headers = {}
headers["Authorization"] = 'Bearer' + " " + credential
body = None
if body is not None:
headers["Content-Type"] = "application/json"
with ExitStack() as stack:
session = stack.enter_context(requests.Session())
files = None
if False:
image = stack.enter_context(open(os.environ["SHOPENTLY_IMAGE_FILE"], "rb"))
if os.fstat(image.fileno()).st_size > 5242880:
raise ValueError("Image exceeds 5 MiB")
files = {"file": ("article.png", image, "image/png")}
response = session.request(
'GET', base_url + '/api/v1/products/example', headers=headers,
data=body.encode("utf-8") if body is not None else None, files=files,
timeout=(5, 30), allow_redirects=False,
)
if not 200 <= response.status_code < 300:
raise RuntimeError(f"HTTP {response.status_code}; request_id={response.headers.get('X-Request-ID', '')}; retry_after={response.headers.get('Retry-After', '')}")
if False:
if response.headers.get("Content-Type") != "image/webp" or len(response.content) > 5242880:
raise ValueError("Unexpected image response")
with open(os.environ["SHOPENTLY_OUTPUT_FILE"], "xb") as output:
output.write(response.content)
else:
result = response.json() if response.content else None
print(json.dumps(result, ensure_ascii=False, indent=2))
Exemplo de resposta 200
{
"data": {
"availability": {
"available_from": null,
"available_until": null,
"is_available": true
},
"brand_id": null,
"condition": "new",
"created_at": "2026-01-01T12:00:00Z",
"description": "example",
"features": [
{
"feature_id": "example",
"feature_name": "example",
"value": "example",
"value_id": "example"
}
],
"id": "example",
"identifiers": {},
"media": [
{
"alt_text": "example",
"id": "example",
"is_primary": true,
"kind": "image",
"mime_type": "image/jpeg",
"position": 1,
"url": "https://example.invalid/product.jpg"
}
],
"meta_description": "example",
"meta_keywords": [
"example"
],
"meta_title": "example",
"name": "Example",
"number": "example",
"price": {
"amount": "0.00",
"currency": "PLN",
"minor_units": 2,
"tax_included": true
},
"price_version": 1,
"primary_category_id": "example",
"primary_media_id": "example",
"published": false,
"sku": "example",
"slug": "example",
"tax_category_id": "example",
"updated_at": "2026-01-01T12:00:00Z",
"variants_enabled": false,
"version": 1
},
"meta": {
"locale": "en",
"market_code": "PL",
"market_id": "example",
"request_id": "example"
}
}
Como funciona
- A integração pode ler produtos não excluídos, incluindo rascunhos, exceto os bloqueados por um limite do plano.
- Produtos bloqueados são omitidos das listas; o acesso direto retorna entitlements.resource_blocked.
- Assim, a visibilidade na API difere da publicação na loja.
- Use identificadores existentes de marcas, categorias, características e arquivos de mídia.
- Os preços incluem moeda, lista de preços, tratamento fiscal e versões explícitas de concorrência.
- Preços de produtos e variantes são distintos; use a estrutura de preços aceita e textos decimais exatos.
Parâmetros
Parâmetros do caminho
product_idTextoObrigatórioIdentificador do produto.
Restrições
pattern"^[a-z0-9][a-z0-9_-]{0,62}$"
Parâmetros de consulta
localeTexto nullOpcionalIdioma selecionado para esta requisição.
Texto:minLength:2maxLength:20market_idTexto nullOpcionalIdentificador do mercado retornado pelo endpoint de contexto.
Restrições · Texto 1
pattern"^[a-z0-9][a-z0-9_-]{0,62}$"
market_codeTexto nullOpcionalCódigo do mercado retornado pelo endpoint de contexto.
Texto:minLength:1maxLength:16
Esta operação não aceita um corpo JSON.
Respostas
Resposta 200
Modelo completo: ApiResponse_ProductDetailData_
dataProductDetailDataObrigatórioConteúdo de uma resposta bem-sucedida.
Campos ·
dataModelo completo:
ProductDetailDataavailabilityAvailabilityDataObrigatórioInformações de disponibilidade no contexto selecionado.
Campos ·
availabilityModelo completo:
AvailabilityDataavailable_fromTexto nullObrigatórioInício da disponibilidade.
Texto:format:"date-time"available_untilTexto nullObrigatórioFim da disponibilidade.
Texto:format:"date-time"is_availableBooleanoObrigatórioIndica se o item está disponível neste contexto.
brand_idTexto nullObrigatórioIdentificador da marca.
conditionTextoObrigatórioCondição do produto.
Restrições
enum["new", "refurbished", "used", "returned", "display", "damaged"]
created_atTextoObrigatórioMomento da criação.
format:"date-time"descriptionTexto nullObrigatórioDescrição no idioma selecionado.
featuresLista <FeatureSelectionData> ObrigatórioCaracterísticas do produto.
Campos ·
featuresidTextoObrigatórioIdentificador do recurso; preserve-o conforme retornado.
identifiersObjetoCampos adicionais: TextoObrigatórioCódigos de identificação do produto.
mediaLista <ProductMediaData> ObrigatórioInformações dos arquivos de mídia anexados.
Campos ·
mediameta_descriptionTexto nullObrigatórioDescrição para mecanismos de pesquisa no idioma selecionado.
meta_keywordsLista <Texto> nullObrigatórioPalavras-chave para mecanismos de pesquisa no idioma selecionado.
meta_titleTexto nullObrigatórioTítulo para mecanismos de pesquisa no idioma selecionado.
nameTexto nullObrigatórioNome do recurso no contexto correspondente.
numberTextoObrigatórioNúmero do pedido ou da solicitação exibido ao usuário.
pricePriceDatanullObrigatórioInformações do preço no contexto selecionado.
Campos ·
priceprice_versionNúmero inteiroObrigatórioVersão atual do preço para controle de concorrência.
primary_category_idTexto nullObrigatórioIdentificador da categoria principal.
primary_media_idTexto nullObrigatórioIdentificador do arquivo de mídia principal.
publishedBooleanoObrigatórioIndica se o recurso está publicado.
skuTextoObrigatórioCódigo da unidade de manutenção de estoque.
slugTexto nullObrigatórioSegmento do caminho da URL no idioma selecionado.
tax_category_idTextoObrigatórioIdentificador da categoria fiscal.
updated_atTextoObrigatórioMomento da atualização mais recente.
format:"date-time"variants_enabledBooleanoObrigatórioIndica se o produto utiliza variantes.
versionNúmero inteiroObrigatórioVersão do recurso utilizada para controle de concorrência.
metaContextPageMetaContextMetaPageMetaRequestMetaObrigatórioMetadados da resposta.
Campos ·
metaModelo completo:
ContextPageMetalocaleTextoObrigatórioIdioma selecionado para esta requisição.
market_codeTextoObrigatórioCódigo do mercado retornado pelo endpoint de contexto.
market_idTextoObrigatórioIdentificador do mercado retornado pelo endpoint de contexto.
paginationPaginationObrigatórioMetadados da paginação por cursor.
request_idTextoObrigatórioIdentificador da solicitação; nos metadados da resposta identifica a requisição HTTP.
minLength:1maxLength:100
localeTextoObrigatórioIdioma selecionado para esta requisição.
market_codeTextoObrigatórioCódigo do mercado retornado pelo endpoint de contexto.
market_idTextoObrigatórioIdentificador do mercado retornado pelo endpoint de contexto.
request_idTextoObrigatórioIdentificador da solicitação; nos metadados da resposta identifica a requisição HTTP.
minLength:1maxLength:100
paginationPaginationObrigatórioMetadados da paginação por cursor.
request_idTextoObrigatórioIdentificador da solicitação; nos metadados da resposta identifica a requisição HTTP.
minLength:1maxLength:100
request_idTextoObrigatórioIdentificador da solicitação; nos metadados da resposta identifica a requisição HTTP.
minLength:1maxLength:100
Estado HTTP
200- Resposta bem-sucedida Esquema
400- Requisição inválida
401- Autenticação necessária
403- Permissão negada
404- Recurso não encontrado
409- Conflito de versão
422- Falha na validação
429- Limite de requisições excedido
Outros status HTTP (7)
405- Método não permitido
413- Requisição muito grande
415- Formato não suportado
500- Erro do servidor
502- Erro do gateway da API
503- Serviço indisponível
504- Tempo de espera excedido
Catálogo de erros: ErrorResponse
Cabeçalhos
401
WWW-AuthenticateTextoOpcionalEsquema de autenticação exigido pelo servidor.
405
AllowTextoOpcionalMétodos HTTP aceitos por este recurso.
429, 503
Retry-AfterNúmero inteiroOpcionalEspera mínima antes de tentar novamente, em segundos.
minimum:0