واجهة تحويلات الإعلانات — مركز المساعدة

يتيح هذان المساران لسكربت Google Ads، أو لأداتك الخاصة، أن يرفع إلى Google المبيعات والعملاء المحتملين الذين جاؤوا من نقرة على إعلان Google. تجلب ما ينتظر، وترفعه إلى Google تحويلات بلا اتصال، ثم تؤكده فلا يُعرض مرة أخرى. والسكربت الجاهز في Google Ads يفعل ذلك تمامًا كل يوم، وما يعنيه الرفع للنشاط التجاري مشروح في الإعلانات.

قبل أن تبدأ

يجب أن تشمل الباقة واجهة API وعائد الحملات.
يجب أن يكون منشئ المفتاح مالكًا أو مسؤولًا.
يعمل GET بأي مفتاح لهذا الشخص، أما POST فيحتاج إلى مفتاح قراءة وكتابة، ولذلك يستعمل السكربت مفتاحًا واحدًا بصلاحية الكتابة للاثنين.
في صفحة الإعلانات يجب أن يعمل أرسل المبيعات إلى Google Ads مع اسم التحويل للمبيعات. وما دام متوقفًا تبقى القائمة فارغة.
لا يُعرض التحويل إلا لنقرة Google تحمل gclid، قبل البيع بـ90 يومًا على الأكثر. ويسجل النقرةَ سكربتُ التتبع أو نموذج الموقع.

جلب التحويلات المنتظرة

GET /ad-conversions

curl https://rutbacrm.com/api/v1/ad-conversions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json"

الرد 200 وفيه حتى 500 تحويل، الأقدم أولًا:

{
  "data": [
    {
      "id": "0f9c2b8e-6a51-4d2e-9b7a-3c1d2e4f5a6b",
      "gclid": "Cj0KCQiA-EXAMPLE",
      "name": "CRM purchase",
      "time": "2026-11-07 14:32:05",
      "value": "250.00",
      "currency": "SAR"
    }
  ]
}

الحقل	معناه
`id`	معرّف التحويل، لتأكيده بعد ذلك
`gclid`	معرّف نقرة Google التي يرتبط بها البيع
`name`	اسم إجراء التحويل كما كُتب في صفحة الإعلانات: اسم المبيعات للبيع، واسم العملاء المحتملين للعميل المحتمل
`time`	وقت البيع أو العميل المحتمل، بصيغة `YYYY-MM-DD HH:MM:SS` بتوقيت UTC
`value`	للبيع، المبلغ بخانتين عشريتين نصًا. و`null` للعميل المحتمل أو حين لا يُعرف مبلغ
`currency`	عملة البيع، أو `null`

تعود التحويلات نفسها مع كل استدعاء حتى تؤكدها. والتحويل المنتظر الذي صار اسمه فارغًا، أو غابت نقرته، يُنحّى ولا يعود أبدًا. وقائمة data الفارغة تعني أن لا شيء ينتظر، أو أن أرسل المبيعات إلى Google Ads متوقف.

تأكيد التحويلات المرفوعة

POST /ad-conversions/confirm

أرسل معرّفات ما رفعته:

curl -X POST https://rutbacrm.com/api/v1/ad-conversions/confirm \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"ids": ["0f9c2b8e-6a51-4d2e-9b7a-3c1d2e4f5a6b"]}'

{
  "data": {
    "confirmed": 1
  }
}

confirmed عدد التحويلات التي كانت تنتظر وعُلّمت الآن بأنها أُرسلت. وتظهر مرفوعة في صفحة الإعلانات.
التأكيد مرة أخرى آمن: المعرّف المؤكد من قبل لا يُحسب، فالاستدعاء المكرر يرد 0.
القيم التي ليست معرّفات تُتجاهل، ولا يُقرأ أكثر من 1000 معرّف في الاستدعاء الواحد. وids الغائب أو الفارغ يرد 0.
لا تؤكد إلا ما رفعته. فالتحويل المؤكد لا يُعرض مرة أخرى أبدًا.

الأخطاء

الحالة	الرسالة	السبب
`401`	`Invalid API key.`	المفتاح خاطئ أو أُلغي
`403`	`API access is not in this plan.`	الباقة لا تشمل واجهة API، أو يمنعها دور مخصص عن منشئ المفتاح
`403`	`Campaign returns are not in this plan.`	الباقة لا تشمل عائد الحملات
`403`	`Campaign returns are not allowed for this role.`	يمنع دور مخصص عائد الحملات عن منشئ المفتاح
`403`	`Only owners and administrators send results to ad platforms.`	منشئ المفتاح عضو أو مشاهد
`403`	`This key is read only.`	`POST /ad-conversions/confirm` بمفتاح قراءة فقط
`415`	`Send JSON.`	لم يُرسل استدعاء التأكيد بصيغة JSON

أما بقية الحدود ورموز الحالة فهي نفسها في الواجهة كلها، راجع الأخطاء والحدود.

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

يُعرض كل بيع مرة واحدة لكل منصة، مهما تأكد الطلب.
مبيعات حملات التطبيقات في Google (gbraid وwbraid) تُسجَّل لكنها لا تُعرض هنا أبدًا.
لا يرسل رُتبة CRM نفسه شيئًا إلى Google: لا يصل إلى Google إلا ما تجلبه وترفعه أنت.