واجهة برمجة تطبيقات الإعدادات المسبقة (Presets API)

إن الإعداد المسبق للدفع هو قالب إشعار دفع قابل لإعادة الاستخدام — وهو نفس الكائن الذي تقوم ببنائه في محرر الدفع في لوحة التحكم. تدير واجهة برمجة التطبيقات هذه الإعدادات المسبقة للدفع فقط؛ فإعدادات SMS و WhatsApp و Kakao و LINE و Viber المسبقة لكل منها خدمة إعداد مسبق مخصصة خاصة بها، وهي غير مشمولة هنا.

استخدم code الخاص بالإعداد المسبق لإرساله من خلال Notify (حمولة preset) أو نقطة إرسال دفع في Customer Journey.

عنوان URL الأساسي

https://rpc-api.svc-nue.pushwoosh.com

يتم تقديم جميع نقاط النهاية عبر HTTPS. تستخدم الطلبات والاستجابات application/json ما لم يُذكر خلاف ذلك.

المصادقة

يجب أن يتضمن كل طلب ترويسة Authorization مع رمز API الخادم الخاص بك:

Authorization: Api YOUR_API_TOKEN

الأعراف

تسمية الحقول: تقبل أجسام الطلبات ومعلمات الاستعلام/المسار lowerCamelCase (على سبيل المثال، sendType، localizedProperties، searchByName) — يقوم الخادم بفك ترميز أي من الحالتين. يتم دائمًا ترميز الاستجابات باستخدام أسماء حقول البروتو، في snake_case (localized_properties، platform_properties، per_page، وهكذا). تستخدم أمثلة الاستجابة ومرجع كائن الإعداد المسبق أدناه هذه الحالة.
code: تحمل كل استجابة إعداد مسبق رمزها الخاص، الذي يتم إنشاؤه عند Create. مرر هذا الرمز إلى Get، Update، UpdatePartial، Delete، Clone، وإلى واجهات برمجة تطبيقات المراسلة/الرحلة المذكورة أعلاه.
مفاتيح المنصة: يتم فهرسة خرائط platforms و open_actions بواسطة رمز نوع الجهاز الرقمي (1 لـ iOS، 3 لـ Android، وهكذا). يتم فهرسة platform_properties بواسطة اسم enum المنصة بدلاً من ذلك (IOS، ANDROID، HUAWEI_ANDROID، OSX — وهي المنصات الأربع الوحيدة التي يغطيها).
الحقول غير المعبأة: تتضمن استجابات Get و Create و Clone كل حقل من كائن الإعداد المسبق، حتى عندما تكون فارغة أو قيمتها صفر. تعيد List مجموعة حقول مخفضة — انظر List أدناه. لا تعيد Update و UpdatePartial أي حقول إعداد مسبق على الإطلاق — انظر التنبيه في أقسامهما.

استجابات الخطأ

حالة HTTP	المعنى
`400 Bad Request`	وسيطة غير صالحة — حقل مطلوب مفقود أو مشوه، أو فشل شرط مسبق (على سبيل المثال، الاستنساخ بدون `name`).
`401 Unauthorized`	ترويسة `Authorization` مفقودة أو غير صالحة.
`403 Forbidden`	التطبيق أو الإعداد المسبق لا ينتمي إلى حساب المتصل.
`404 Not Found`	لم يتم العثور على الإعداد المسبق أو التطبيق.
`500 Internal Server Error`	فشل غير متوقع من جانب الخادم.

يعيد Delete على إعداد مسبق لا يزال مستخدمًا من قبل نقطة إرسال دفع في رحلة قيد التشغيل أو متوقفة مؤقتًا أيضًا 400 Bad Request (وهو FailedPrecondition على السلك) — وليس 409. قم بإزالة الإعداد المسبق من الرحلة أولاً.

نقاط النهاية

