跳至内容
ShopentlyLearn

更新 — 产品

修改“产品”中的指定数据。必填字段和写入规则如下所述。

PATCH/api/v1/products/{product_id}

身份验证
Bearer
最低套餐
STANDARD
所需权限
catalog.product:update
特定字段所需的附加权限
  • 提供 variant_value_ids 时: catalog.product_variant:create, catalog.product_variant:update, catalog.product_variant:delete
  • 提供 variants_enabled 时: catalog.product_variant:update
了解更多

代码示例

请求示例

cURL

: "${SHOPENTLY_SHOP_URL:?}"

curl --disable --globoff --fail-with-body --silent --show-error \
  --proto '=https' --connect-timeout 5 --max-time 30 \
  --request PATCH \
  --header "Authorization: Bearer ${SHOPENTLY_ACCESS_TOKEN:?}" \
  --header 'Idempotency-Key: example-update_product_api_v1_products__product_id__patch' \
  --header 'Content-Type: application/json' \
  --data-raw '{
  "expected_version": 1,
  "sku": "example"
}' \
  --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 = ['Idempotency-Key: example-update_product_api_v1_products__product_id__patch', 'Content-Type: application/json'];
$headers[] = 'Authorization: Bearer ' . $credential;
$responseHeaders = [];
$handle = curl_init($baseUrl . '/api/v1/products/example');
curl_setopt_array($handle, [
    CURLOPT_CUSTOMREQUEST => 'PATCH',
    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);
    },
]);
curl_setopt($handle, CURLOPT_POSTFIELDS, '{
  "expected_version": 1,
  "sku": "example"
}');
$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 = {'Idempotency-Key': 'example-update_product_api_v1_products__product_id__patch'}
headers["Authorization"] = 'Bearer' + " " + credential
body = '{\n  "expected_version": 1,\n  "sku": "example"\n}'
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(
        'PATCH', 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": {
    "deleted": false,
    "id": "example",
    "version": 1
  },
  "meta": {
    "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

请求头

Idempotency-Key字符串必填

单个逻辑写入操作的唯一标识符。

minLength: 1maxLength: 128
约束
pattern
"^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$"
示例: "example-update_product_api_v1_products__product_id__patch"

请求体

application/json · 必填

ProductUpdate
brand_id字符串 null可选

品牌标识符。

字符串:minLength: 1maxLength: 63
condition字符串可选

产品状况。

约束
enum
["new", "refurbished", "used", "returned", "display", "damaged"]
description字符串 null可选

所选语言的描述。

字符串:maxLength: 100000
示例: null
expected_variant_price_versions对象附加字段: 整数
minimum: 0maximum: 9223372036854775807
可选

此前读取的价格版本,以变体标识符为键。

maxProperties: 250
约束
propertyNames
{"maxLength": 63, "minLength": 1}
expected_version整数必填

写入前读取的版本;不匹配时拒绝更新。

minimum: 1maximum: 9223372036854775807
示例: 1
feature_value_ids数组 <字符串> 可选

所选属性值的标识符。

maxItems: 1000
数组:minLength: 1maxLength: 63
identifiersProductIdentifiers null可选

产品识别代码。

market_ids数组 <字符串> 可选

所选市场的标识符。

maxItems: 1000
数组:minLength: 1maxLength: 63
media_ids数组 <字符串> 可选

已存在媒体资产的标识符。

maxItems: 20
数组:minLength: 1maxLength: 63
meta_description字符串 null可选

所选语言的搜索引擎描述。

字符串:maxLength: 160
meta_keywords数组 <字符串> null可选

所选语言的搜索引擎关键词。

数组:maxItems: 20
数组 / 数组:maxLength: 50
meta_title字符串 null可选

所选语言的搜索引擎标题。

字符串:maxLength: 70
name字符串 null可选

对应上下文中的资源名称。

字符串:maxLength: 300
示例: null
pricingProductPrice 可选

价格配置及其并发控制版本。

示例: {"amount":"0.00","currency":"PLN","expected_price_list_version":1,"expected_version":0,"kind":"base","price_list_id":"example","tax_included":true}
primary_category_id字符串 null可选

主要分类标识符。

字符串:minLength: 1maxLength: 63
published布尔值可选

资源是否已发布。

sku字符串可选

库存单位代码。

minLength: 1maxLength: 100
约束
pattern
"^\\S+$"
示例: "example"
slug字符串 null可选

所选语言的 URL 路径段。

字符串:maxLength: 160
tax_category_id字符串 null可选

税务类别标识符。

字符串:minLength: 1maxLength: 63
variant_value_ids数组 <字符串> 可选

所选变体值的标识符。

maxItems: 250
数组:minLength: 1maxLength: 63
variants_enabled布尔值可选

产品是否使用变体。

响应

响应 200

dataMutationData 必填

成功响应的数据。

字段 · data
deleted布尔值必填

是否已执行删除。

id字符串必填

资源标识符;请保留返回的原值。

version整数 null必填

用于并发控制的资源版本。

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