---
url: 'https://dxpr.com/ar/hc/%D8%A7%D9%84%D8%AA%D9%88%D8%AB%D9%8A%D9%82/%D8%AA%D8%B9%D9%84%D9%85-dxpr-builder/%D8%A7%D9%84%D9%85%D8%B1%D8%AC%D8%B9/%D9%86%D9%82%D8%A7%D8%B7-%D9%86%D9%87%D8%A7%D9%8A%D8%A9-api'
title: 'نقاط نهاية API | DXPR'
author:
  name: Jurriaan
  url: 'https://dxpr.com/users/jurriaan'
date: '2026-10-24T08:09:20+00:00'
updated: '2026-10-24T17:19:22+00:00'
copyright: 'Copyright DXPR. All rights reserved.'
type: article
summary: |-
  تسرد هذه الصفحة كل مسار يسجّله DXPR Builder في
  dxpr_builder.routing.yml، مع طرق HTTP ومتطلبات
  الوصول ومعاملات الطلب وأشكال الاستجابة كما
  نُفِّذت في المتحكمات. فـ JavaScript المحرر هي
  العميل المقصود لنقاط نهاية AJAX؛ ولا شيء في هذه الصفحة
  واجهة API عامة مستقرة، وقد تتغير أسماء المعاملات بين
  الإصدارات.
  متطلبات الوصول
  تستخدم المسارات ثلاثة أنواع من المتطلبات. ويمكن للمسار الجمع بينها.
tags:
  - 'Configuration and API'
image: 'https://dxpr.com/themes/custom/dxpr_com/images/dxpr-share-card.jpg'
published: true
og:
  site_name: DXPR
  updated_time: '2026-10-24T17:19:22+0000'
  'image:alt': 'DXPR, powered by Drupal: AI-powered Drupal for marketers.'
schema:
  '@context': 'https://schema.org'
  '@graph':
    -
      mainEntity: {  }
    -
      '@type': TechArticle
      headline: 'نقاط نهاية API'
      description: |-
        تسرد هذه الصفحة كل مسار يسجّله DXPR Builder في
        dxpr_builder.routing.yml، مع طرق HTTP ومتطلبات
        الوصول ومعاملات الطلب وأشكال الاستجابة كما
        نُفِّذت في المتحكمات. فـ JavaScript المحرر هي
        العميل المقصود لنقاط نهاية AJAX؛ ولا شيء في هذه الصفحة
        واجهة API عامة مستقرة، وقد تتغير أسماء المعاملات بين
        الإصدارات.
        متطلبات الوصول
        تستخدم المسارات ثلاثة أنواع من المتطلبات. ويمكن للمسار الجمع بينها.
      image:
        '@type': ImageObject
        url: 'https://dxpr.com/themes/custom/dxpr_com/images/dxpr-share-card.jpg'
        width: '1200'
        height: '630'
      datePublished: '2026-10-24T08:09:20+0000'
      dateModified: '2026-10-24T17:19:22+0000'
      author:
        '@type': Organization
        '@id': 'https://dxpr.com/#organization'
        name: DXPR
        url: 'https://dxpr.com/'
        logo:
          '@type': ImageObject
          url: 'https://dxpr.com/themes/custom/dxpr_com/dxpr-logo-dark.svg'
          width: '1348'
          height: '501'
      publisher:
        '@type': Organization
        '@id': 'https://dxpr.com/#organization'
        name: DXPR
        url: 'https://dxpr.com/'
        logo:
          '@type': ImageObject
          url: 'https://dxpr.com/themes/custom/dxpr_com/dxpr-logo-dark.svg'
          width: '1348'
          height: '501'
      mainEntityOfPage: 'https://dxpr.com/ar/hc/%D8%A7%D9%84%D8%AA%D9%88%D8%AB%D9%8A%D9%82/%D8%AA%D8%B9%D9%84%D9%85-dxpr-builder/%D8%A7%D9%84%D9%85%D8%B1%D8%AC%D8%B9/%D9%86%D9%82%D8%A7%D8%B7-%D9%86%D9%87%D8%A7%D9%8A%D8%A9-api'
      articleSection: 'الإعداد وAPI'
    -
      '@type': WebPage
      '@id': 'https://dxpr.com/ar/hc/%D8%A7%D9%84%D8%AA%D9%88%D8%AB%D9%8A%D9%82/%D8%AA%D8%B9%D9%84%D9%85-dxpr-builder/%D8%A7%D9%84%D9%85%D8%B1%D8%AC%D8%B9/%D9%86%D9%82%D8%A7%D8%B7-%D9%86%D9%87%D8%A7%D9%8A%D8%A9-api'
      description: |-
        تسرد هذه الصفحة كل مسار يسجّله DXPR Builder في
        dxpr_builder.routing.yml، مع طرق HTTP ومتطلبات
        الوصول ومعاملات الطلب وأشكال الاستجابة كما
        نُفِّذت في المتحكمات. فـ JavaScript المحرر هي
        العميل المقصود لنقاط نهاية AJAX؛ ولا شيء في هذه الصفحة
        واجهة API عامة مستقرة، وقد تتغير أسماء المعاملات بين
        الإصدارات.
        متطلبات الوصول
        تستخدم المسارات ثلاثة أنواع من المتطلبات. ويمكن للمسار الجمع بينها.
      breadcrumb:
        '@type': BreadcrumbList
        itemListElement:
          -
            '@type': ListItem
            position: 1
            name: الرئيسية
            item: 'https://dxpr.com/ar'
      publisher:
        '@type': Organization
        '@id': 'https://dxpr.com/#organization'
        name: DXPR
      inLanguage: ar
---
[مركز المساعدة](/ar/hc)/[التوثيق](/ar/hc/%D8%A7%D9%84%D8%AA%D9%88%D8%AB%D9%8A%D9%82) /[تعلّم DXPR Builder](/ar/hc/documentation/learn-dxpr-builder) /[المرجع](/ar/hc/documentation/learn-dxpr-builder/reference) /[الإعداد وAPI](/ar/hc/documentation/learn-dxpr-builder/reference/config-and-api) # نقاط نهاية API.

 تعلّم DXPR Builderالمرجعالإعداد وAPI

   ## في هذا الدليل

 أدلة ذات صلة