الطريقة	المسار	الوصف
`POST`	`/api/presets`	إنشاء إعداد دفع مسبق جديد
`GET`	`/api/presets`	سرد الإعدادات المسبقة للدفع لتطبيق ما
`GET`	`/api/presets/{code}`	الحصول على إعداد دفع مسبق واحد
`PUT`	`/api/presets/{code}`	تحديث إعداد دفع مسبق (الكتابة فوق بالكامل)
`PUT`	`/api/presets/{code}:partial`	تحديث إعداد دفع مسبق (جزئي)
`POST`	`/api/presets/{code}:clone`	استنساخ إعداد دفع مسبق
`DELETE`	`/api/presets/{code}`	حذف إعداد دفع مسبق

إنشاء

ينشئ إعداد دفع مسبق جديد في تطبيق ويعيده مع رمزه الذي تم إنشاؤه.

POST /api/presets

جسم الطلب

المعلمة	النوع	مطلوب	الوصف
`application`	string	نعم	رمز التطبيق لإنشاء الإعداد المسبق فيه.
`name`	string	نعم	اسم الإعداد المسبق.
`sendType`	string	لا	قناة الإعداد المسبق (على سبيل المثال `push`).
`isV2`	boolean	لا	يثبت علامة أصل الإعداد المسبق. احذفه ليكون الافتراضي `true` (v2)؛ اضبطه على `false` فقط عند إعادة إنتاج إعداد مسبق قديم v1.

جميع الحقول الأخرى — المحتوى المترجم، والمنصات، والرابط العميق، وصندوق الوارد، والفئات، وما إلى ذلك — مشتركة مع Update وموثقة مرة واحدة في مرجع كائن الإعداد المسبق أدناه.

مثال على الطلب

{
  "application": "XXXXX-XXXXX",
  "name": "20% discount",
  "platforms": { "1": true, "3": true },
  "localizedContent": {
    "default": "Get your 20% discount right now",
    "es": "Consigue tu 20% de descuento ahora mismo"
  },
  "localizedTitle": { "default": "Hi there" },
  "openAction": { "link": { "url": "https://example.com" } },
  "categories": ["promo"]
}

الاستجابة

يعيد { "preset": { ... } }، وهو كائن الإعداد المسبق الذي تم إنشاؤه.

سرد

يسرد الإعدادات المسبقة للدفع لتطبيق ما — مجموعة حقول مخفضة، وليس الكائن الكامل — مع ترقيم الصفحات والترتيب والتصفية حسب الاسم أو الفئة.

GET /api/presets

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

المعلمة	النوع	مطلوب	الوصف
`application`	string	نعم	رمز التطبيق لسرد الإعدادات المسبقة له.
`orderBy`	string	لا	`NAME` (افتراضي)، `CREATED`، أو `UPDATED`.
`orderDirection`	string	لا	`ASC` (افتراضي) أو `DESC`.
`page`	integer	لا	فهرس الصفحة يبدأ من الصفر.
`perPage`	integer	لا	حجم الصفحة. الافتراضي `100` عند حذفه أو `0`.
`searchByName`	string	لا	مطابقة سلسلة فرعية غير حساسة لحالة الأحرف على اسم الإعداد المسبق أو الرمز (`ILIKE %value%`).
`searchByCategory`	array of strings	لا	كرر المعلمة للتصفية حسب أي من الفئات المتعددة، على سبيل المثال `?searchByCategory=promo&searchByCategory=lifecycle`.
`showHidden`	boolean	لا	تضمين الإعدادات المسبقة المميزة بـ `hidden`.

الاستجابة

يحمل كل عنصر فقط: name، code، platforms، localized_content (نص عادي لكل لغة — ليس localized_properties)، localized_title، localized_subtitle، banner، icon، categories، journey_uuid، custom_data، is_v2، created، updated. يتم حذف كل حقل آخر من كائن الإعداد المسبق — localized_properties، platform_properties، deeplink، richmedia، url، وما إلى ذلك — حتى لو تم تعيينه في الإعداد المسبق.

الحقل	النوع	الوصف
`presets`	array of objects	الصفحة الحالية من الإعدادات المسبقة، بالشكل المخفض الموضح أعلاه.
`page`	integer	فهرس الصفحة المعاد.
`per_page`	integer	حجم الصفحة المستخدم لهذه الاستجابة.
`total`	integer	العدد الإجمالي للإعدادات المسبقة المطابقة للمرشحات، عبر جميع الصفحات.

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

