getRelatedProductsById

البحث عن جميع المنتجات المرتبطة حسب معرّف المنتج.

الوصف

يجلب المنتجات المرتبطة بالمنتج ذي المعرّف id المحدد. يقبل userQuery الاختياري معلمات الترقيم والفرز (offset وlimit وsortOrder وsortKey) وstatusMarker وtemplateMarker وrelationMode وsignPrice. يُعيد IProductsResponse: المنتجات في items، والعدد الإجمالي في total.

.getRelatedProductsById( , , );

مخطط المعلمات

المخطط

id: number
معرّف المنتج المراد البحث عن منتجات ذات صلة به.
مثال: 12345

langCode: string
رمز اللغة. الافتراضي: langCode المُمرَّر إلى defineOneEntry ("en_US" إذا لم يُمرَّر).
مثال: "en_US"

userQuery: IProductsRelatedQuery
معاملات استعلام اختيارية.
مثال:

{
  "limit": 30,
  "offset": 0,
  "sortOrder": "DESC",
  "sortKey": "id",
  "signPrice": "orders",
  "statusMarker": "in_stock",
  "templateMarker": "template_12345"
}

userQuery.offset(required): number
عدد السجلات المراد تخطيها. الافتراضي: 0. يجب ألا يتجاوز offset + limit القيمة 200؛ وتُرفض النافذة الأكبر بالخطأ 400.

userQuery.limit(required): number
الحد الأقصى لعدد السجلات المراد إرجاعها. الافتراضي: 30.

userQuery.sortOrder(required): string
ترتيب الفرز: "DESC" أو "ASC". الافتراضي: "DESC".

userQuery.sortKey(required): string
الحقل المراد الفرز حسبه: "id" أو "position" أو "title" أو "date" أو "price" أو "status". الافتراضي: "position".

userQuery.signPrice: string
علامة مخزن الطلبات الذي تُثبَّت الأسعار له. عند تعيينها يأتي كل منتج مع signedPrice الذي يثبّت السعر لفترة محدودة.
see: Fixing the price

userQuery.statusMarker: string | null
علامة حالة المنتج. الافتراضي: null.
مثال: "in_stock"

userQuery.templateMarker: string | null
علامة قالب المنتج. الافتراضي: null.
مثال: "template_12345"

userQuery.relationMode: string
طريقة حساب العلاقات: "global" (الافتراضي) ينفّذ سلسلة شروط القالب كما هي؛ و"local" يشترط إضافيًا أن تستوفي قيمة سمة المنتج id شرط القالب (المعامل نفسه والقيمة المخزنة نفسها) قبل الاحتفاظ بمنتجات تلك الخطوة.
مثال: "local"

حد السجلات. إذا كانت صلاحية مجموعة المستخدمين لهذه الطريقة تسمح بالقراءة المقيدة فقط، تُرجع واجهة API عددًا من السجلات لا يتجاوز العدد المحدد في إعدادات المشروع (10 افتراضيًا)، أيًّا كانت قيمة limit التي تمررها. مع صلاحية القراءة الكاملة يعمل limit كالمعتاد. راجع Module permissions (يفتح في علامة تبويب جديدة).

يثبّت signPrice السعر المُعاد لفترة محدودة. عيّنه إلى علامة تخزين الطلبات الخاصة بك. انظر تثبيت السعر (signPrice).

أمثلة

مثال بسيط

const response = await Products.getRelatedProductsById(2954);

مثال مع userQuery

const  = {
  "offset": 0,
  "limit": 30,
  "sortOrder": "DESC",
  "sortKey": "id"
};
const response = await Products.getRelatedProductsById(2954, 'en_US', userQuery);

مثال على الاستجابة

يعرض المثال شكل عنصر واحد، كما تُعيده getProducts().

{
  "total": 1,
  "items": [
    {
      "id": 2954,
      "localizeInfos": {
        "title": "Box"
      },
      "isVisible": true,
      "isSync": false,
      "sku": null,
      "price": 51,
      "additional": {
        "prices": {
          "min": 51,
          "max": 180
        }
      },
      "categories": [
        "catalog"
      ],
      "statusIdentifier": "sale",
      "statusLocalizeInfos": {
        "title": "Sale"
      },
      "templateIdentifier": null,
      "shortDescTemplateIdentifier": "product_preview",
      "attributeValues": {
        "product-name": {
          "type": "string",
          "value": "product-name",
          "isIcon": false,
          "position": 0,
          "additionalFields": {},
          "isProductPreview": false
        },
        "price": {
          "type": "integer",
          "value": 51,
          "isIcon": false,
          "position": 1,
          "additionalFields": {},
          "isProductPreview": false
        },
        "currency_products": {
          "type": "string",
          "value": "usd",
          "isIcon": false,
          "position": 2,
          "additionalFields": {},
          "isProductPreview": false
        }
      },
      "attributeSetIdentifier": "products",
      "isPositionLocked": false,
      "position": 1,
      "rating": {},
      "paymentStages": null,
      "moduleFormConfigs": [
        {
          "id": 12,
          "formIdentifier": "review",
          "moduleIdentifier": "catalog",
          "isGlobal": false,
          "isClosed": false,
          "isModerate": false,
          "viewOnlyMyData": false,
          "commentOnlyMyData": false,
          "entityIdentifiers": [
            {
              "id": "catalog",
              "isNested": true
            }
          ],
          "formDataCount": 823,
          "ratingCalculation": "average",
          "allowHalfRatings": null,
          "maxRatingScale": null,
          "isAnonymous": null,
          "allowRerating": null,
          "isRating": null,
          "entityFormDataCount": {
            "2954": 823
          },
          "nestedEntityIdentifiers": [
            "catalog"
          ],
          "exceptionIds": []
        }
      ],
      "discountConfig": {}
    }
  ]
}

