سير عمل واجهة برمجة التطبيقات

يوضّح هذا الدليل سير عمل واجهة برمجة التطبيقات الشائعة لإنشاء الصفقات وإلغائها واستردادها وتعديلها والتفاوض بشأنها باستخدام Deal Sync API.

إنشاء صفقة

1. تحقَّق ممّا إذا سبق إنشاء منتج من خلال طلب LIST للمنتجات باستخدام الفلتر externalDealId. يُرجى العِلم أنّه يمكن استخدام كل من camelCase externalDealId وsnake_case external_deal_id في سلسلة الفلتر. يجب أن يكون external_deal_id فريدًا في كل المنتجات.

   GET https://dv360seller.googleapis.com/v1beta1/{parent=exchanges/*/orders/*}/products?filter=externalDealId="{external_deal_id}"
   

2. إنشاء طلب يتم إنشاء اسم الطلب من خلال "مساحة العرض والفيديو 360"، وننصحك بتخزين هذا المعرّف في نظامك لاسترجاعه في المستقبل.

3. إنشاء منتج ضمن الطلب يتم إنشاء اسم المنتج من خلال "مساحة العرض والفيديو 360"، وننصحك بتخزين هذا المعرّف في نظامك لاسترداده في المستقبل.

يمكنك بدلاً من ذلك الاتصال بالرقم LIST باستخدام external_deal_id. يحتوي اسم المورد على كل من معرّف الطلب ومعرّف المنتج، ما يتيح لك تحديد الطلب الرئيسي.

إلغاء صفقة

1. تعديل حالة الطلب إلى CANCELED لا يمكن الإلغاء إلا إذا لم يتم قبول الطلب بعد. الحالة "تم الإلغاء" هي حالة نهائية، ولا يمكن إعادة تفعيل الطلب بعد إلغائه. إذا كان الطلب يتضمّن أي منتجات، لا يمكن إعادة استخدام external_deal_id.

الحصول على تفاصيل صفقة

1. الحصول على تفاصيل طلب يتم تعديل الحالة بعد أن يقبل المستخدم الطلب أو يؤرشفه أو يلغيه.
2. الحصول على تفاصيل حول منتج

الحصول على قائمة بالصفقات

1. قائمة الطلبات مع فلتر الحالة للحصول على جميع الطلبات المقبولة أو في انتظار القبول.
2. أدرِج المنتجات التي تستخدم الفلتر external_deal_id.
3. LIST كل المنتجات ضِمن طلب.

تعديل صفقة

1. تعديل ترتيب معلومات الاتصال الخاصة بالناشر
   1. لا يمكن تعديل name (لا يمكن ضبطها في updateMask). يمكن ضبط الحالة على CANCELED فقط باستخدام واجهة برمجة التطبيقات.
   2. يتعذّر تحديث partner_id.
2. تعديل لتعديل مدة صفقة معيّنة
   1. لا يمكن تعديل name وexternalDealId وtransactionType وpricingType وupdateTime .
   2. لا يتطلّب تعديل displayName إعادة موافقة المستخدم.
   3. يؤدي تعديل rateDetails أو creativeConfig إلى تغيير حالة الطلب الرئيسي إلى PENDING_ACCEPTANCE. سيُطلب من المعلِنين على "مساحة العرض والفيديو 360" قبول البنود الجديدة في صفحة "المفاوضات"، بغض النظر عمّا إذا كان قد تم قبول "طلب الشراء" السابق أم لا.

التحقّق ممّا إذا كان المستخدم قد قبل الصفقة

1. Get Order إذا كنت تعرف اسم الطلب المقابل. تحقَّق من الحقل status.
2. في حال عدم تتبُّع اسم الطلب: أدرِج المنتجات باستخدام فلتر external_deal_id، حدِّد اسم الطلب من اسم المنتج، ثم استخدِم Get Order. تحقَّق من الحقل status.

تحقَّق ممّا إذا كان المستخدم قد أعدّ الصفقة (Programmatic Guaranteed فقط)

1. Get Inventory Source. اسم المورد هو exchanges/{exchangeId}/inventorysources/{external_deal_id}. تحقَّق من حالة المشتري.
   1. صفقات الحجز:
      1. ‫BUYER_STATUS_ACTIVE: تم قبول الصفقة وإعدادها. ستبدأ الصفقة في استهلاك الميزانية عندما تتلقّى "منصة العرض والفيديو 360" طلبات عروض أسعار تتطابق مع بنود الصفقة. يتم إنشاء بند إعلان تلقائيًا أثناء إعداد الصفقة. لمزيد من التفاصيل، راجِع إعدادات الصفقة.
      2. ‫BUYER_STATUS_PENDING: تم قبول الطلب، ولكن لم يتم إعداد الصفقة بعد. لا يتم الإنفاق في هذه الحالة.
      3. BUYER_STATUS_PAUSED: أوقف المعلِن الصفقة مؤقتًا. لا يتم الإنفاق في هذه الحالة.
   2. الصفقات التي لا تتطلّب حجزًا:
      1. ‫BUYER_STATUS_ACTIVE: تم قبول الصفقة. ستبدأ الصفقة في إنفاق الأموال عندما تتلقّى "مساحة العرض والفيديو 360" طلبات عروض أسعار مطابقة، ويستهدف عنصر نشط في الحملة الصفقة، وتتطابق طلبات عروض الأسعار مع معايير استهداف العنصر في الحملة. لمزيد من التفاصيل، يُرجى الاطّلاع على العناصر. (ملاحظة: لا تتوفّر واجهة Seller API للاستعلام عمّا إذا كانت الصفقات مستهدَفة من خلال عناصر الحملة).
      2. ‫BUYER_STATUS_PENDING: لا ينطبق ذلك على الصفقات التي لا تتطلّب حجزًا.
      3. BUYER_STATUS_PAUSED: أوقف المعلِن الصفقة مؤقتًا بشكلٍ صريح. لا يتم الإنفاق في هذه الحالة.

إيقاف صفقة مؤقتًا واستئنافها بعد قبولها

1. تعديل مصدر المستودع حالة البائع
   1. لا يؤدي الإيقاف المؤقت أو استئناف العرض إلى إيقاف عرض الصفقات. عندما يوقف بائع صفقة مؤقتًا، تظهر رسالة إعلامية للمعلِنين في واجهة مستخدم "مساحة العرض والفيديو 360" للمساعدة في تحديد المشاكل وحلّها في الصفقات التي لا يتم فيها الإنفاق.

إعادة التفاوض (تعديل صفقة بعد قبولها)

تشير إعادة التفاوض إلى التعديلات التي يتم إجراؤها على صفقة بعد أن يقبلها المشتري. يتيح ذلك لجهات تبادل الإعلانات والمشترين تعديل البنود في الصفقات الحالية. على سبيل المثال، قد يجد أحد المصادر أنّ وقت انتهاء الرحلة الجوية الخاص بصفقة مقبولة غير صحيح، ويمكنه استخدام Product Patch لإرسال آخر المعلومات إلى المشترين في "مساحة العرض والفيديو 360" قبل بدء عرض الصفقة.

التغييرات المسموح بها وغير المسموح بها

اطّلِع على مقالات مركز مساعدة "مساحة العرض والفيديو 360" للحصول على تفاصيل كاملة حول قواعد التفاوض وإعادة التفاوض بشأن الصفقات:

• إعادة التفاوض على صفقة Programmatic Guaranteed
• التفاوض على صفقة في "مساحة العرض والفيديو 360"