跳至內容
ShopentlyLearn

取得 — 產品

讀取「產品」的資料。結果取決於此操作的參數。

GET/api/v1/products/{product_id}

身份驗證
Bearer
最低方案
STANDARD
所需權限
catalog.product:read

程式碼範例

請求示例

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))

回應示例 200

JSON
{
  "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"
  }
}

工作原理

  • 整合可以讀取所有未刪除的產品,包括草稿,但不包括被方案限制阻止的產品。
  • 被阻止的產品不出現在清單中;直接存取回傳 entitlements.resource_blocked。
  • 因此,產品在 API 中的可見性不同於店面發佈狀態。
  • 使用品牌、分類、屬性和媒體的現有識別碼。
  • 價格包含明確的幣種、價格表、稅務模式和並行控制版本。
  • 產品定價與變體定價相互獨立;請使用支援的價格結構及精確的十進位字串。

參數

路徑參數

product_id字串必填

產品識別碼。

約束
pattern
"^[a-z0-9][a-z0-9_-]{0,62}$"
示例: "example"

查詢參數

locale字串 null選填

本次請求選擇的語言。

字串:minLength: 2maxLength: 20
market_id字串 null選填

上下文端點回傳的市場識別碼。

約束 · 字串 1
pattern
"^[a-z0-9][a-z0-9_-]{0,62}$"
market_code字串 null選填

上下文端點回傳的市場代碼。

字串:minLength: 1maxLength: 16

此操作不接受 JSON 請求本文。

回應

回應 200

dataProductDetailData 必填

成功回應的資料。

欄位 · data
availabilityAvailabilityData 必填

所選上下文中的可用性資訊。

欄位 · availability
available_from字串 null必填

開始可用的時間。

字串:format: "date-time"
available_until字串 null必填

結束可用的時間。

字串:format: "date-time"
is_available布林值必填

此項目在目前上下文中是否可用。

brand_id字串 null必填

品牌識別碼。

condition字串必填

產品狀況。

約束
enum
["new", "refurbished", "used", "returned", "display", "damaged"]
created_at字串必填

建立時間。

format: "date-time"
description字串 null必填

所選語言的描述。

features陣列 <FeatureSelectionData > 必填

產品屬性。

欄位 · features
id字串必填

資源識別碼;請保留回傳的原值。

identifiers物件附加欄位: 字串必填

產品識別代碼。

media陣列 <ProductMediaData > 必填

附加媒體資訊。

欄位 · media
meta_description字串 null必填

所選語言的搜尋引擎描述。

meta_keywords陣列 <字串> null必填

所選語言的搜尋引擎關鍵詞。

meta_title字串 null必填

所選語言的搜尋引擎標題。

name字串 null必填

對應上下文中的資源名稱。

number字串必填

面向使用者的訂單號或申請編號。

pricePriceData null必填

所選上下文中的價格資訊。

欄位 · price
price_version整數必填

用於並行控制的目前價格版本。

primary_category_id字串 null必填

主要分類識別碼。

primary_media_id字串 null必填

主要媒體資產識別碼。

published布林值必填

資源是否已發佈。

sku字串必填

庫存單位代碼。

slug字串 null必填

所選語言的 URL 路徑段。

tax_category_id字串必填

稅務類別識別碼。

updated_at字串必填

最近更新時間。

format: "date-time"
variants_enabled布林值必填

產品是否使用變體。

version整數必填

用於並行控制的資源版本。

metaContextPageMeta ContextMeta PageMeta RequestMeta 必填

回應元資料。

欄位 · meta

ContextPageMeta

locale字串必填

本次請求選擇的語言。

market_code字串必填

上下文端點回傳的市場代碼。

market_id字串必填

上下文端點回傳的市場識別碼。

paginationPagination 必填

遊標分頁元資料。

request_id字串必填

申請識別碼;在回應元資料中表示 HTTP 請求識別碼。

minLength: 1maxLength: 100

ContextMeta

locale字串必填

本次請求選擇的語言。

market_code字串必填

上下文端點回傳的市場代碼。

market_id字串必填

上下文端點回傳的市場識別碼。

request_id字串必填

申請識別碼;在回應元資料中表示 HTTP 請求識別碼。

minLength: 1maxLength: 100

PageMeta

paginationPagination 必填

遊標分頁元資料。

request_id字串必填

申請識別碼;在回應元資料中表示 HTTP 請求識別碼。

minLength: 1maxLength: 100

RequestMeta

request_id字串必填

申請識別碼;在回應元資料中表示 HTTP 請求識別碼。

minLength: 1maxLength: 100
回應示例

HTTP 狀態

200
請求成功 架構
400
無效請求
401
需要身分驗證
403
權限不足
404
找不到資源
409
版本衝突
422
驗證失敗
429
超出請求限制
其他 HTTP 狀態 (7)
405
不允許的方法
413
請求過大
415
不支援的格式
500
伺服器錯誤
502
API 閘道錯誤
503
服務無法使用
504
閘道逾時

錯誤目錄: ErrorResponse

請求標頭與回應標頭

401

WWW-Authenticate字串選填

伺服器要求的身份驗證方案。

405

Allow字串選填

此資源支援的 HTTP 方法。

429, 503

Retry-After整數選填

重試前最少等待的秒數。

minimum: 0