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

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

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

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

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

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

المصادقة

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

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 بواسطة اسم التعداد للمنصة بدلاً من ذلك (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 (a FailedPrecondition على السلك) — وليس 409. قم بإزالة الإعداد المسبق من الرحلة أولاً.

تعيد Create، Update، و UpdatePartial أيضًا 400 Bad Request لرمز تخصيص غير قابل للحل — انظر أدناه.

رموز التخصيص

تقوم Create، Update، و UpdatePartial بالتحقق من صحة كل رمز تخصيص ({name|modifier|default}) في localizedTitle، localizedSubtitle، و localizedContent (لكل لغة في الطلب)، وفي حقول المحتوى الغني لكل منصة التي يقوم المرسل بالتعويض فيها (العنوان، المحتوى، الشعار، الأيقونة، عنوان URL، معلمات الرابط العميق، وما إلى ذلك، لكل منصة). الحقول خارج تلك المجموعة، مثل richmedia، campaignCode، deeplink، أو filterCode، تحتفظ بالرمز تمامًا كما هو مكتوب — لا يقوم Pushwoosh بتحليل بناء جملة التخصيص هناك.

يحتاج الرمز إلى مُعدِّل يتعرف عليه Pushwoosh، لأن الرمز غير المُعدَّل أو الذي به خطأ إملائي لا يمكن تنسيقه وسيصل إلى المستخدمين كأقواس حرفية. الرمز الذي به مُعدِّل مفقود أو غير معروف ({Tag|}، {Tag|typo}) يفشل في الاستدعاء مع InvalidArgument:

{
  "code": 3,
  "message": "personalization token {Tag|} has no known modifier, so it would be delivered as text; expected one of [capitalizefirst capitalizeallfirst uppercase lowercase regular base64 cent dollar comma euro jpy lira M-d-y m-d-y M d y M d Y l M d H:i m-d-y H:i]"
}

تنبيه

في UpdatePartial، يتم تشغيل هذا التحقق مقابل المجموعة الكاملة المحفوظة للإعداد المسبق من حقول المحتوى المستبدلة، وليس فقط الحقول الموجودة في الطلب الحالي — فالإعداد المسبق الذي يحتوي بالفعل على رمز معطوب في حقل لم يتم لمسه يفشل في كل استدعاء UpdatePartial لاحق حتى يتم إصلاح هذا الرمز. localizedTitle، localizedSubtitle، و localizedContent هي الاستثناء: يتم التحقق منها فقط عندما يتضمنها نفس الاستدعاء.

المُعدِّلات المقبولة

يقدم منتقي التخصيص في لوحة التحكم بالفعل كل مُعدِّل أدناه لعلامات INTEGER/PRICE (بما في ذلك تنسيقات التاريخ) وعلامات السلسلة النصية، باستثناء base64 — هذا المُعدِّل يمكن الوصول إليه فقط من خلال واجهة برمجة التطبيقات. gitlab.corp.pushwoosh.com/channels/sdk/pkg/dynamiccontent هو مصدر الحقيقة الذي يتحقق منه كل من لوحة التحكم وواجهة برمجة التطبيقات هذه.

المُعدِّل	نوع العلامة	ملاحظات
capitalizefirst	string	غير حساس لحالة الأحرف
capitalizeallfirst	string	غير حساس لحالة الأحرف
uppercase	string	غير حساس لحالة الأحرف
lowercase	string	غير حساس لحالة الأحرف
regular	string or integer	غير حساس لحالة الأحرف، لا يتم تطبيق أي تنسيق
base64	string	غير حساس لحالة الأحرف، API فقط — غير معروض في منتقي CP
cent / dollar / comma / euro / jpy / lira	integer	غير حساس لحالة الأحرف
M-d-y, m-d-y, M d y, M d Y, l, M d, H:i, m-d-y H:i	integer	مُعدِّلات تنسيق التاريخ، تتم مطابقتها تمامًا كما هي مكتوبة، بما في ذلك حالة الأحرف

نقاط النهاية

الطريقة	المسار	الوصف
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.

ملاحظة

isDefault هو مرشح مهمل يتم الاحتفاظ به فقط لنموذج إرسال الدفع القديم في لوحة التحكم — لا تعتمد عليه.

الاستجابة

يحمل كل عنصر فقط: 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	رمز الإعداد المسبق للكتابة فوقه.

جسم الطلب

نفس حقول الإنشاء (ناقص 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 إذا كنت تريد أن تترك المجموعة الأولى دون تغيير عند حذفها أيضًا.

الاستجابة لا تحتوي على حقل إعداد مسبق

يعيد Update {} — كائن فارغ. تحدد رسالة الاستجابة تقنيًا حقل preset، لكن الخادم لا يملأه أبدًا. استدعِ Get بعد ذلك إذا كنت بحاجة إلى الكائن المحدث مرة أخرى.

الاستجابة

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

تحديث جزئي

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

PUT /api/presets/{code}:partial

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

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

جسم الطلب

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

ملاحظة

isV2 هو الاستثناء الوحيد حتى هنا: يتم إعادة كتابته في كل استدعاء UpdatePartial، مع الافتراضي إلى true عند حذفه. أرسل isV2: false صراحةً إذا كان يجب أن يظل الإعداد المسبق إعدادًا مسبقًا بنمط v1.

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

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

الاستجابة

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

استنساخ

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

POST /api/presets/{code}:clone

ملاحظة

على عكس Clone في واجهة برمجة تطبيقات قوالب البريد الإلكتروني، لا تحتوي نقطة النهاية هذه على معلمة application — فهي تستنسخ دائمًا داخل تطبيق الإعداد المسبق المصدر نفسه. يتم دائمًا إنشاء النسخة مع hidden: false، بغض النظر عن المصدر.

جسم الطلب

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

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

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

الاستجابة

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

حذف

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

DELETE /api/presets/{code}

تنبيه

يفشل إذا كان الإعداد المسبق لا يزال مستخدمًا بواسطة نقطة send_push في رحلة قيد التشغيل أو متوقفة مؤقتًا — قم بإزالته من الرحلة أولاً. لا يمكن التراجع عن هذا الإجراء.

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

المعلمة	النوع	الوصف
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>	تجاوزات قديمة لكل منصة، مفهرسة باسم تعداد المنصة (IOS، ANDROID، HUAWEI_ANDROID، OSX). انظر كائن PlatformProperties أدناه.
open_action	OpenAction	الإجراء الذي يتم تشغيله عندما يفتح المستخدم الإشعار، يتم تطبيقه على كل منصة. حصري متبادل مع open_actions — تحدد الاستجابة واحدًا بالضبط.
open_actions	map<string, OpenAction>	تجاوز open_action لكل منصة، مفهرس بـ رمز نوع الجهاز.
deeplink	string	رمز الرابط العميق (Deep Link).
deeplink_params	map<string, string>	المعلمات التي يتم تمريرها إلى الرابط العميق.
richmedia	string	رمز الوسائط الغنية (Rich Media) الذي يفتحه الإشعار.
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	استهداف المناطق الجغرافية (Geozone)، إذا كان الإعداد المسبق يتم تشغيله جغرافيًا.
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.

Webhooks

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

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

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

الحقل	النوع	الوصف
remote_page	string	مرجع صفحة بعيدة قديم.
wns_content	string	JSON قالب Windows toast قديم، كما هو مقبول بواسطة طرق 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 فقط).

ذات صلة

Notify

مرجع الحمولة (Payload)

مرجع نقاط Customer Journey