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

عرض القائمة — طلبات الشراء

اقرأ بيانات «طلبات الشراء». تعتمد النتيجة على معلمات هذه العملية.

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

JSON
{
  "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: 100
القيمة الافتراضية: 50مثال: 20
cursorسلسلة نصية nullاختياري

قيمة متابعة معتمة أعادتها الصفحة السابقة.

سلسلة نصية:minLength: 1maxLength: 1024
numberسلسلة نصية nullاختياري

رقم طلب الشراء أو طلب الخدمة المعروض للمستخدم.

سلسلة نصية:minLength: 1maxLength: 48
status_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

dataمصفوفة <OrderSummaryData > مطلوب

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

الحقول · data

OrderSummaryData

created_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 مطلوب

المبلغ الإجمالي.

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