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

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

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

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

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

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

Authorization: Api YOUR_API_TOKEN

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

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

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

POST /api/presets

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

{
  "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": { ... } }، وهو كائن الإعداد المسبق (Preset object) الذي تم إنشاؤه.

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

GET /api/presets

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

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

يُرجع إعدادًا مسبقًا واحدًا للدفع برمزه، مع تعبئة كل حقل من كائن الإعداد المسبق (Preset object).

GET /api/presets/{code}

تُرجع { "preset": { ... } }، وهو كائن الإعداد المسبق (Preset object) الكامل.

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

PUT /api/presets/{code}

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

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

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

PUT /api/presets/{code}:partial

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

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

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

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

POST /api/presets/{code}:clone

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

تُرجع { "preset": { ... } }، وهو كائن الإعداد المسبق (Preset object) الجديد.

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

DELETE /api/presets/{code}

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

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

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

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