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

إنشاء صفقة

1. معرفة ما إذا تم إنشاء منتج من خلال LIST المنتجات باستخدام فلتر external_deal_id يجب أن يكون External_deal_id فريدًا في جميع المنتجات.

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

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

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

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

إلغاء صفقة

1. تعديل حالة الطلب إلى "تم الإلغاء" لا يمكن إلغاء الطلب إلا إذا لم يتم قبوله. الحالة "تم الإلغاء" هي حالة نهائية. لا يمكن إعادة تفعيل الطلب بعد إلغائه.

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

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

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

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

تعديل صفقة

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

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

1. الحصول على الطلب إذا كنت تعرف معرّف الطلب المقابل اطّلِع على حقل الحالة.
2. في حال عدم تتبُّع معرّف الطلب: أدرِج المنتجات باستخدام فلتر external_deal_id، ثم حدِّد اسم الطلب من اسم المنتج، ثم احصل على الطلب. اطّلِع على حقل الحالة.

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

1. الحصول على مصدر المستودع الاسم هو "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 إلى أنّه تم قبول صفقة. من المتوقّع أن يتم الإنفاق في هذه الحالة عندما تتلقّى منصة DV3 طلب عرض سعر يتطابق مع بنود الصفقة، وعندما يكون هناك عنصر خطّ نشط يستهدف هذه الصفقة، وعندما يتطابق طلب عرض السعر مع معايير استهداف العنصر الخطّ. لمزيد من التفاصيل، يُرجى الاطّلاع على السلعة.** لا تتوفّر واجهة برمجة تطبيقات خاصة بالبائعين للاستعلام عمّا إذا كانت الصفقات مستهدَفة بعناصر حملات. **
      2. BUYER_STATUS_PENDINGلا ينطبق.
      3. BUYER_STATUS_PAUSEDتعني أنّ المعلِنين أوقفوا الصفقة مؤقتًا بشكل صريح. لن يتم إجراء أي إنفاق في هذه الحالة.

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

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

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

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

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

نسمح بإجراء تغييرات على جميع الحقول باستثناء بعض الحقول المهمة، مثل: startTime وendTime وrateDetails وcreativeConfig وما إلى ذلك. ونفرض عمليات تحقّق من صحة هذه الحقول المهمة. بشكل عام، يُسمح بإجراء تعديلات على هذه الحقول باستثناء creativeConfig إذا كان وقت بدء الصفقة بعد يوم واحد على الأقل في المستقبل. لا يُسمح إلا بالتعديلات التدريجية على الصفقات السارية التي يسبق وقت بدئها التاريخ الحالي، ولكنّ وقت انتهائها يقع في المستقبل. لا يُسمح بإجراء أي تغييرات على الصفقات المكتملة التي انتهى وقتها. على سبيل المثال، لا يُسمح بتعديل rateDetails صفقة تمّت قبل عام. في حالات مثل هذه، سيؤدي خيار تعديل المنتج في "مساحة العرض والفيديو 360" إلى ظهور خطأ في التحقّق من الصحة.