{
  "presets": [
    { "name": "20% discount", "code": "AAAAA-BBBBB", "platforms": { "1": true, "3": true }, "categories": ["promo"] }
  ],
  "page": 0,
  "per_page": 100,
  "total": 1
}

الحصول على

يعيد إعداد دفع مسبق واحد برمزه، مع تعبئة كل حقل من كائن الإعداد المسبق.

GET /api/presets/{code}

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

المعلمة	النوع	الوصف
`code`	string	رمز الإعداد المسبق.

الاستجابة

يعيد { "preset": { ... } }، وهو كائن الإعداد المسبق الكامل.

تحديث

يكتب فوق إعداد دفع مسبق موجود برمزه بالحقول المقدمة.

PUT /api/presets/{code}

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

المعلمة	النوع	الوصف
`code`	string	رمز الإعداد المسبق للكتابة فوقه.

جسم الطلب

نفس حقول Create (ناقص application)، بالإضافة إلى بقية حقول كائن الإعداد المسبق. يتم قبول sendType ولكن يتم تجاهله — لا يمكن تغيير قناة الإعداد المسبق بعد الإنشاء.

يقوم Update بإعادة بناء خصائص محتوى الإعداد المسبق من البداية في كل استدعاء: localizedProperties، platformProperties، openAction/openActions، deeplink، deeplinkParams، richmedia، url، campaignCode، filterCode، geoZones، sendRate، cappingCount/cappingDays، حقول notification*Url الثلاثة، remotePage، wnsContent، originalUrl، علامات *Silent الأربعة، inboxImage/inboxIcon/inboxDays/inboxDate، banner، icon، customData، و isV2 — حذف أي من هذه يؤدي إلى مسحها (أو، بالنسبة لـ isV2، إعادة تعيينها إلى true).

name، platforms، categories، localizedTitle، localizedSubtitle، و localizedContent هي الاستثناء: يتم لمس كل منها فقط عند إرسالها، وتترك دون تغيير عند حذفها.

استخدم UpdatePartial إذا كنت تريد أن تظل المجموعة الأولى دون تغيير عند حذفها أيضًا.

الاستجابة

كائن فارغ عند النجاح: {}.

تحديث جزئي

يحدّث فقط الحقول المقدمة من إعداد دفع مسبق موجود برمزه، ويترك الحقول غير المعينة دون تغيير.

PUT /api/presets/{code}:partial

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

المعلمة	النوع	الوصف
`code`	string	رمز الإعداد المسبق لتصحيحه.

جسم الطلب

نفس حقول Update، ناقص application. على عكس Update، كل حقل هنا — بما في ذلك localizedProperties، platformProperties، categories، وبقية مجموعة خصائص المحتوى المدرجة في تنبيه Update — يترك دون تغيير عند حذفه، ويتم لمسه فقط عند إرساله (حقل خريطة/مصفوفة ترسله لا يزال يحل محل القيمة الحالية بالكامل لهذا الحقل، ولكنه لا يؤثر على أي شيء لم تقم بتضمينه). يتم قبول sendType بالمثل ولكن يتم تجاهله.

مثال على الطلب

{
  "sendRate": 500,
  "cappingCount": 3,
  "cappingDays": 7
}

الاستجابة

أيضًا كائن فارغ — انظر التنبيه أعلاه.

استنساخ

ينسخ إعداد دفع مسبق موجود، تحت اسم جديد، في نفس التطبيق.

POST /api/presets/{code}:clone

جسم الطلب

المعلمة	النوع	مطلوب	الوصف
`code`	string	نعم	رمز الإعداد المسبق المصدر للنسخ.
`name`	string	نعم	اسم للإعداد المسبق الجديد.

مثال على الطلب

{ "code": "AAAAA-BBBBB", "name": "20% discount (copy)" }

الاستجابة

يعيد { "preset": { ... } }، وهو كائن الإعداد المسبق الجديد.

حذف

يحذف بشكل دائم إعداد دفع مسبق برمزه.

DELETE /api/presets/{code}

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