مخطط الاستجابة

المخطط: IProductsResponse

total: number
العدد الإجمالي للمنتجات التي عُثر عليها.
مثال: 100

items: IProductsEntity[]
المنتجات في هذه الاستجابة.
مثال:

[
  {
    "id": 12345,
    "title": "Product 1"
  },
  {
    "id": 67890,
    "title": "Product 2"
  }
]

items.id: number
معرّف المنتج.
مثال: 12345

items.localizeInfos: ILocalizeInfo
بيانات المنتج المترجمة، مثل العنوان.
مثال:

{}

items.statusIdentifier: string | null
علامة حالة المنتج، أو null.
مثال: "in_stock"

items.statusLocalizeInfos: ILocalizeInfo
اسم الحالة المترجم للمنتج.
مثال:

{ "title": "Sale" }

items.attributeSetIdentifier: string | null
علامة مجموعة السمات، أو null إذا لم تُعيَّن.
مثال: "set_12345"

items.position: number
الموضع المستخدم للفرز.
مثال: 1

items.price: number | null
سعر المنتج من فهرس البحث.
مثال: 150.00

items.additional: object
قيم إضافية يحسبها فهرس البحث، مثل نطاق السعر في prices.min وprices.max.
مثال:

{
  "prices": {
    "min": 5,
    "max": 150
  }
}

items.sku: string | null
رمز SKU للمنتج من فهرس البحث، أو null.
مثال: "SKU_12345"

items.isSync: boolean
ما إذا كان فهرس سمات المنتج محدّثًا للغة المطلوبة. عند false يعني attributeValues الفارغ أو الناقص أن القيم لم تُنشر بعد، لا أنها غير موجودة.
مثال: true

items.attributeValues: IAttributeValues
قيم السمات مفهرسة حسب علامة السمة.
مثال:

{
  "color": {
    "type": "string",
    "value": "red",
    "isIcon": false,
    "position": 0,
    "additionalFields": {}
  }
}

items.categories: string[]
روابط صفحات الكتالوج التي ينتمي إليها المنتج.
مثال:

[
  "catalog"
]

items.isVisible: boolean
هل المنتج ظاهر.
مثال: true

items.moduleFormConfigs: Array<IFormConfig>
إعدادات نماذج الوحدة.

items.rating: IRating
بيانات التقييم: القيمة المتوسطة، والإعجابات وعدمها، وطريقة الحساب.

items.isPositionLocked: boolean
هل موضع الفرز مقفل.
مثال: false

items.relatedIds: number[]
معرّفات المنتجات المرتبطة.
مثال:

[
  12345,
  67890
]

items.paymentStages: unknown
مراحل الدفع للمنتج: مصفوفة من كائنات { title, value, marker }، أو null عندما لا تكون مُعيَّنة.
مثال: null

items.distance: number
مسافة الصلة في البحث المتجهي (الدلالي). موجودة فقط في نتائج البحث المتجهي.
مثال: 0.42

items.discountConfig: Record<string, unknown>
إعدادات الخصم.
مثال:

{}

items.templateIdentifier: string | null
علامة القالب المرتبط.
مثال: "template_12345"

items.shortDescTemplateIdentifier: string | null
علامة القالب المستخدم للوصف المختصر.
مثال: "short_desc_template_12345"

items.signedPrice: string
رمز موقّع (JWT) يثبّت سعر المنتج لطلب ما. يُعاد عند تعيين signPrice.
see: Fixed product price
مثال: "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

items.productPages: IProductPageRef[]
الروابط بين المنتج وصفحات الكتالوج التي ينتمي إليها.
مثال:

[
  {
    "id": 16,
    "pageId": 4,
    "productId": 15,
    "positionId": 244,
    "categoryPath": "products"
  }
]

items.blocks: string[]
علامات الكتل المرتبطة بالمنتج.
مثال:

[
  "block_12345",
  "block_67890"
]

totalFound: number
عدد المنتجات المطابقة قبل تطبيق الحدود؛ تُعيده نقاط نهاية منتجات الكتل (similarProducts، وتوصيات سلة التسوق وقائمة الأمنيات، والمنتجات المطلوبة معًا كثيرًا). اختياري.
مثال: 2

signedPrice هو رمز موقّع يحمل السعر المثبّت. أعِده عند إنشاء الطلب. انظر سعر المنتج الثابت (signedPrice).

---