واجهة إنفاق الإعلانات

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

قبل أن تبدأ

• يجب أن تشمل الباقة واجهة API وعائد الحملات معًا. ومن دون عائد الحملات يرد المسار 403 مع Campaign returns are not in this plan.
• استخدم مفتاحًا بصلاحية قراءة وكتابة أنشأه مالك أو مسؤول. والمفتاح الذي أنشأه عضو أو مشاهد يتلقى 403.
• إن كان لمنشئ المفتاح دور مخصص يمنع عائد الحملات، يرد المسار 403 مع Campaign returns are not allowed for this role.
• استخدم أسماء الحملات نفسها التي تحملها طلبات متجرك في وسوم الحملة، مثل قيمة utm_campaign، ليتطابق الإنفاق مع المبيعات.

إرسال الإنفاق

POST /ad-spend

للجسم حقل واحد هو rows، وهو قائمة من 1 إلى 1000 رقم يومي:

curl -X POST https://rutbacrm.com/api/v1/ad-spend \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"rows": [
        {"campaign": "ramadan-sale", "source": "google", "spent_on": "2026-11-06", "amount": "120.50", "currency": "SAR"},
        {"campaign": "ramadan-sale", "source": "google", "spent_on": "2026-11-07", "amount": "30.00", "currency": "SAR"}
      ]}'

الرد 200 مع عددين:

{
  "data": {
    "saved": 2,
    "unchanged": 0
  }
}

كيف تُطابق الصفوف

الصف هو نفسه رقم سابق حين تتطابق الحملة واليوم والعملة والمصدر جميعًا. وتُقارن أسماء الحملات دون اعتبار لحالة الأحرف أو المسافات المحيطة، فـRamadan-Sale وramadan-sale حملة واحدة. والصف دون مصدر لا يطابق إلا الأرقام السابقة التي لا مصدر لها.

الأرقام المستبدلة والمحذوفة تبقى قيودًا ملغاة ولا تُمحى.

الأخطاء

الطلب كله أو لا شيء. فإن كان أي صف غير صالح لا يُحفظ شيء، ويكون الرد 422:

صحح الصف وأرسل الطلب كاملًا مرة أخرى.

سكربت يومي

الإعداد المعتاد سكربت يعمل مرة في اليوم في أداة السكربتات لدى منصة الإعلانات، ويرسل أمس والأيام الستة التي قبله، فتُلتقط التصحيحات المتأخرة من منصة الإعلانات. ولأن كل يوم يستبدل نفسه فإعادة الإرسال لا تكلف شيئًا. أبقِ كل تشغيل تحت 1000 صف، وإن كنت تتابع حملات كثيرة فوزّع الأيام على عدة طلبات.

معلومات مفيدة

• يُحفظ الإنفاق يوميًا، ولا يوجد رقم بالساعة.
• تظهر الأرقام التي ترسلها في تقرير عائد الحملات في التطبيق بجانب الإنفاق المكتوب يدويًا، ويستطيع المالكون والمسؤولون إزالتها من هناك.
• لا يُحوَّل أي رقم بين العملات. أرسل الإنفاق بالعملة التي يبيع بها متجرك، وإلا ظهرت العملات منفصلة في التقرير.