المعلمة	النوع	الوصف
`code`	string	رمز الإعداد المسبق للحذف.

الاستجابة

كائن فارغ عند النجاح: {}.

مرجع الكائن

تتطابق أسماء الحقول أدناه مع ما تعيده Get و Create و Update و Clone بالفعل — أسماء حقول البروتو snake_case (انظر الأعراف). يعمل نموذج lowerCamelCase المستخدم في أمثلة الطلب أعلاه بنفس الطريقة عند الإدخال.

كائن الإعداد المسبق

الهوية

الحقل	النوع	الوصف
`code`	string	يتم إنشاؤه عند `Create`. يحدد هذا الإعداد المسبق في كل مكان آخر في واجهة برمجة التطبيقات.
`name`	string	اسم الإعداد المسبق.
`send_type`	string	قناة الإعداد المسبق (على سبيل المثال `push`).
`is_v2`	boolean	`true` للإعدادات المسبقة التي تم إنشاؤها أو ترحيلها إلى نموذج المحتوى v2.
`system`	boolean	يحدد الإعداد المسبق كإعداد مسبق للنظام/داخلي.
`hidden`	boolean	يخفي الإعداد المسبق من نتائج `List` (أرسل `showHidden: true` لتضمينه).
`created`	string (RFC 3339)	الطابع الزمني للإنشاء.
`updated`	string (RFC 3339)	الطابع الزمني لآخر تحديث.

الاستهداف والمحتوى

الحقل	النوع	الوصف
`platforms`	map<string, boolean>	المنصات التي يستهدفها الإعداد المسبق، مفهرسة بواسطة رمز نوع الجهاز (على سبيل المثال `"1"` لـ iOS).
`localized_properties`	map<string, object>	اللغة ← محتوى غني لكل منصة. نفس شكل `LocalizedContent` على حمولة `Notify` — إدخال واحد لكل كتلة منصة (`ios`، `android`، وهكذا). هذه هي الطريقة الأساسية لتعيين محتوى دفع خاص بالمنصة.
`localized_title` / `localized_subtitle` / `localized_content`	map<string, string>	اللغة ← نص عادي. بديل أبسط لـ `localized_properties` للعنوان والعنوان الفرعي والنص الأساسي عندما لا تحتاج إلى تجاوزات لكل منصة.
`platform_properties`	map<string, object>	تجاوزات قديمة لكل منصة، مفهرسة بواسطة اسم enum المنصة (`IOS`، `ANDROID`، `HUAWEI_ANDROID`، `OSX`). انظر كائن PlatformProperties أدناه.
`open_action`	`OpenAction`	الإجراء الذي يتم تشغيله عندما يفتح المستخدم الإشعار، ويتم تطبيقه على كل منصة. حصري بشكل متبادل مع `open_actions` — تحدد الاستجابة واحدًا بالضبط.
`open_actions`	map<string, `OpenAction`>	تجاوز لكل منصة لـ `open_action`، مفهرس بواسطة رمز نوع الجهاز.
`deeplink`	string	رمز الرابط العميق.
`deeplink_params`	map<string, string>	المعلمات التي يتم تمريرها إلى الرابط العميق.
`richmedia`	string	رمز الوسائط الغنية الذي يفتحه الإشعار.
`url`	string	عنوان URL الذي يفتحه الإشعار، إذا لم يتم استخدام رابط عميق أو وسائط غنية.

صندوق الوارد

الحقل	النوع	الوصف
`inbox_image`	string	عنوان URL للصورة المعروضة في إدخال صندوق الوارد للرسائل.
`inbox_icon`	string	عنوان URL للرمز المعروض في إدخال صندوق الوارد للرسائل.
`inbox_days`	integer	عدد الأيام التي يبقى فيها الإدخال في صندوق الوارد للرسائل.
`inbox_date`	string (RFC 3339)	تاريخ انتهاء صلاحية صريح لإدخال صندوق الوارد للرسائل، كبديل لـ `inbox_days`.

التنظيم والبيانات الوصفية

