انتقل إلى المحتوى
ShopentlyLearn

العروض الترويجية · جلب

العروض الترويجية · جلب. يجب أن يسمح كل رمز بالدمج. تُطبّق الخصومات بالتتابع.

GET/api/v1/discounts/promotions/{identity}

المصادقة
Bearer
متاح بدءًا من
STANDARD
الصلاحيات المطلوبة
discounts.promotions: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/discounts/promotions/example-campaign

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/discounts/promotions/example-campaign');
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/discounts/promotions/example-campaign', 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": {
    "created_at": "2026-10-07T10:00:00Z",
    "created_by": {
      "kind": "admin",
      "label": "Editorial integration",
      "reference": "learn-api-key"
    },
    "enabled": false,
    "id": "example-campaign",
    "kind": "coupon",
    "markets": [
      {
        "currency": "PLN",
        "market_id": "poland",
        "minor_units": 0
      }
    ],
    "name": "Autumn guide offer",
    "updated_at": "2026-10-07T10:00:00Z",
    "used_count": 0,
    "version": 1
  },
  "meta": {
    "locale": "example",
    "market_code": "example",
    "market_id": "poland",
    "pagination": {
      "has_more": false,
      "limit": 1,
      "next_cursor": null
    },
    "request_id": "learn-example-request"
  }
}

نظرة عامة

تُجمع المنتجات والفئات المحددة. تشمل الفئات المنتجات المرتبطة بها مباشرة.

المعاملات

معلمات المسار

identityسلسلة نصيةمطلوب

المعرّف المستخدم في مسار هذا المورد.

القيود
pattern
"^[a-z0-9][a-z0-9_-]{0,62}$"
مثال: "example-campaign"

لا تقبل هذه العملية محتوى JSON.

الاستجابات

الاستجابة 200

dataCampaignData مطلوب

محتوى الاستجابة الناجحة.

الحقول · data
audienceسلسلة نصيةاختياري

العملاء

القيود
enum
["all", "guest", "customer", "selected"]

القيمة الافتراضية: "all"

benefit_typeسلسلة نصيةاختياري

صيغة بنية البيانات التي تحددها القيم المسموح بها.

القيود
enum
["percentage", "fixed", "none"]

القيمة الافتراضية: "percentage"

category_idsمصفوفة <سلسلة نصية> اختياري

معرّفات الفئات المرتبطة.

maxItems: 1000
القيود · مصفوفة 1
pattern
"^[a-z0-9][a-z0-9_-]{0,62}$"
codeسلسلة نصية nullاختياري

رمز ثابت قابل للقراءة آليًا.

القيود · سلسلة نصية 1
pattern
"^[A-Za-z0-9]{6,16}$"
combine_couponsقيمة منطقيةاختياري

الدمج مع رموز أخرى

القيمة الافتراضية: false

combine_promotionsقيمة منطقيةاختياري

السماح بهذا الرمز للمنتجات المشمولة بعروض تلقائية

القيمة الافتراضية: false

created_atسلسلة نصيةمطلوب

وقت الإنشاء.

format: "date-time"
created_byCreatorData مطلوب

أنشأه

الحقول · created_by
kindسلسلة نصيةمطلوب

صيغة بنية البيانات التي تحددها القيم المسموح بها.

القيود
enum
["admin", "api"]
labelسلسلة نصيةمطلوب

اسم المورد في السياق المناسب.

referenceسلسلة نصيةمطلوب

معرّف الكيان المشار إليه.

customer_idsمصفوفة <سلسلة نصية> اختياري

معلومات العميل المسجلة لهذا المورد.

maxItems: 1000
القيود · مصفوفة 1
pattern
"^[a-z0-9][a-z0-9_-]{0,62}$"
enabledقيمة منطقيةمطلوب

ما إذا كان هذا الإعداد مفعّلًا.

ends_atسلسلة نصية nullاختياري

نشط حتى

سلسلة نصية:format: "date-time"
free_shippingقيمة منطقيةاختياري

شحن مجاني

القيمة الافتراضية: false

idسلسلة نصيةمطلوب

معرّف المورد؛ احتفظ به كما أعيد.

kindسلسلة نصيةمطلوب

صيغة بنية البيانات التي تحددها القيم المسموح بها.

القيود
enum
["coupon", "promotion"]
minimum_quantityعدد صحيحاختياري

الحد الأدنى لعدد القطع في السلة

minimum: 1maximum: 2147483647

القيمة الافتراضية: 1

nameسلسلة نصيةمطلوب

اسم المورد في السياق المناسب.

minLength: 1maxLength: 160
per_customer_limitعدد صحيحاختياري

الحد الأقصى للاستخدامات لكل عميل

minimum: -1maximum: 2147483647

القيمة الافتراضية: -1

percentageسلسلة نصيةاختياري

نسبة مئوية

maxLength: 19
القيود
pattern
"^(0|[1-9][0-9]{0,13})(\\.[0-9]{1,4})?$"

القيمة الافتراضية: "10"

product_idsمصفوفة <سلسلة نصية> اختياري

معرّفات المنتجات المرتبطة.

maxItems: 1000
القيود · مصفوفة 1
pattern
"^[a-z0-9][a-z0-9_-]{0,62}$"
product_scopeسلسلة نصيةاختياري

المنتجات

القيود
enum
["all", "selected"]

القيمة الافتراضية: "all"

show_accountقيمة منطقيةاختياري

في حساب العميل

القيمة الافتراضية: false

show_cartقيمة منطقيةاختياري

في السلة

القيمة الافتراضية: false

show_productقيمة منطقيةاختياري

على صفحات المنتجات

القيمة الافتراضية: false

starts_atسلسلة نصية nullاختياري

نشط من

سلسلة نصية:format: "date-time"
updated_atسلسلة نصيةمطلوب

وقت آخر تحديث.

format: "date-time"
usage_limitعدد صحيحاختياري

الحد الأقصى للاستخدامات

minimum: -1maximum: 2147483647

القيمة الافتراضية: -1

used_countعدد صحيحمطلوب

عدد مرات الاستخدام

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