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

جلب — الإرجاع والشكاوى والاستبدال

اقرأ بيانات «الإرجاع والشكاوى والاستبدال». تعتمد النتيجة على معلمات هذه العملية.

GET/api/v1/requests/{request_id}

المصادقة
Bearer
متاح بدءًا من
BASIC
الصلاحيات المطلوبة
returns.request: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/requests/example

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/requests/example');
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/requests/example', 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-01-01T12:00:00Z",
    "customer": {
      "email": "customer@example.invalid",
      "name": "Example"
    },
    "id": "example",
    "items": [
      {
        "id": "example",
        "name": "Example",
        "order_line_id": "example",
        "product_id": "example",
        "quantity": 1,
        "returned_quantity": 1,
        "sku": "example",
        "total": {
          "amount": "0.00",
          "currency": "PLN",
          "minor_units": 2
        },
        "unit_price": {
          "amount": "0.00",
          "currency": "PLN",
          "minor_units": 2
        },
        "variant_id": "example",
        "variant_options": [
          {
            "name": "Example",
            "value": "example"
          }
        ]
      }
    ],
    "number": "example",
    "order_id": "example",
    "order_number": "example",
    "products_value": {
      "amount": "0.00",
      "currency": "PLN",
      "minor_units": 2
    },
    "refund": {
      "amount": {
        "amount": "0.00",
        "currency": "PLN",
        "minor_units": 2
      },
      "completed_at": null,
      "status": "pending",
      "updated_at": "2026-01-01T12:00:00Z",
      "version": 1
    },
    "resolution_state": "unknown",
    "status": {
      "id": "example",
      "locale": "en",
      "name": "Example"
    },
    "type": "return",
    "updated_at": "2026-01-01T12:00:00Z",
    "version": 1
  },
  "meta": {
    "request_id": "example"
  }
}

آلية العمل

  • استخدم نقطتي نهاية المجموعة والتفاصيل لرقم الطلب ونوعه وطلب الشراء المرتبط والعناصر المقدمة وبيانات العميل ومعلومات الاسترداد.
  • الأنواع الصالحة هي return وexchange وcomplaint.
  • احصل على معرّفات الحالات من /api/v1/request-statuses.
  • الحالة ومبلغ الاسترداد عمليتا كتابة منفصلتان مع التحقق من الإصدار.
  • يحدّث تغيير مبلغ الاسترداد المسجل سجل طلب الخدمة؛ ولا ينفذ تحويلًا ماليًا.

المعاملات

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

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

معرّف الطلب؛ في البيانات الوصفية للاستجابة يحدد طلب HTTP.

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

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

الاستجابات

الاستجابة 200

dataRequestDetailData مطلوب

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

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

وقت الإنشاء.

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

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

الحقول · customer
emailسلسلة نصيةمطلوب

عنوان البريد الإلكتروني.

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

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

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

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

itemsمصفوفة <RequestItemData > مطلوب

العناصر المضمنة في المورد.

الحقول · items
numberسلسلة نصيةمطلوب

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

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

معرّف طلب الشراء المرتبط.

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

رقم طلب الشراء المرتبط.

products_valueMoneyData مطلوب

قيمة المنتجات في طلب الشراء.

الحقول · products_value
amountسلسلة نصيةمطلوب

مبلغ عشري ممثل كسلسلة JSON؛ يسمح بالقيمة null فقط حيث يكون ذلك مسموحًا.

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

رمز عملة المبلغ.

القيود
pattern
"^[A-Z]{3}$"
minor_unitsعدد صحيحمطلوب

عدد المنازل العشرية التي تستخدمها العملة.

minimum: 0maximum: 4
refundRefundData مطلوب

معلومات المبلغ المسترد المسجلة.

الحقول · refund
amountMoneyData nullمطلوب

مبلغ عشري ممثل كسلسلة JSON؛ يسمح بالقيمة null فقط حيث يكون ذلك مسموحًا.

completed_atسلسلة نصية nullمطلوب

وقت الاكتمال.

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

الحالة التي تقبلها هذه العملية تحديدًا.

القيود
enum
["pending", "completed"]
updated_atسلسلة نصية nullمطلوب

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

سلسلة نصية:format: "date-time"
versionعدد صحيحمطلوب

إصدار المورد المستخدم للتحكم في التعديلات المتزامنة.

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

حالة معالجة طلب خدمة العميل.

القيود
enum
["unknown", "open", "completed", "rejected", "cancelled"]
statusRequestStatusData مطلوب

الحالة التي تقبلها هذه العملية تحديدًا.

الحقول · status
idسلسلة نصيةمطلوب

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

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

اللغة المحددة لهذا الطلب.

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

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

typeRequestType مطلوب

نوع المورد.

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

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

format: "date-time"
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