الحقل	النوع	الوصف
`categories`	array of strings	أسماء الفئات التي تم وسم الإعداد المسبق بها.
`campaign_code`	string	رمز الحملة الذي ينسب إليه هذا الإعداد المسبق.
`filter_code`	string	رمز الشريحة / المرشح الذي يستهدفه هذا الإعداد المسبق افتراضيًا.
`geo_zones`	string	استهداف المناطق الجغرافية، إذا كان الإعداد المسبق يتم تشغيله جغرافيًا.
`journey_uuid`	string	UUID لرحلة العميل التي تمتلك هذا الإعداد المسبق، إذا تم إنشاؤه من نقطة إرسال دفع في رحلة.
`custom_data`	object	JSON حر الشكل يتم إرساله إلى SDK العميل كمعلمة `u`.
`banner`	string	عنوان URL لصورة كبيرة / مرفق.
`icon`	string	عنوان URL لرمز إشعار مخصص.

حدود التسليم

الحقل	النوع	الوصف
`send_rate`	integer	تقييد الإرسال باستخدام هذا الإعداد المسبق، بالرسائل/ثانية — المعادل على مستوى الإعداد المسبق لـ `SendRate` في `Notify`.
`capping_count` / `capping_days`	integer	حد التكرار لكل مستخدم لهذا الإعداد المسبق — المعادل على مستوى الإعداد المسبق لـ `count` / `days` في `FrequencyCapping` في `Notify`.

خطافات الويب

الحقل	النوع	الوصف
`notification_sent_url`	string	عنوان URL للاستدعاء المطلوب عند إرسال إشعار يستخدم هذا الإعداد المسبق.
`notification_delivered_url`	string	عنوان URL للاستدعاء المطلوب عند تسليم إشعار يستخدم هذا الإعداد المسبق.
`notification_click_url`	string	عنوان URL للاستدعاء المطلوب عند النقر على إشعار يستخدم هذا الإعداد المسبق.

الحقول القديمة

هذه الحقول موروثة من نموذج الإعداد المسبق v1. يتم تعبئتها للتوافق مع لوحة التحكم بدلاً من التكاملات الجديدة.

الحقل	النوع	الوصف
`remote_page`	string	مرجع صفحة بعيدة قديم.
`wns_content`	string	JSON قالب إشعار Windows القديم، كما هو مقبول من قبل طرق `createPreset`/`getPreset` v1.
`original_url`	string	قيمة `url` قبل التقصير، عندما تم استبدال `url` برابط مختصر.
`ios_silent` / `android_silent` / `huawei_android_silent`	boolean	علامات دفع صامتة (بيانات فقط) لكل منصة.

كائن PlatformProperties

الحقول المتاحة في كل إدخال platform_properties (IOS، ANDROID، HUAWEI_ANDROID، OSX):

الحقل	النوع	الوصف
`badge`	string	تجاوز عدد الشارة.
`sound`	string	اسم ملف الصوت.
`sound_off`	boolean	كتم صوت الإشعار.
`priority`	string	أولوية في درج الإشعارات (Android/Huawei فقط).
`delivery_priority`	string	أولوية التسليم `NORMAL` أو `HIGH` (Android/Huawei فقط).
`ios_interruption_level`	string	`passive`، `active`، `time-sensitive`، أو `critical` (iOS فقط).

واجهة برمجة تطبيقات الإعدادات المسبقة (Presets API)

عنوان URL الأساسي

المصادقة

الأعراف

استجابات الخطأ

نقاط النهاية

إنشاء

جسم الطلب

مثال على الطلب

الاستجابة

سرد

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

الاستجابة

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

الحصول على

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

الاستجابة

تحديث

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

جسم الطلب

الاستجابة

تحديث جزئي

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

جسم الطلب

مثال على الطلب

الاستجابة

استنساخ

جسم الطلب

مثال على الطلب

الاستجابة

حذف

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

الاستجابة

مرجع الكائن

كائن الإعداد المسبق

الهوية

الاستهداف والمحتوى

صندوق الوارد

التنظيم والبيانات الوصفية

حدود التسليم

خطافات الويب

الحقول القديمة

كائن PlatformProperties

ذات صلة