وثائق API المنتجات

واجهة API للقراءة فقط لكتالوج المنتجات للموزعين والشركاء.

يوثّق هذا المرجع حقول JSON العامة للقراءة فقط التي تشغّل بطاقات منتجات EmpireX وصفحات التفاصيل وفلاتر الفئات وشارات المخزون والفئات المسعّرة بـ VND/USD. لا يتم كشف أي بيانات خاصة.

1. البدء السريع

اجلب عناصر الكتالوج النشطة عبر نقاط نهاية القائمة لعرض بطاقات المتجر بالصور المصغرة والعناوين المترجمة وأسعار VND/USD والخصومات وحالة التوفر.

GET /api/accounts

GET /api/services

GET /api/products/{id-or-slug}

2. واجهة API لقائمة الكتالوج

GET /api/accounts?page=1&limit=20&sort=price&order=asc&locale=ar&category_id=cat-ai-tools

المعامل (Query)	الوصف	مثال
category_id	تصفية العناصر حسب معرّف فئة المتجر	cat-ai-tools
sort	حقل الترتيب: view_count أو created_at أو price	price
order	اتجاه الترتيب: asc أو desc	asc
page	رقم الصفحة (يبدأ من 1)	1
limit	عدد العناصر في الصفحة (الافتراضي في المتجر 20)	20
locale	لغة الاستجابة المفضلة	ar

{
  "success": true,
  "data": {
    "items": [
      {
        "id": "prod_chatgpt_plus",
        "slug": "chatgpt-plus-nang-cap-chinh-chu",
        "type": "account",
        "name_vi": "ChatGPT Plus - Nâng cấp chính chủ",
        "name_en": "ChatGPT Plus - Official Upgrade",
        "thumbnail": "https://empirex.org/images/chatgpt-plus.webp",
        "inventory_status": "in-stock",
        "categories": [
          {
            "category": {
              "id": "cat-ai-tools",
              "name_vi": "AI Tools",
              "name_en": "AI Tools",
              "slug": "ai-tools"
            }
          }
        ],
        "variants": [
          {
            "id": "var_1m",
            "name_vi": "Gói 1 tháng",
            "name_en": "1 Month",
            "price_vnd": 135000,
            "price_usd": 5.5,
            "original_price_vnd": 550000,
            "original_price_usd": 22,
            "stock": true,
            "is_default": true,
            "sku": "CGPT-PLUS-1M"
          }
        ]
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 20,
      "total": 120,
      "totalPages": 6
    }
  }
}

3. واجهة API لتفاصيل المنتج

استخدم نقطة النهاية هذه عند فتح صفحة منتج فردي لتحميل الأوصاف الكاملة وصور المعرض ومدة الضمان وشروط التسليم.

GET /api/products/chatgpt-plus-nang-cap-chinh-chu

{
  "success": true,
  "data": {
    "id": "prod_chatgpt_plus",
    "slug": "chatgpt-plus-nang-cap-chinh-chu",
    "type": "account",
    "name_vi": "ChatGPT Plus - Nâng cấp chính chủ",
    "name_en": "ChatGPT Plus - Official Upgrade",
    "description_vi": "Mô tả chi tiết đang hiển thị ở trang sản phẩm.",
    "description_en": "Product detail description shown on the product page.",
    "thumbnail": "https://empirex.org/images/chatgpt-plus.webp",
    "inventory_status": "in-stock",
    "delivery_type_vi": "Giao tài khoản thủ công",
    "delivery_type_en": "Manual account delivery",
    "vietnam_only": false,
    "variant_layout": "default",
    "images": [
      {
        "image_url": "https://empirex.org/images/chatgpt-plus-1.webp",
        "locale": "vi",
        "order_index": 1
      }
    ],
    "categories": [
      {
        "category": {
          "id": "cat-ai-tools",
          "name_vi": "AI Tools",
          "name_en": "AI Tools",
          "slug": "ai-tools"
        }
      }
    ],
    "variants": [
      {
        "id": "var_1m",
        "name_vi": "Gói 1 tháng",
        "name_en": "1 Month",
        "sku": "CGPT-PLUS-1M",
        "price_vnd": 135000,
        "price_usd": 5.5,
        "original_price_vnd": 550000,
        "original_price_usd": 22,
        "stock": true,
        "is_default": true,
        "warranty_duration": 1,
        "warranty_unit": "month",
        "image": "https://empirex.org/images/chatgpt-plus-variant.webp",
        "images": []
      }
    ]
  }
}

4. حقول مخطط المنتج (Schema)

id

معرّف فريد للمنتج يُستخدم لجلب التفاصيل وعناصر السلة وإتمام الدفع.

slug

معرّف الرابط النصي للمنتج، مثل /ar/accounts/chatgpt-plus.

type

نوع مسار الكتالوج: account أو service.

name_vi / name_en

عناوين المنتج المترجمة حسب اللغة.

thumbnail

الصورة الرئيسية للبطاقة المعروضة في صفحات قوائم الكتالوج.

inventory_status

مؤشر التوفر الرئيسي المعروض على البطاقات وصفحات التفاصيل.

categories

الفئات المرتبطة لتصفية وتجميع المنتجات في المتجر.

variants

باقات وخيارات الاشتراك مع أسعار VND وUSD والأسعار الأصلية ورمز SKU والمخزون.

description_vi / description_en

الأوصاف التفصيلية المترجمة للمنتج المعروضة في صفحات التفاصيل.

images

صور معرض المنتج المرتبة في صفحة التفاصيل.

delivery_type_vi / delivery_type_en

طريقة التسليم المترجمة المعروضة ضمن مميزات المنتج.

warranty_duration / warranty_unit

مدة ووحدة تغطية الضمان لكل باقة.

vietnam_only

عند القيمة true، يشير إلى أن التفعيل أو الاستخدام مخصص لمنطقة فيتنام فقط.

variant_layout

نمط عرض محدد الباقات: default أو matrix_2d أو matrix_3d.

5. قيم حالة المخزون

in-stock

متوفر للإضافة الفورية إلى السلة وإتمام الشراء.

low-stock

كمية متبقية محدودة؛ يعرض شارة مخزون منخفض.

out-of-stock

غير متوفر مؤقتاً؛ يتم تعطيل أزرار الشراء.

price = 0

منتج بعرض سعر مخصص ("اطلب عرض سعر")؛ يتم إخفاء زر الشراء العادي.