Treci la conținut
ShopentlyLearn

Actualizează — Produse

Modificați datele indicate din „Produse”. Câmpurile obligatorii și regulile de scriere sunt descrise mai jos.

PATCH/api/v1/products/{product_id}

Autentificare
Bearer
Disponibil începând cu
STANDARD
Permisiuni necesare
catalog.product:update
Permisiuni suplimentare pentru câmpurile selectate
  • Când este inclus variant_value_ids: catalog.product_variant:create, catalog.product_variant:update, catalog.product_variant:delete
  • Când este inclus variants_enabled: catalog.product_variant:update
Află mai multe

Exemple de cod

Exemplu de cerere

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

Exemplu de răspuns 200

JSON
{
  "data": {
    "deleted": false,
    "id": "example",
    "version": 1
  },
  "meta": {
    "request_id": "example"
  }
}

Cum funcționează

  • Integrarea poate citi produsele neșterse, inclusiv ciornele, cu excepția produselor blocate de o limită a planului.
  • Produsele blocate sunt excluse din liste; accesul direct returnează entitlements.resource_blocked.
  • Vizibilitatea în API diferă astfel de publicarea în magazin.
  • Folosiți identificatori existenți pentru mărci, categorii, caracteristici și fișiere media.
  • Prețurile au monedă, listă de prețuri, mod de taxare și versiuni de concurență explicite.
  • Prețurile produselor și ale variantelor sunt distincte; folosiți structura acceptată și șiruri zecimale exacte.

Parametri

Parametrii căii

product_idȘir de caractereObligatoriu

Identificatorul produsului.

Restricții
pattern
"^[a-z0-9][a-z0-9_-]{0,62}$"
Exemplu: "example"

Parametri de interogare

localeȘir de caractere nullOpțional

Limba selectată pentru această cerere.

Șir de caractere:minLength: 2maxLength: 20
market_idȘir de caractere nullOpțional

Identificatorul pieței returnat de endpointul de context.

Restricții · Șir de caractere 1
pattern
"^[a-z0-9][a-z0-9_-]{0,62}$"
market_codeȘir de caractere nullOpțional

Codul pieței returnat de endpointul de context.

Șir de caractere:minLength: 1maxLength: 16

Antetele cererii

Idempotency-KeyȘir de caractereObligatoriu

Identificator unic pentru o operație logică de scriere.

minLength: 1maxLength: 128
Restricții
pattern
"^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$"
Exemplu: "example-update_product_api_v1_products__product_id__patch"

Corpul cererii

application/json · Obligatoriu

ProductUpdate
brand_idȘir de caractere nullOpțional

Identificatorul mărcii.

Șir de caractere:minLength: 1maxLength: 63
conditionȘir de caractereOpțional

Starea produsului.

Restricții
enum
["new", "refurbished", "used", "returned", "display", "damaged"]
descriptionȘir de caractere nullOpțional

Descriere în limba selectată.

Șir de caractere:maxLength: 100000
Exemplu: null
expected_variant_price_versionsObiectCâmpuri suplimentare: Număr întreg
minimum: 0maximum: 9223372036854775807
Opțional

Versiunile prețurilor citite anterior, indexate după identificatorul variantei.

maxProperties: 250
Restricții
propertyNames
{"maxLength": 63, "minLength": 1}
expected_versionNumăr întregObligatoriu

Versiunea citită înainte de scriere; o neconcordanță respinge actualizarea.

minimum: 1maximum: 9223372036854775807
Exemplu: 1
feature_value_idsTablou <Șir de caractere> Opțional

Identificatorii valorilor selectate ale caracteristicilor.

maxItems: 1000
Tablou:minLength: 1maxLength: 63
identifiersProductIdentifiers nullOpțional

Codurile de identificare ale produsului.

market_idsTablou <Șir de caractere> Opțional

Identificatorii piețelor selectate.

maxItems: 1000
Tablou:minLength: 1maxLength: 63
media_idsTablou <Șir de caractere> Opțional

Identificatorii fișierelor media deja existente.

maxItems: 20
Tablou:minLength: 1maxLength: 63
meta_descriptionȘir de caractere nullOpțional

Descriere pentru motoarele de căutare, în limba selectată.

Șir de caractere:maxLength: 160
meta_keywordsTablou <Șir de caractere> nullOpțional

