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

جلب · رمز الوصول — المصادقة

احصل على رمز Shopently API صالح لمدة 900 ثانية. راجع ترويسة ApiKey والاستجابة واستخدام Bearer في الطلبات التالية.

POST/api/v1/auth/token

المصادقة
ApiKey
متاح بدءًا من
BASIC
الصلاحيات المطلوبة
لا ينطبق

أمثلة الكود

مثال على الطلب

cURL

: "${SHOPENTLY_SHOP_URL:?}"

curl --disable --globoff --fail-with-body --silent --show-error \
  --proto '=https' --connect-timeout 5 --max-time 30 \
  --request POST \
  --header "Authorization: ApiKey ${SHOPENTLY_API_KEY:?}" \
  --header 'Content-Type: application/json' \
  --data-raw '{}' \
  --url "${SHOPENTLY_SHOP_URL%/}"/api/v1/auth/token

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_API_KEY') ?: '';
if ($credential === '' || strpbrk($credential, "\r\n") !== false) {
    throw new RuntimeException('Invalid credential');
}
$headers = ['Content-Type: application/json'];
$headers[] = 'Authorization: ApiKey ' . $credential;
$responseHeaders = [];
$handle = curl_init($baseUrl . '/api/v1/auth/token');
curl_setopt_array($handle, [
    CURLOPT_CUSTOMREQUEST => 'POST',
    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, '{}');
$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_API_KEY']
if not credential or "\r" in credential or "\n" in credential:
    raise ValueError("Invalid credential")
headers = {}
headers["Authorization"] = 'ApiKey' + " " + credential
body = '{}'
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(
        'POST', base_url + '/api/v1/auth/token', 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": {
    "access_token": "EXAMPLE_ACCESS_TOKEN",
    "expires_at": "2026-01-01T12:00:00Z",
    "expires_in": 900,
    "rate_limits": {
      "auth_per_minute": 10,
      "read_per_minute": 60,
      "write_per_minute": 10
    },
    "token_type": "Bearer"
  },
  "meta": {
    "request_id": "example"
  }
}

المصادقة

  • يُرسل مفتاح API حصريًا في ترويسة Authorization لطلب POST /api/v1/auth/token.
  • لا تضعه في JSON أو عنوان URL أو معاملات الاستعلام.
  • استخدم الرمز المعاد لطلبات الموارد، وجدده وفق expires_at؛ تُعبّر expires_in عن المدة بالثواني.
  • لا يتجاوز رمز الوصول التحقق من صلاحيات المفتاح الحالية أو استحقاقات المتجر أو إلغاء المفتاح أو قيود IP.

ما مدة صلاحية الرمز؟

  • expires_in: 900 ثانية، أي 15 دقيقة من وقت الإصدار. إرسال الطلبات لا يمدد الصلاحية.
  • expires_at: وقت انتهاء الصلاحية بتوقيت UTC. قد تمنع قيود الوصول الحالية استخدام الرمز قبل ذلك.

أعد استخدام الرمز نفسه لطلبات متعددة واحصل على رمز جديد قبل expires_at. لا تطلب رمزًا قبل كل عملية. استخدم مفتاح API للحصول على الرمز الجديد.

حدود معدل الطلبات

Engine ≥ 4.143.0. تتضمن كل استجابة للرمز data.rate_limits من سياسة المتجر وقت إصداره. تتشارك جميع المفاتيح هذه الحدود؛ إصدار رمز جديد لا يعيد ضبطها. قد يسري تغيير الخطة قبل انتهاء صلاحية الرمز.

المعاملات

لا توجد معاملات للمسار أو الاستعلام أو ترويسات إضافية.

محتوى الطلب

application/json · اختياري

TokenRequest null

الاستجابات

الاستجابة 200

dataTokenData مطلوب

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

الحقول · data
access_tokenسلسلة نصيةمطلوب

بيانات اعتماد Bearer قصيرة الأجل.

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

تاريخ انتهاء صلاحية بيانات الاعتماد ووقته.

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

مدة صلاحية بيانات الاعتماد بالثواني.

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

rate_limitsTokenRateLimitsData مطلوب

تتضمن كل استجابة للرمز data.rate_limits من سياسة المتجر وقت إصداره. تتشارك جميع المفاتيح هذه الحدود؛ إصدار رمز جديد لا يعيد ضبطها. قد يسري تغيير الخطة قبل انتهاء صلاحية الرمز.

الحقول · rate_limits
auth_per_minuteعدد صحيحمطلوب

طلبات الرمز في الدقيقة، بما فيها محاولات المصادقة الفاشلة.

minimum: 0maximum: 1000000
read_per_minuteعدد صحيحمطلوب

طلبات القراءة في الدقيقة.

minimum: 0maximum: 1000000
write_per_minuteعدد صحيحمطلوب

طلبات الكتابة في الدقيقة؛ لا تمنح هذه القيمة صلاحيات الكتابة.

minimum: 0maximum: 1000000
token_typeسلسلة نصيةاختياري

نظام المصادقة للرمز المعاد.

const: "Bearer"

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

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.0