Obține — Produse
Citiți datele din „Produse”. Rezultatul depinde de parametrii acestei operațiuni.
GET/api/v1/products/{product_id}
- Autentificare
Bearer- Disponibil începând cu
- STANDARD
- Permisiuni necesare
catalog.product:read
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 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))
Exemplu de răspuns 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"
}
}
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 caractereObligatoriuIdentificatorul produsului.
Restricții
pattern"^[a-z0-9][a-z0-9_-]{0,62}$"
Parametri de interogare
localeȘir de caractere nullOpționalLimba selectată pentru această cerere.
Șir de caractere:minLength:2maxLength:20market_idȘir de caractere nullOpționalIdentificatorul 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ționalCodul pieței returnat de endpointul de context.
Șir de caractere:minLength:1maxLength:16
Această operație nu acceptă un corp JSON.
Răspunsuri
Răspuns 200
Model complet: ApiResponse_ProductDetailData_
dataProductDetailDataObligatoriuDatele unui răspuns reușit.
Câmpuri ·
dataModel complet:
ProductDetailDataavailabilityAvailabilityDataObligatoriuInformații despre disponibilitate în contextul selectat.
Câmpuri ·
availabilityModel complet:
AvailabilityDataavailable_fromȘir de caractere nullObligatoriuÎnceputul disponibilității.
Șir de caractere:format:"date-time"available_untilȘir de caractere nullObligatoriuSfârșitul disponibilității.
Șir de caractere:format:"date-time"is_availableValoare booleanăObligatoriuIndică dacă articolul este disponibil în acest context.
brand_idȘir de caractere nullObligatoriuIdentificatorul mărcii.
conditionȘir de caractereObligatoriuStarea produsului.
Restricții
enum["new", "refurbished", "used", "returned", "display", "damaged"]
created_atȘir de caractereObligatoriuMomentul creării.
format:"date-time"descriptionȘir de caractere nullObligatoriuDescriere în limba selectată.
featuresTablou <FeatureSelectionData> ObligatoriuCaracteristicile produsului.
Câmpuri ·
featuresidȘir de caractereObligatoriuIdentificatorul resursei; păstrați-l în forma returnată.
identifiersObiectCâmpuri suplimentare: Șir de caractereObligatoriuCodurile de identificare ale produsului.
mediaTablou <ProductMediaData> ObligatoriuInformații despre fișierele media atașate.
Câmpuri ·
mediameta_descriptionȘir de caractere nullObligatoriuDescriere pentru motoarele de căutare, în limba selectată.
meta_keywordsTablou <Șir de caractere> nullObligatoriuCuvinte-cheie pentru motoarele de căutare, în limba selectată.
meta_titleȘir de caractere nullObligatoriuTitlu pentru motoarele de căutare, în limba selectată.
nameȘir de caractere nullObligatoriuNumele resursei în contextul relevant.
numberȘir de caractereObligatoriuNumărul comenzii sau al solicitării, destinat utilizatorilor.
pricePriceDatanullObligatoriuInformații despre preț în contextul selectat.
Câmpuri ·
priceprice_versionNumăr întregObligatoriuVersiunea curentă a prețului, pentru controlul concurenței.
primary_category_idȘir de caractere nullObligatoriuIdentificatorul categoriei principale.
primary_media_idȘir de caractere nullObligatoriuIdentificatorul fișierului media principal.
publishedValoare booleanăObligatoriuIndică dacă resursa este publicată.
skuȘir de caractereObligatoriuCodul unității de stoc.
slugȘir de caractere nullObligatoriuSegmentul căii URL în limba selectată.
tax_category_idȘir de caractereObligatoriuIdentificatorul categoriei fiscale.
updated_atȘir de caractereObligatoriuMomentul celei mai recente actualizări.
format:"date-time"variants_enabledValoare booleanăObligatoriuIndică dacă produsul folosește variante.
versionNumăr întregObligatoriuVersiunea resursei folosită pentru controlul concurenței.
metaContextPageMetaContextMetaPageMetaRequestMetaObligatoriuMetadatele răspunsului.
Câmpuri ·
metaModel complet:
ContextPageMetalocaleȘir de caractereObligatoriuLimba selectată pentru această cerere.
market_codeȘir de caractereObligatoriuCodul pieței returnat de endpointul de context.
market_idȘir de caractereObligatoriuIdentificatorul pieței returnat de endpointul de context.
paginationPaginationObligatoriuMetadatele paginării prin cursor.
request_idȘir de caractereObligatoriuIdentificatorul solicitării; în metadatele răspunsului identifică cererea HTTP.
minLength:1maxLength:100
localeȘir de caractereObligatoriuLimba selectată pentru această cerere.
market_codeȘir de caractereObligatoriuCodul pieței returnat de endpointul de context.
market_idȘir de caractereObligatoriuIdentificatorul pieței returnat de endpointul de context.
request_idȘir de caractereObligatoriuIdentificatorul solicitării; în metadatele răspunsului identifică cererea HTTP.
minLength:1maxLength:100
paginationPaginationObligatoriuMetadatele paginării prin cursor.
request_idȘir de caractereObligatoriuIdentificatorul solicitării; în metadatele răspunsului identifică cererea HTTP.
minLength:1maxLength:100
request_idȘir de caractereObligatoriuIdentificatorul solicitării; în metadatele răspunsului identifică cererea HTTP.
minLength:1maxLength:100
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ționalSchema de autentificare cerută de server.
405
AllowȘir de caractereOpționalMetodele HTTP acceptate de această resursă.
429, 503
Retry-AfterNumăr întregOpționalÎntârzierea minimă înainte de reîncercare, în secunde.
minimum:0