Cuvinte-cheie pentru motoarele de căutare, în limba selectată.

Tablou:maxItems: 20
Tablou / Tablou:maxLength: 50
meta_titleȘir de caractere nullOpțional

Titlu pentru motoarele de căutare, în limba selectată.

Șir de caractere:maxLength: 70
nameȘir de caractere nullOpțional

Numele resursei în contextul relevant.

Șir de caractere:maxLength: 300
Exemplu: null
pricingProductPrice Opțional

Configurația prețurilor și versiunile pentru controlul concurenței.

Exemplu: {"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Șir de caractere nullOpțional

Identificatorul categoriei principale.

Șir de caractere:minLength: 1maxLength: 63
publishedValoare booleanăOpțional

Indică dacă resursa este publicată.

skuȘir de caractereOpțional

Codul unității de stoc.

minLength: 1maxLength: 100
Restricții
pattern
"^\\S+$"
Exemplu: "example"
slugȘir de caractere nullOpțional

Segmentul căii URL în limba selectată.

Șir de caractere:maxLength: 160
tax_category_idȘir de caractere nullOpțional

Identificatorul categoriei fiscale.

Șir de caractere:minLength: 1maxLength: 63
variant_value_idsTablou <Șir de caractere> Opțional

Identificatorii valorilor selectate ale variantelor.

maxItems: 250
Tablou:minLength: 1maxLength: 63
variants_enabledValoare booleanăOpțional

Indică dacă produsul folosește variante.

Răspunsuri

Răspuns 200

dataMutationData Obligatoriu

Datele unui răspuns reușit.

Câmpuri · data
deletedValoare booleanăObligatoriu

Indică dacă ștergerea a fost aplicată.

idȘir de caractereObligatoriu

Identificatorul resursei; păstrați-l în forma returnată.

versionNumăr întreg nullObligatoriu

Versiunea resursei folosită pentru controlul concurenței.

metaContextPageMeta ContextMeta PageMeta RequestMeta Obligatoriu

Metadatele răspunsului.

Câmpuri · meta

ContextPageMeta

localeȘir de caractereObligatoriu

Limba selectată pentru această cerere.

market_codeȘir de caractereObligatoriu

Codul pieței returnat de endpointul de context.

market_idȘir de caractereObligatoriu

Identificatorul pieței returnat de endpointul de context.

paginationPagination Obligatoriu

Metadatele paginării prin cursor.

request_idȘir de caractereObligatoriu

Identificatorul solicitării; în metadatele răspunsului identifică cererea HTTP.

minLength: 1maxLength: 100

ContextMeta

localeȘir de caractereObligatoriu

Limba selectată pentru această cerere.

market_codeȘir de caractereObligatoriu

Codul pieței returnat de endpointul de context.

market_idȘir de caractereObligatoriu

Identificatorul pieței returnat de endpointul de context.

request_idȘir de caractereObligatoriu

Identificatorul solicitării; în metadatele răspunsului identifică cererea HTTP.

minLength: 1maxLength: 100

PageMeta

paginationPagination Obligatoriu

Metadatele paginării prin cursor.

request_idȘir de caractereObligatoriu

Identificatorul solicitării; în metadatele răspunsului identifică cererea HTTP.

minLength: 1maxLength: 100

RequestMeta

request_idȘir de caractereObligatoriu

Identificatorul solicitării; în metadatele răspunsului identifică cererea HTTP.

minLength: 1maxLength: 100
Exemplu de răspuns

Stare HTTP

200
Răspuns reușit Schemă
400
Cerere nevalidă
401
Autentificare necesară
403
Acces refuzat
404
Resursa nu a fost găsită
409
Conflict de versiune
422
Validare eșuată
429
Limită de cereri depășită
Alte stări HTTP (7)
405
Metodă nepermisă
413
Cerere prea mare
415
Format neacceptat
500
Eroare de server
502
Eroare de gateway API
503
Serviciu indisponibil
504
Timp de așteptare depășit

Catalog de erori: ErrorResponse

Antete

401

WWW-AuthenticateȘir de caractereOpțional

Schema de autentificare cerută de server.

405

AllowȘir de caractereOpțional

Metodele HTTP acceptate de această resursă.

429, 503

Retry-AfterNumăr întregOpțional

Întârzierea minimă înainte de reîncercare, în secunde.

minimum: 0