جلب · رمز الوصول — المصادقة
احصل على رمز 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
{
"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
النموذج الكامل: ApiResponse_TokenData_
dataTokenDataمطلوبمحتوى الاستجابة الناجحة.
الحقول ·
dataaccess_tokenسلسلة نصيةمطلوببيانات اعتماد Bearer قصيرة الأجل.
expires_atسلسلة نصيةمطلوبتاريخ انتهاء صلاحية بيانات الاعتماد ووقته.
format:"date-time"expires_inعدد صحيحاختياريمدة صلاحية بيانات الاعتماد بالثواني.
rate_limitsTokenRateLimitsDataمطلوبتتضمن كل استجابة للرمز data.rate_limits من سياسة المتجر وقت إصداره. تتشارك جميع المفاتيح هذه الحدود؛ إصدار رمز جديد لا يعيد ضبطها. قد يسري تغيير الخطة قبل انتهاء صلاحية الرمز.
الحقول ·
rate_limitsالنموذج الكامل:
TokenRateLimitsDataauth_per_minuteعدد صحيحمطلوبطلبات الرمز في الدقيقة، بما فيها محاولات المصادقة الفاشلة.
minimum:0maximum:1000000read_per_minuteعدد صحيحمطلوبطلبات القراءة في الدقيقة.
minimum:0maximum:1000000write_per_minuteعدد صحيحمطلوبطلبات الكتابة في الدقيقة؛ لا تمنح هذه القيمة صلاحيات الكتابة.
minimum:0maximum:1000000
token_typeسلسلة نصيةاختيارينظام المصادقة للرمز المعاد.
const:"Bearer"
metaContextPageMetaContextMetaPageMetaRequestMetaمطلوبالبيانات الوصفية للاستجابة.
الحقول ·
metaالنموذج الكامل:
ContextPageMetalocaleسلسلة نصيةمطلوباللغة المحددة لهذا الطلب.
market_codeسلسلة نصيةمطلوبرمز السوق الذي تعيده نقطة نهاية السياق.
market_idسلسلة نصيةمطلوبمعرّف السوق الذي تعيده نقطة نهاية السياق.
paginationPaginationمطلوبالبيانات الوصفية للترقيم باستخدام المؤشر.
request_idسلسلة نصيةمطلوبمعرّف الطلب؛ في البيانات الوصفية للاستجابة يحدد طلب HTTP.
minLength:1maxLength:100
localeسلسلة نصيةمطلوباللغة المحددة لهذا الطلب.
market_codeسلسلة نصيةمطلوبرمز السوق الذي تعيده نقطة نهاية السياق.
market_idسلسلة نصيةمطلوبمعرّف السوق الذي تعيده نقطة نهاية السياق.
request_idسلسلة نصيةمطلوبمعرّف الطلب؛ في البيانات الوصفية للاستجابة يحدد طلب HTTP.
minLength:1maxLength:100
paginationPaginationمطلوبالبيانات الوصفية للترقيم باستخدام المؤشر.
request_idسلسلة نصيةمطلوبمعرّف الطلب؛ في البيانات الوصفية للاستجابة يحدد طلب HTTP.
minLength:1maxLength:100
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