- [مرجع الإعدادات](/ar/hc/%D8%A7%D9%84%D8%AA%D9%88%D8%AB%D9%8A%D9%82/%D8%AA%D8%B9%D9%84%D9%85-dxpr-builder/%D8%A7%D9%84%D9%85%D8%B1%D8%AC%D8%B9/%D9%85%D8%B1%D8%AC%D8%B9-%D8%A7%D9%84%D8%A5%D8%B9%D8%AF%D8%A7%D8%AF%D8%A7%D8%AA)
- [مرجع API](/ar/hc/documentation/learn-dxpr-builder/development/api)
- [مرجع واجهة الخطافات](/ar/hc/%D8%A7%D9%84%D8%AA%D9%88%D8%AB%D9%8A%D9%82/%D8%AA%D8%B9%D9%84%D9%85-dxpr-builder/%D8%A7%D9%84%D8%AA%D8%B7%D9%88%D9%8A%D8%B1/api-%D8%A7%D9%84%D8%AE%D8%B7%D8%A7%D9%81%D8%A7%D8%AA)

تسرد هذه الصفحة كل مسار يسجّله DXPR Builder في `dxpr_builder.routing.yml`، مع طرق HTTP ومتطلبات الوصول ومعاملات الطلب وأشكال الاستجابة كما نُفِّذت في المتحكمات. فـ JavaScript المحرر هي العميل المقصود لنقاط نهاية AJAX؛ ولا شيء في هذه الصفحة واجهة API عامة مستقرة، وقد تتغير أسماء المعاملات بين الإصدارات.

## متطلبات الوصول

تستخدم المسارات ثلاثة أنواع من المتطلبات. ويمكن للمسار الجمع بينها.

| المتطلب | المعنى |
|---|---|
| `_permission` | يحتاج المستخدم صلاحية Drupal المسماة. فتعرّف DXPR Builder الصلاحيات `administer dxpr builder configuration` و`edit with dxpr builder` و`administer dxpr_builder_profile` في `dxpr_builder.permissions.yml`؛ وتأتي `view media` و`administer site configuration` من النواة. |
| `_csrf_token` | يجب أن يحمل الطلب رمز CSRF صالحًا في معامل الاستعلام `token`. ولمعالج AJAX الرئيسي، يجلب المحرر عنوان URL بالرمز من `/dxpr_builder/csrf` (أو من العملية `dxpr_builder_csrf`). وللمسارات الأخرى، يضع مُنسِّق الحقل عناوين URL برمز في `drupalSettings.dxprBuilder`، مثل `fileUploadUrl` و`entityLinkSuggestionsUrl` و`userSettingsUrl` و`aiAgent.endpointUrl`. |
| `_dxpr_builder_billable_user` | يجب أن يكون المستخدم مستخدمًا قابلًا للفوترة، كما هو معرّف تحته. |

### ماذا يعني «المستخدم القابل للفوترة»

`DxprBuilderBillableUserAccessCheck` يسمح بالوصول عندما تعيد `DxprBuilderLicenseService::isBillableUser()` القيمة true للحساب الحالي. وتعيد تلك الطريقة false للحسابات المحظورة والحسابات التي ضُبِط حقل `dxpr_user_is_disavowed`الخاص بها (يستبعد المسؤول مستخدمًا من التحرير على صفحة تراخيص المستخدم). وإلا تعيد true للمستخدم 1 ولأي حساب يحمل صلاحية `edit with dxpr builder`. وباختصار: المستخدم القابل للفوترة حساب نشط غير مستبعد مسموح له بالتحرير مع DXPR Builder، وتحسب خدمة الترخيص هذه الحسابات مقابل مفتاح منتجكم.

### طرق HTTP

حيث يعلن مسار `methods`، لا تُوجَّه إلا تلك الطرق. وحيث لا يعلن، يقبل المسار أي طريقة (فـ `MethodFilter` الخاصة بـ Drupal لا ترشّح إلا المسارات المعلنة للطرق). وتذكر الجداول تحته الطريقة التي يستخدمها JavaScript المحرر فعلًا عندما تظهر في المصدر.

## نقاط نهاية AJAX للمحرر

### عنوان URL لرمز CSRF

|  |  |
|---|---|
| المسار | `/dxpr_builder/csrf` |
| اسم المسار | `dxpr_builder.csrf_refresh` |
| الطرق | غير معلَن (أي طريقة). ويرسل المحرر GET (`backend-connect.js`، `fetchCsrfTokenUrl()`). |
| المتطلبات | مستخدم قابل للفوترة |
| المتحكم | `AjaxController::ajaxRefresh()` |

يجب أن يحمل الطلب الترويسة `X-Requested-With: XMLHttpRequest`؛ ودونها يعيد المتحكم HTTP 403 مع متن JSON `{"error": "Invalid request"}`.

| المعامل | المصدر | مطلوب | ملاحظات |
|---|---|---|---|
| `enterprise` | سلسلة الاستعلام | اختياري | عندما يُضبَط إلى `true` وتكون الوحدة `dxpr_builder_e` مثبّتة، يُولَّد الرمز للمسار `dxpr_builder_e.ajax_callback` بدلًا من ذلك. وعندما يُضبَط إلى `true` دون تلك الوحدة يرمي المتحكم استثناءً. |

الاستجابة: سلسلة JSON بعنوان URL لمعالج AJAX الرئيسي ومعامل استعلام `token`. والعنوان مسار من جذر الموقع (المسار الأساسي مشمول، بلا مضيف). فيرسل JavaScript كل عملية منشئ إلى هذا العنوان.

### معالج AJAX الرئيسي

|  |  |
|---|---|
| المسار | `/dxpr_builder/ajax` |
| اسم المسار | `dxpr_builder.ajax_callback` |
| الطرق | غير معلَن (أي طريقة). ويقرأ المتحكم كل معامل من متن POST، ويرسل المحرر POST. |
| المتطلبات | مستخدم قابل للفوترة، رمز CSRF |
| المتحكم | `AjaxController::ajaxCallback()` |

