عرض القائمة — طلبات الشراء
اقرأ بيانات «طلبات الشراء». تعتمد النتيجة على معلمات هذه العملية.
GET/api/v1/orders
- المصادقة
Bearer- متاح بدءًا من
- BASIC
- الصلاحيات المطلوبة
orders.order: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/orders?limit=20'
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/orders?limit=20');
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/orders?limit=20', 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": [
{
"created_at": "2026-10-19T10:00:00Z",
"customer": {
"email": "customer@example.invalid",
"first_name": "Example",
"last_name": "Example",
"phone": null
},
"delivery": {
"amount": {
"amount": "0.00",
"currency": "PLN",
"minor_units": 2
},
"dates": {
"dispatch_timezone": "Europe/Warsaw",
"estimated_delivery_from": "2026-10-20",
"estimated_delivery_to": "2026-10-21",
"planned_dispatch_on": "2026-10-19"
},
"method_code": "shipping-old",
"method_name": "Historic carrier",
"pickup_point": null,
"recipient_mode": "full_address"
},
"discount_amount": {
"amount": "24.60",
"currency": "PLN",
"minor_units": 2
},
"id": "order-0000",
"lifecycle_state": "placed",
"locale": "pl",
"market_id": "market-pl",
"number": "0001",
"payment": {
"amount": {
"amount": "329.40",
"currency": "PLN",
"minor_units": 2
},
"environment": "live",
"method_code": "payment-old",
"method_name": "Historic method",
"paid_at": null,
"status": "unpaid",
"updated_at": "2026-10-19T10:00:00Z",
"version": 0
},
"prices_include_tax": true,
"shipping_discount_amount": {
"amount": "24.60",
"currency": "PLN",
"minor_units": 2
},
"status": {
"id": "status-0",
"name": "Status 0",
"updated_at": "2026-10-19T10:00:00Z",
"version": 1
},
"subtotal": {
"amount": "329.40",
"currency": "PLN",
"minor_units": 2
},
"tax": {
"amount": "49.40",
"currency": "PLN",
"minor_units": 2
},
"tax_country_code": "PL",
"total": {
"amount": "329.40",
"currency": "PLN",
"minor_units": 2
}
}
],
"meta": {
"pagination": {
"has_more": false,
"limit": 20,
"next_cursor": null
},
"request_id": "example"
}
}
آلية العمل
- توفر المجموعة ملخصات الطلبات ومرشحات حسب الرقم والحالة وحالة الدفع ووقت الإنشاء.
- تتضمن قائمة الطلبات وتفاصيلها delivery.dates. التواريخ بصيغة YYYY-MM-DD مخططة ولا تؤكد الشحن الفعلي. للتواريخ الحالية الأولوية؛ وتستخدم الطلبات القديمة التقدير المحفوظ. القيم المحذوفة أو غير المعروفة هي null. تتضمن التفاصيل أيضًا جميع بنود الطلب وصور المنتجات.
- احصل على معرّفات حالات صالحة من /api/v1/order-statuses.
- تستخدم حالة الطلب وحالة الدفع نقطتي نهاية PATCH وصلاحيات منفصلة.
- لا يؤدي تغيير حالة الدفع المسجلة إلى خصم مبلغ من بطاقة أو إصدار استرداد عبر مزود دفع.
الطلب · المجاميع
تأتي المبالغ ومعدلات الضريبة من الطلب المحفوظ، بما يشمل تصحيحات البنود. تكون البيانات التاريخية المفقودة null ولا تُستبدل بمعدلات الكتالوج الحالية. تبقى المبالغ سلاسل نصية عشرية.
تعيد القائمة ملخصات. اجلب GET /api/v1/orders/{order_id} لكل نتيجة لتصدير التفاصيل المالية الكاملة. محاولات GET محدودة وتلتزم بـ Retry-After. لا يزامن التصدير حسب تاريخ الإنشاء التصحيحات اللاحقة.
المعاملات
معلمات الاستعلام
limitعدد صحيحاختياريالعدد الأقصى للسجلات في هذه الصفحة.
minimum:1maximum:100cursorسلسلة نصية nullاختياريقيمة متابعة معتمة أعادتها الصفحة السابقة.
سلسلة نصية:minLength:1maxLength:1024numberسلسلة نصية nullاختياريرقم طلب الشراء أو طلب الخدمة المعروض للمستخدم.
سلسلة نصية:minLength:1maxLength:48status_idسلسلة نصية nullاختياريمعرّف مأخوذ من دليل الحالات المناسب.
القيود · سلسلة نصية 1
pattern"^[a-z0-9][a-z0-9_-]{0,62}$"
payment_statusسلسلة نصية nullاختياريحالة الدفع المسجلة.
القيود · سلسلة نصية 1
enum["unpaid", "paid", "failed", "refunded"]
created_fromسلسلة نصية nullاختياريبداية مرشح وقت الإنشاء.
سلسلة نصية:format:"date-time"created_toسلسلة نصية nullاختيارينهاية مرشح وقت الإنشاء.
سلسلة نصية:format:"date-time"
لا تقبل هذه العملية محتوى JSON.
الاستجابات
الاستجابة 200
النموذج الكامل: ApiResponse_list_OrderSummaryData__
dataمصفوفة <OrderSummaryData> مطلوبمحتوى الاستجابة الناجحة.
الحقول ·
dataالنموذج الكامل:
OrderSummaryDatacreated_atسلسلة نصيةمطلوبوقت الإنشاء.
format:"date-time"customerCustomerDataمطلوبمعلومات العميل المسجلة لهذا المورد.
deliveryShippingDataمطلوبطريقة التسليم والمعلومات المرتبطة بها.
discount_amountMoneyDataمطلوبمبلغ عشري ممثل كسلسلة JSON؛ يسمح بالقيمة null فقط حيث يكون ذلك مسموحًا.
idسلسلة نصيةمطلوبمعرّف المورد؛ احتفظ به كما أعيد.
lifecycle_stateOrderLifecycleStateمطلوبحالة دورة حياة المورد.
localeسلسلة نصيةمطلوباللغة المحددة لهذا الطلب.
market_idسلسلة نصيةمطلوبمعرّف السوق الذي تعيده نقطة نهاية السياق.
numberسلسلة نصيةمطلوبرقم طلب الشراء أو طلب الخدمة المعروض للمستخدم.
paymentPaymentDataمطلوبتفاصيل الدفع المسجلة للطلب.
prices_include_taxقيمة منطقيةمطلوبما إذا كانت أسعار القائمة تشمل الضرائب.
shipping_discount_amountMoneyDataمطلوبمبلغ عشري ممثل كسلسلة JSON؛ يسمح بالقيمة null فقط حيث يكون ذلك مسموحًا.
statusOrderStatusDataمطلوبالحالة التي تقبلها هذه العملية تحديدًا.
subtotalMoneyDataمطلوبالمبلغ قبل المكونات الإضافية الموضحة في الاستجابة.
taxMoneyDataمطلوبالمعلومات الضريبية.
tax_country_codeسلسلة نصية nullمطلوببلد الضريبة · بيانات الطلب المحفوظة · ISO 3166-1 alpha-2; null.
totalMoneyDataمطلوبالمبلغ الإجمالي.
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