يختار حقل متن POST `action` العملية. وتُسرَد كل عملية ومعاملاتها تحت [عمليات معالج AJAX الرئيسي](#main-ajax-handler-operations). وعندما يغيب `action` أو يكون مجهولًا، يعيد المتحكم `AjaxResponse` فارغة من Drupal بلا أوامر. ومعظم العمليات التي تعيد فحص حالة المستخدم القابل للفوترة تعيد الاستجابة الفارغة نفسها عند فشل ذلك الفحص؛ ويذكر الجدول الاستثناءين.

### محادثة الذكاء الاصطناعي

|  |  |
|---|---|
| المسار | `/dxpr_builder/ajax/ai/chat` |
| اسم المسار | `dxpr_builder.ai_chat` |
| الطرق | POST |
| المتطلبات | `edit with dxpr builder`، مستخدم قابل للفوترة، رمز CSRF |
| المتحكم | `AiChatController::chat()` |

متن الطلب JSON. فيوكّل المتحكم الطلب إلى موفر `dxpr` في وحدة `ai` الخاصة بـ Drupal، فلا يصل أي مفتاح API إلى المتصفح. وقبل الاتصال يدمج النطاقات من إعداد `ai_output_allowed_domains` في مرشح أسماء المضيفين الخاص بوحدة `ai`، عندما توجد تلك الخدمة. وتضبط القيمة `*`المرشح على الثقة الكاملة بدلًا من ذلك. ويُستعاد المرشح بعدها.

| المعامل | المصدر | مطلوب | ملاحظات |
|---|---|---|---|
| `messages` | متن JSON | مطلوب | مصفوفة كائنات بقيم `role` و`content`. |
| `stream` | متن JSON | اختياري | قيمة boolean، والافتراضي `true`. |
| `model` | متن JSON | اختياري | الافتراضي `kavya-m1`. |
| `prediction` | متن JSON | اختياري | تُمرَّر إلى إعدادات الموفر كمصفوفة. |
| `providers` | متن JSON | اختياري | تُمرَّر إلى إعدادات الموفر. |
| `allowed_html_tags` | متن JSON | اختياري | تُمرَّر إلى إعدادات الموفر. |
| `allowed_html_classes` | متن JSON | اختياري | تُمرَّر إلى إعدادات الموفر. |
| `web_search` | متن JSON | اختياري | تُمرَّر القيمة `false` فقط؛ وتُتجاهَل أي قيمة أخرى. |
| `response_format` | متن JSON | اختياري | تُمرَّر إلى إعدادات الموفر كمصفوفة. |

الاستجابات:

| الحالة | رمز الحالة | المتن |
|---|---|---|
| بث (`stream` بقيمة true والموفر يبث) | 200، `Content-Type: text/event-stream` | أحداث مرسلة من الخادم. كل حدث هو `data: <JSON>` حيث يحمل JSON القيم `choices[0].delta.content`، وعندما يقدمها الموفر `id` و`object` و`created` و`model` و`original_model` و`usage`. وينتهي البث مع `data: [DONE]`. |
| بلا بث | 200، `application/json` | `{"choices": [{"message": {"role": "assistant", "content": "<text>"}}]}` |
| المتن ليس JSON، أو `messages` غائبة أو فارغة | 400، نص عادي | `Invalid request: messages required` |
| `model` ليست في قائمة `allowed_models` في `ai_provider_dxpr.settings` (لا تُفحَص إلا عندما تكون الوحدة `ai_provider_dxpr` مثبّتة وتكون القائمة مضبوطة) | 403، `application/json` | `{"error": {"code": "model_not_allowed", "message": "The selected model is not allowed. Please refresh the page to update your model options."}}` |
| استثناء الموفر | 500، `application/json` | `{"error": {"message": "The request could not be completed."}}` |

### توليد صور الذكاء الاصطناعي

|  |  |
|---|---|
| المسار | `/dxpr_builder/ajax/ai/image` |
| اسم المسار | `dxpr_builder.ai_image` |
| الطرق | POST |
| المتطلبات | `edit with dxpr builder`، مستخدم قابل للفوترة، رمز CSRF |
| المتحكم | `AiImageController::generate()` |

| المعامل | المصدر | مطلوب | ملاحظات |
|---|---|---|---|
| `prompt` | متن JSON | مطلوب | الأمر النصي. |
| `model` | متن JSON | اختياري | الافتراضي `kavya-image`. |
| `size` | متن JSON | اختياري | تُمرَّر إلى إعدادات الموفر عندما تكون غير فارغة. |
| `quality` | متن JSON | اختياري | تُمرَّر إلى إعدادات الموفر عندما تكون غير فارغة. |
| `background` | متن JSON | اختياري | تُمرَّر إلى إعدادات الموفر عندما تكون غير فارغة. |

الاستجابات:

| الحالة | رمز الحالة | المتن |
|---|---|---|
| نجاح | 200 | `{"data": [{"b64_json": "<base64 image>"}]}` (لا تُرجَع إلا أول صورة مولّدة) |
| المتن ليس JSON، أو `prompt` غائب | 400 | `{"error": {"message": "Invalid request: prompt required"}}` |
| الموفر لم يعِد أي صورة | 500 | `{"error": {"message": "No image was generated"}}` |
| استثناء الموفر | 500 | `{"error": {"message": "Image generation failed. Please try again."}}` |

### تحرير صور الذكاء الاصطناعي

|  |  |
|---|---|
| المسار | `/dxpr_builder/ajax/ai/image/edit` |
| اسم المسار | `dxpr_builder.ai_image_edit` |
| الطرق | POST |
| المتطلبات | `edit with dxpr builder`، مستخدم قابل للفوترة، رمز CSRF |
| المتحكم | `AiImageController::edit()` |

| المعامل | المصدر | مطلوب | ملاحظات |
|---|---|---|---|
| `prompt` | متن JSON | مطلوب | تعليمات التحرير. |
| `image` | متن JSON | مطلوب | صورة المصدر مشفرة Base64 (فك صارم). |
| `mimeType` | متن JSON | اختياري | الافتراضي `image/png`؛ ويصبح النوع الفرعي امتداد الملف الممرر إلى الموفر. |
| `model` | متن JSON | اختياري | الافتراضي `kavya-image`. |
| `size`، `quality`، `background` | متن JSON | اختياري | تُمرَّر إلى إعدادات الموفر عندما تكون غير فارغة. |

الاستجابات:

| الحالة | رمز الحالة | المتن |
|---|---|---|
| نجاح | 200 | `{"data": [{"b64_json": "<base64 image>"}]}` |
| المتن ليس JSON، أو `prompt` أو `image` غائب | 400 | `{"error": {"message": "Invalid request: prompt and image required"}}` |
| `image` ليست base64 صالحة | 400 | `{"error": {"message": "Invalid image data: base64 decode failed"}}` |
| الموفر لم يعِد أي صورة | 500 | `{"error": {"message": "No image was generated"}}` |
| استثناء الموفر | 500 | `{"error": {"message": "Image editing failed. Please try again."}}` |

### رفع الملفات

|  |  |
|---|---|
| المسار | `/dxpr_builder/ajax/file_upload` |
| اسم المسار | `dxpr_builder.ajax_file_upload_callback` |
| الطرق | POST وDELETE (معلَنة في التوجيه؛ وللمتحكم معالج رفع واحد ولا فرع حذف منفصل) |
| المتطلبات | مستخدم قابل للفوترة، رمز CSRF |
| المتحكم | `UploadFileController::fileUpload()` |

| المعامل | المصدر | مطلوب | ملاحظات |
|---|---|---|---|
| `upload` | ملفات نموذج متعددة الأجزاء، تُرسَل كـ `upload[]` | مطلوب | ملف مرفوع واحد أو أكثر. |

يفرز المتحكم كل ملف حسب الجزء الأول من نوع MIME الخاص بالعميل إلى `<default scheme>://dxpr_builder_images` أو `dxpr_builder_videos` أو `dxpr_builder_files`. وتحتاج الصورة امتدادًا من أنواع MIME: `image/gif` أو `jpg` أو `jpeg` أو `png` أو `webp` أو `avif` أو `svg`. ويحتاج الفيديو واحدًا من `video/webm` أو `ogv` أو `ogg` أو `mp4` أو `quicktime` (مثل `.mov`). وحد الحجم هو أقصى رفع في PHP. والملف بالاسم نفسه ومحتوى SHA-256 المطابق لملف مُدار موجود يستطيع المستخدم عرضه يُعاد استخدامه بدل حفظه مجددًا. وعندما تكون الوحدة `media` مثبّتة ويوجد نوع وسائط مسمى `image` أو `media_image` أو `video` أو `media_video`، يُنشَأ كيان وسائط منشور (أو يُعاد استخدامه) للملف. ويُسجَّل استخدام الملف تحت الوحدة `dxpr_builder`.

الاستجابات:

| الحالة | رمز الحالة | المتن |
|---|---|---|
| نجاح | 201 | مصفوفة JSON، كائن لكل ملف: `url` (عنوان URL المطلق للملف) و`uuid` و`id` (لكيان الوسائط عند وجوده، وإلا للملف) و`fid` (معرف الملف) و`entity_type` (بقيمة `media` أو `file`). |
| بلا ملفات `upload` مرفوعة | 400 | `{"message": "No files were uploaded."}` |
| رفع غير صالح أو وجهة غير قابلة للكتابة أو فشل الحفظ | 500 | `{"message": "<reason>"}` |
| فشل التحقق (الامتداد أو الحجم) | 422 | `{"message": "<violation messages>"}` |
| اسم الملف مقفل أصلًا بطلب آخر | 503 | `{"message": "File \"<name>\" is already locked for writing."}` |

### مربع حوار مكتبة الوسائط

|  |  |
|---|---|
| المسار | `/dxpr_builder/media-library` |
| اسم المسار | `dxpr_builder.media_library` |
| الطرق | غير معلَن (أي طريقة). وتُقرَأ المعاملات من سلسلة الاستعلام. |
| المتطلبات | `view media`؛ مسار إدارة |
| المتحكم | `AjaxController::openImageMediaLibrary()` |

| المعامل | المصدر | مطلوب | ملاحظات |
|---|---|---|---|
| `media_type` | سلسلة الاستعلام | اختياري | `image` (الافتراضي) أو `video`. |
| `remaining_slots` | سلسلة الاستعلام | اختياري | عدد العناصر التي يقبلها الفاتح؛ والافتراضي 1. |
| `uuid` | سلسلة الاستعلام | اختياري | تُمرَّر إلى الفاتح كـ `opener_parameters.uuid`. |

يعتمد نوع الوسائط المعروض على إعداد `media_browser`: يستخدم `media_library` نوع الوسائط `image` أو `video` مباشرة؛ ويستخدم `media_library_acquia_dam` النوع `acquia_dam_image_asset` أو `acquia_dam_video_asset` عندما يوجد نوع الوسائط ذلك.

الاستجابات:

| الحالة | النتيجة |
|---|---|
| نجاح | مصفوفة عرض مبنية مع `MediaLibraryUiBuilder::buildUi()` بالفاتح `media_library.opener.dxpr_builder`. فيعرضها Drupal كصفحة HTML مقصودة لإطار مضمّن. |
| `media_library`: الوحدة غير مثبّتة | 403، نص عادي `Media Library is not enabled. Please enable it to access this feature.` |
| قيمة غير مدعومة: `media_type` | 400، نص عادي `Unsupported media type "<value>".` |
| `media_browser`: إعداد بلا نوع وسائط صالح | 400، نص عادي `The "<setting>" settings is not supported.` |

### مدقق روابط المساعدة

|  |  |
|---|---|
| المسار | `/dxpr_builder/ajax/help_link_validator` |
| اسم المسار | `dxpr_builder.ajax_help_link_validator` |
| الطرق | غير معلَن (أي طريقة). ويرسل سكربت التطوير `dxpr_builder_dev.js` طلب POST بمتن مشفر كنموذج. |
| المتطلبات | مستخدم قابل للفوترة |
| المتحكم | `AjaxController::validateHelpLink()` |

| المعامل | المصدر | مطلوب | ملاحظات |
|---|---|---|---|
| `help_link` | متن POST | مطلوب لإجابة مفيدة | لا تُفحَص إلا روابط `http` أو `https` على المضيف `dxpr.com` بمسار يبدأ `/documentation/`. |

الاستجابة: مصفوفة JSON. القيمة `[true]` عندما يعيد طلب HEAD للرابط (دون اتباع التحويلات) 200؛ و`[false]` عندما يرمي عميل HTTP؛ و`[]` في كل حالة أخرى، بما فيها معامل غائب أو رابط غير مطابق أو حالة غير 200.

### اقتراحات روابط الكيانات

|  |  |
|---|---|
| المسار | `/dxpr_builder/entity-link-suggestions` |
| اسم المسار | `dxpr_builder.entity_link_suggestions` |
| الطرق | GET |
| المتطلبات | `edit with dxpr builder` ورمز CSRF؛ وخيار `no_cache` من خيارات المسار |
| المتحكم | `EntityLinkSuggestionsController::suggestions()` |

| المعامل | المصدر | مطلوب | ملاحظات |
|---|---|---|---|
| `q` | سلسلة الاستعلام | مطلوب للنتائج | نص البحث، بأحرف صغيرة. فقيمة مثل `/node/123` تحمّل ذلك الكيان مباشرة. |
| `langcode` | سلسلة الاستعلام | اختياري | لغة الكيان المضيف؛ والافتراضي اللغة الحالية. ولا تُرجَع إلا الكيانات المتاحة بهذه اللغة. |

الحزم هي ذات `ckeditor5_link_suggestions` المفعّلة في معلومات حزمها؛ وعندما لا تُضبَط أي منها، تُبحَث كل حزم العقد. ويُطابَق حتى 100 كيان لكل نوع كيان مع بحث `CONTAINS` عبر ملحقات اختيار مرجع الكيان في النواة.

الاستجابة: `{"suggestions": [...]}` بقابلية تخزين خاصة وعمر أقصى 300 ثانية. ويحمل كل اقتراح `description` و `entity_type_id` و`entity_uuid` و`group` و`label` و`path`. وعندما لا يطابق `q` شيئًا، تحمل المصفوفة اقتراح رابط يدوي واحدًا مع `description` و`label` (المدخل بأحرف صغيرة) و `path` (المدخل عندما يكون URL صالحًا، وإلا سلسلة فارغة). وعندما يكون `q` فارغًا، تكون `suggestions`مصفوفة فارغة.

### إعدادات محرر المستخدم

|  |  |
|---|---|
| المسار | `/dxpr_builder/user-settings` |
| اسم المسار | `dxpr_builder.user_settings` |
| الطرق | POST |
| المتطلبات | `edit with dxpr builder` ورمز CSRF؛ وخيار `no_cache` من خيارات المسار |
| المتحكم | `UserSettingsController::save()` |

يرسل المحرر هذا الطلب عندما يغيّر مستخدم إعدادات محرره الخاصة، مثلًا تحت **إعدادات المحرر**. وتُخزَّن القيم مع حساب المستخدم في `user.data`، الوحدة `dxpr_builder`.

| المعامل | المصدر | مطلوب | ملاحظات |
|---|---|---|---|
| `controls_layout` | متن JSON | مطلوب (الإعداد الوحيد) | `element` أو `breadcrumb` أو `default`. وتزيل `default` اختيار المستخدم، فينطبق إعداد الملف أو الموقع. |

الاستجابات:

| الحالة | رمز الحالة | المتن |
|---|---|---|
| حُفِظ | 200 | `{"settings": {"controls_layout": "<value>"}}`: كل إعداد بعد الحفظ، وقيمة `default` حيث لا اختيار مخزّن للمستخدم. |
| المتن ليس كائن JSON غير فارغ، أو اسم أو قيمة غير صالحين | 400 | `{"error": "Invalid setting or value."}`. ولا يُخزَّن شيء. |

## عمليات معالج AJAX الرئيسي

تذهب كل العمليات إلى `/dxpr_builder/ajax` مع معامل استعلام الرمز المأخوذ من `/dxpr_builder/csrf`. ويُرسَل اسم العملية في حقل متن POST `action`؛ وكل الحقول الأخرى معاملات متن POST ما لم يُذكَر غير ذلك. ويشير عمود «إعادة فحص الفوترة» إلى العمليات التي تستدعي `isBillableUser()` مجددًا داخل المبدّل. وعند فشل ذلك الفحص تعيد `AjaxResponse` الفارغة الموضحة أعلاه، ما لم يقل الصف غير ذلك.

### الجلسة والوصول

| العملية | المعاملات | إعادة فحص الفوترة | يُرجِع |
|---|---|---|---|
| `dxpr_login` | بلا | لا | قيمة JSON منطقية: هل المستخدم الحالي قابل للفوترة. |
| `dxpr_builder_csrf` | بلا | نعم | سلسلة JSON: عنوان URL للمعالج مع معامل استعلام `token` (كالعنوان من `/dxpr_builder/csrf` دون خيار `enterprise`). |

### الحاويات (الحقول المعروضة بمُنسِّق DXPR Builder)

| العملية | المعاملات | إعادة فحص الفوترة | يُرجِع |
|---|---|---|---|
| `dxpr_get_container_types` | بلا | نعم | كائن JSON مفتاحه `entity_type\|bundle` وقيمته `entity_type - bundle`، مدخل لكل حزمة يستخدم عرضها الافتراضي المُنسِّق `dxpr_builder_text` على حقل واحد على الأقل. |
| `dxpr_get_container_names` | `container_type` (مطلوب، `entity_type\|bundle`) | نعم (يعيد سلسلة JSON فارغة بدل الاستجابة الفارغة) | كائن JSON مفتاحه `entity_id\|field_name` (أو `entity_id\|field_name\|langcode` للكيانات القابلة للترجمة) وقيمته `entity label\|field label`. وعندما يغيب `container_type`، أو يفشل فحص الفوترة، تكون الاستجابة سلسلة JSON فارغة. |
| `dxpr_save_container` | `type` (مطلوب، `entity_type\|bundle`)؛ و`name` (مطلوب، `entity_id\|field_name` أو `entity_id\|revision_id\|field_name`)؛ و`htmlContent` (مطلوب، وسوم مشفرة)؛ و`lang` (اختياري، والافتراضي لغة الموقع الافتراضية) | نعم | سلسلة JSON فارغة عند النجاح. وHTTP 400 مع رسالة JSON عندما لا يكون `htmlContent` سلسلة أو لا تنطبق اللغة على كيان غير قابل للترجمة؛ و404 عندما لا توجد الترجمة المطلوبة؛ و500 عندما لا يمكن تحميل الكيان. |

`dxpr_save_container` يفعل التالي:

1. يفك تشفير `htmlContent`: XOR لكل بايت مع 7، ثم فك ترميز URL.
2. يكتب النتيجة إلى الدلتا الأولى للحقل المسمى.
3. ينشئ مراجعة افتراضية جديدة مع رسالة السجل `Saved with DXPR builder` عندما يكون نوع الكيان قابلًا للمراجعة.
4. يزيل أي قفل محتوى للكيان.
5. يحدّث `block_revision_id` في أقسام Layout Builder التي تشير إلى الكتلة المضمّنة المحفوظة.
6. يزيد قيمة الحالة `dxpr_builder.saves_count`.

لا يحدث الحفظ إلا عندما يملك المستخدم صلاحية `update` على الكيان. ودونها، ما زالت العملية تعيد استجابة النجاح بسلسلة فارغة.

### عناصر CMS (الكتل وطرق العرض)

| العملية | المعاملات | إعادة فحص الفوترة | يُرجِع |
|---|---|---|---|
| `dxpr_builder_get_cms_element_names` | بلا | نعم | كائن JSON من `DxprBuilderService::getCmsElementNames()` بمفاتيح `list` و`disallowed` و`blockCategories`. |
| `dxpr_get_cms_element_settings` | `name` (مطلوب): `view-<view_id>-<display_id>` أو `block-<plugin_id>`؛ و`ajax_page_state[libraries]` (اختياري، مكتبات مفصولة بفواصل محمّلة أصلًا) | نعم | كائن JSON مع `css` و`js` و`settings` و`data`. فللعرض، `data` هي ودجات المرشحات المكشوفة المعروضة؛ وللكتلة، `data` هي نموذج إعدادات الكتلة ملفوفًا بوسوم `<form>`، مع إزالة عناصر `provider` و`admin_label` و`label` و`label_display` و`context_mapping` وفتح كل عناصر details. |
| `dxpr_builder_load_cms_element` | `name` (مطلوب، يحلله `parseStringForCmsElementInfo()`)؛ و`settings` (مطلوب)؛ و`data` (مطلوب، مصفوفة)؛ و`ajax_page_state[libraries]` (اختياري) | لا | كائن JSON مع `css` و`js` و`settings` و`data`، حيث `data` هي الكتلة أو معروض العرض المعروض. |

في العمليتين المعيدتين لـ `settings`، `css` و`js`وسوم أصول معروضة ليست في الصفحة أصلًا، و`settings`كائن `drupalSettings` المفكوك، أو سلسلة فارغة عند غيابه.

### قوالب الصفحات

| العملية | المعاملات | إعادة فحص الفوترة | يُرجِع |
|---|---|---|---|
| `dxpr_get_page_templates` | بلا | نعم | مصفوفة JSON من قوالب الصفحات المفعّلة، لكل منها `title` و`uuid` و`module` (دائمًا `null`: فالكيان لا يخزّنها) و`category` و`date` و`weight` (عدد صحيح) و`image` (عنوان `data:`، أو عنوان `not-found.png` الخاص بالوحدة). |
| `dxpr_load_page_template` | `uuid` (مطلوب) | نعم | استجابة HTML تحمل وسوم القالب مع استبدال الرموز الأساسية؛ وفارغة عندما لا يطابق أي قالب مفعّل. |

### قوالب المستخدم

| العملية | المعاملات | إعادة فحص الفوترة | يُرجِع |
|---|---|---|---|
| `dxpr_get_templates` | بلا | نعم | مصفوفة JSON من القوالب التي يملكها المستخدم الحالي أو المميزة عامة؛ وتُستبعَد القوالب التي لم يعد حساب مؤلفها موجودًا. ويحمل كل مدخل `id` و`uuid` و`name` و`global` و`current_user_is_author` و`author_id` و`author_name` و`type`، وعند تخزينها `image` (عنوان `data:`). |
| `dxpr_load_template` | `uuid` (مطلوب) | نعم | استجابة HTML تحمل وسوم القالب مع استبدال الرموز الأساسية؛ وفارغة عندما لا يطابق أي قالب مفعّل. |
| `dxpr_save_template` | `name` (مطلوب)؛ و`template` (مطلوب، وسوم)؛ و`type` (اختياري، والافتراضي `custom`)؛ و`global` (اختياري، يُحوَّل إلى boolean)؛ و`image` (اختياري: سلسلة base64 أو عنوان `data:image` في متن POST، أو حقل ملف متعدد الأجزاء مسمى `image`) | نعم | كائن JSON مع `message` و`code`. والرمز `code` بقيمة 200 عند النجاح؛ و`code` بقيمة 409 (وحالة HTTP 200) عندما يوجد قالب بالاسم الآلي نفسه؛ و`code` بقيمة 400 مع HTTP 400 عندما لا تكون الصورة بيانات صورة صالحة. |
| `dxpr_delete_template` | `name` (مطلوب) | نعم | سلسلة JSON فارغة. |

يُشتَق الاسم الآلي من `name` بتصغير أحرفه واستبدال كل سلسلة أحرف خارج `a-z0-9_` بشرطة سفلية. ويعود `type` إلى سمة `data-azb` في الوسوم عندما لا يملك قالب مخزّن نوعًا.

### الصور

| العملية | المعاملات | إعادة فحص الفوترة | يُرجِع |
|---|---|---|---|
| `dxpr_builder_get_image_urls` | `entityIDs` (مطلوب، مصفوفة)؛ و`imageStyle` (مطلوب؛ والقيمة `original` للملف بلا نمط)؛ و`entityType` (مطلوب؛ وتحل `media` عناصر الوسائط، وأي قيمة أخرى تُستخدَم كنوع كيان المعرفات) | نعم | متن نصي: عناوين URL للصور مفصولة بفواصل. وتعطي الملفات عنوان URL نسبيًا للجذر مع معامل استعلام `fid`. وتُحَل عناصر الوسائط من نوع `image` أو `video` إلى ملف مصدرها. وتعطي عناصر `acquia_dam_image_asset` عنوان DAM مع إضافة `mid` و`acquiaDamAsset` و`imageStyle`. وتُتخطَّى عناصر الوسائط الأخرى. وHTTP 204 بلا متن عندما تكون `entityIDs` فارغة، أو عندما لا يمكن حل أي عنصر وسائط. |
| `dxpr_builder_get_image_style_url` | `imageStyle` (مطلوب)؛ و`entityId` (مطلوب)؛ و`entityTypeId` (مطلوب، بقيمة `file` أو `media`) | نعم | متن نصي. للملف: عنوان URL النسبي للجذر عبر نمط الصورة (تتخطى ملفات SVG والقيمة `original` النمط)، مع معامل استعلام `fid`. ولعنصر وسائط `acquia_dam_image_asset`: عنوان DAM. وHTTP 204 بلا متن لأي كيان آخر، أو عندما لا يُعثَر على الكيان. |
| `dxpr_builder_get_image_metadata` | `entityId` (مطلوب)؛ و`entityType` (مطلوب، بقيمة `file` أو `media`) | نعم (يعيد JSON بقيمة 403 بدل الاستجابة الفارغة) | `{"data": {"alt": "...", "title": "..."}}` من حقل مصدر صورة عنصر الوسائط (يعطي أصل Acquia DAM نصه البديل في DAM وعنوانًا فارغًا). وللملف، تأتي القيم من أول عنصر وسائط يشير `field_media_image` الخاص به إليه. و`data` مصفوفة فارغة عندما لا يكون الكيان ملفًا ولا عنصر وسائط، أو عندما لا تشير أي وسائط إلى الملف. الأخطاء: 400 `{"error": "Missing required parameters"}` و404 `{"error": "Entity not found"}` و500 `{"error": "Failed to load entity"}` و403 `{"error": "Access denied"}`. |

### أقفال المحتوى

| العملية | المعاملات | إعادة فحص الفوترة | يُرجِع |
|---|---|---|---|
| `dxpr_content_lock_status` | `entity_id` و`revision_id` و`entity_type` و`langcode` (كلها مطلوبة) | لا | كائن JSON مع `status` (قيمة boolean) و`label` (تسمية الكيان)؛ وعند القفل، أيضًا `entity_lock_author_id` و`entity_lock_author_name`. |
| `dxpr_toggle_content_lock` | `entity_id` و`revision_id` و`entity_type` و`langcode` و`toggle_action` (كلها مطلوبة؛ وتنشئ `lock` القفل، وأي قيمة أخرى تزيله) | لا | كائن JSON مع `label` و`status` (بقيمة `true` بعد القفل و`false` بعد فكه). ومصفوفة JSON فارغة (`[]`) عندما لا يمكن تحميل الكيان أو ينقص المستخدم صلاحية `update`. |

## صفحات الإدارة

تقبل كل هذه المسارات أي طريقة (بلا مفتاح `methods`). والمسارات الحاملة `{...}` تأخذ معرف كيان الإعدادات، أو معرف الترحيل لـ `{migration_id}`.

| المسار | اسم المسار | الصلاحية | الغرض |
|---|---|---|---|
| `/admin/dxpr_studio` | `dxpr_builder.admin.studio` | `administer dxpr builder configuration` | نظرة عامة على DXPR Studio؛ صفحة كتلة قائمة الإدارة في النواة تسرد الصفحات الفرعية. |
| `/admin/dxpr_studio/dxpr_builder` | `dxpr_builder.admin.studio.builder` | `administer dxpr builder configuration` | نظرة عامة على DXPR Builder؛ صفحة كتلة قائمة الإدارة في النواة. |
| `/admin/dxpr_studio/dxpr_builder/settings` | `dxpr_builder.settings` | `administer dxpr builder configuration` | `DxprBuilderSettingsForm`: نموذج إعدادات الوحدة. |
| `/admin/dxpr_studio/dxpr_builder/ai_settings` | `dxpr_builder.ai_settings` | `administer dxpr builder configuration` | `DxprBuilderAiSettingsForm`: نموذج إعدادات الذكاء الاصطناعي. |
| `/admin/dxpr_studio/dxpr_builder/user_templates` | `entity.dxpr_builder_user_template.collection` | `administer site configuration` | قائمة كيانات إعدادات `dxpr_builder_user_template`. |
| `/admin/dxpr_studio/dxpr_builder/user_templates/add` | `entity.dxpr_builder_user_template.add_form` | `administer site configuration` | إضافة قالب مستخدم. |
| `/admin/dxpr_studio/dxpr_builder/user_templates/{dxpr_builder_user_template}` | `entity.dxpr_builder_user_template.edit_form` | `administer site configuration` | تحرير قالب مستخدم. |
| `/admin/dxpr_studio/dxpr_builder/user_templates/{dxpr_builder_user_template}/delete` | `entity.dxpr_builder_user_template.delete_form` | `administer site configuration` | حذف قالب مستخدم (نموذج تأكيد). |
| `/admin/dxpr_studio/dxpr_builder/page_template` | `entity.dxpr_builder_page_template.collection` | `administer site configuration` | قائمة كيانات إعدادات `dxpr_builder_page_template`. |
| `/admin/dxpr_studio/dxpr_builder/page_template/add` | `entity.dxpr_builder_page_template.add_form` | `administer site configuration` | إضافة قالب صفحة. |
| `/admin/dxpr_studio/dxpr_builder/page_template/create` | `dxpr_builder.create_page_template` | `administer dxpr builder configuration` | `PageController::createPageTemplate()`: ينسخ قالب المستخدم المفعّل الذي يحدده معامل الاستعلام `uuid` إلى قالب صفحة جديد بالمعرف نفسه والفئة `DXPR`. فيضبط رسالة حالة أو خطأ ويعيد التوجيه إلى قائمة قوالب المستخدم. |
| `/admin/dxpr_studio/dxpr_builder/page_template/{dxpr_builder_page_template}` | `entity.dxpr_builder_page_template.edit_form` | `administer site configuration` | تحرير قالب صفحة. |
| `/admin/dxpr_studio/dxpr_builder/page_template/{dxpr_builder_page_template}/delete` | `entity.dxpr_builder_page_template.delete_form` | `administer site configuration` | حذف قالب صفحة (نموذج تأكيد). |
| `/admin/dxpr_studio/dxpr_builder/profile` | `entity.dxpr_builder_profile.collection` | `administer dxpr_builder_profile` | قائمة كيانات إعدادات `dxpr_builder_profile`. |
| `/admin/dxpr_studio/dxpr_builder/profile/add` | `entity.dxpr_builder_profile.add_form` | `administer dxpr_builder_profile` | إضافة ملف. |
| `/admin/dxpr_studio/dxpr_builder/profile/{dxpr_builder_profile}` | `entity.dxpr_builder_profile.edit_form` | `administer dxpr_builder_profile` | تحرير ملف. |
| `/admin/dxpr_studio/dxpr_builder/profile/{dxpr_builder_profile}/delete` | `entity.dxpr_builder_profile.delete_form` | `administer dxpr_builder_profile` | حذف ملف (نموذج تأكيد). |
| `/admin/dxpr_studio/dxpr_builder/user_licenses` | `dxpr_builder.user_licenses` | `administer dxpr builder configuration` | `PageController::userLicensesPage()`: جدول غير مخزّن للمستخدمين المرخّصين (الأعمدة User وRoles وSites وAssigned وOperations). وفوقه تعرض الصفحة بطاقة ملخص الترخيص الخاصة بها (`dxpr-license-info`) عندما تتوفر معلومات الترخيص، وبينما ينتظر ترخيص محرَّر أيامه الـ30، إشعار «Next license available on». وعلى هذا المسار لا تعرض كتلة **معلومات الترخيص** شيئًا، فلا يظهر الملخص مرتين أبدًا. |
| `/admin/dxpr_studio/dxpr_builder/user_licenses/sites` | `dxpr_builder.user_licenses.sites` | `administer dxpr builder configuration` | `PageController::userLicensesSitesPage()`: قائمة عناصر بالنطاقات المسجلة للمستخدم المعطى في معامل الطلب `mail`؛ وتُفتَح في مربع حوار من جدول التراخيص. |
| `/admin/dxpr_studio/dxpr_builder/content` | `dxpr_builder.licensed_content` | `administer dxpr builder configuration` | `PageController::licensedContentPage()`: جدول مرقّم (20 في الصفحة) من عناصر المحتوى المحررة مع DXPR Builder، مع ملخص ترخيص عناصر المحتوى. ويعرض معامل الاستعلام `needs_migration=1` فقط العناصر التي تحتاج ترحيل محتوى. وفارغ عندما لا تتوفر معلومات ترخيص. |
| `/admin/dxpr_studio/dxpr_builder/migration-status` | `dxpr_builder.migration_status` | `administer dxpr builder configuration` | `MigrationStatusController::statusPage()`: جدول غير مخزّن لترحيلات المحتوى المسجلة مع عناصرها المعلقة. ويملك كل ترحيل معلق رابط **التشغيل الآن**، ويظهر زر **تشغيل كل الترحيلات المعلقة** عندما يوجد معلق. |
| `/admin/dxpr_studio/dxpr_builder/migration-run/{migration_id}` | `dxpr_builder.migration_run_confirm` | `administer dxpr builder configuration` | `MigrationRunConfirmForm`: يؤكد، ثم يشغّل ترحيلًا واحدًا كدفعة ويعود إلى صفحة الحالة. |
| `/admin/dxpr_studio/dxpr_builder/migration-run-all` | `dxpr_builder.migration_run_all_confirm` | `administer dxpr builder configuration` | `MigrationRunAllConfirmForm`: يؤكد، ثم يشغّل كل ترحيل مسجل كدفعة واحدة ويعود إلى صفحة الحالة. |
| `/dxpr-builder/disavow-user` | `dxpr_builder.disavow_user_confirm` | `administer dxpr builder configuration` | `DisavowUserConfirmForm`: يؤكد استبعاد المستخدم المعطى في معامل الاستعلام `uid` من التحرير مع DXPR Builder. |
| `/dxpr-builder/delete-stale-user` | `dxpr_builder.delete_stale_user_confirm` | `administer dxpr builder configuration` | `DeleteStaleUserConfirmForm`: يؤكد إزالة بيانات الترخيص لعنوان البريد الإلكتروني المعطى في معامل الاستعلام `email`. |

## ما الخطوة التالية؟

- [مرجع الإعدادات](/ar/hc/%D8%A7%D9%84%D8%AA%D9%88%D8%AB%D9%8A%D9%82/%D8%AA%D8%B9%D9%84%D9%85-dxpr-builder/%D8%A7%D9%84%D9%85%D8%B1%D8%AC%D8%B9/%D9%85%D8%B1%D8%AC%D8%B9-%D8%A7%D9%84%D8%A5%D8%B9%D8%AF%D8%A7%D8%AF%D8%A7%D8%AA) للإعدادات التي تتحكم في متصفح الوسائط وسلوك الذكاء الاصطناعي اللذين تستخدمهما نقاط النهاية هذه.
- [PHP API](/ar/hc/documentation/learn-dxpr-builder/development/api) للخدمات التي تستدعيها المتحكمات.
- [Hooks API](/ar/hc/%D8%A7%D9%84%D8%AA%D9%88%D8%AB%D9%8A%D9%82/%D8%AA%D8%B9%D9%84%D9%85-dxpr-builder/%D8%A7%D9%84%D8%AA%D8%B7%D9%88%D9%8A%D8%B1/api-%D8%A7%D9%84%D8%AE%D8%B7%D8%A7%D9%81%D8%A7%D8%AA) للخطافات التي تدع الوحدات الأخرى تغيّر سلوك المنشئ.