Listings APIListings API
تسجيل الدخول

المنشورات

انشر الإعلانات والفعاليات والعروض على Google وFacebook عبر client.posts.

جميع أساليب المنشورات ضمن client.posts. تقبل الأساليب التي تأخذ location_id معرّفات رقمية أو مرمّزة بصيغة base64؛ راجع معرّفات المواقع.

تُنشر المنشورات على منصتين: GOOGLE وFACEBOOK. أنواع المنشورات هي ANNOUNCEMENT وEVENT وOFFER وCOVID19 وPRODUCT. أنواع الدعوة إلى اتخاذ إجراء هي BOOK وORDER وSHOP وLEARN_MORE وSIGN_UP وGET_OFFER؛ ويجب دائمًا توفير cta_type وcta_url معًا.

النشر غير المتزامن

النشر غير متزامن. تُرجع استدعاءات الإنشاء status: INPROGRESS؛ استعلم دوريًا باستخدام posts.retrieve() (أو posts.bulk_retrieve() للحملات الجماعية) حتى تصبح الحالة SUCCESS، وافحص publishDetails[].submissionError لمعرفة حالات الفشل لكل منصة.

رسائل خاصة بكل منصة

يقبل كل أسلوب إنشاء message إما كسلسلة نصية عادية، فينشر النص نفسه على كل منصة، أو كقاموس dict يربط كل منصة بنص:

Python
message = {  "GOOGLE": "Book your summer checkup today!",  "FACEBOOK": "Summer checkups are here. Tag a friend who needs one!",}

عندما يكون message قاموس dict، يجب أن يحتوي على مدخل لكل منصة في sites؛ ويُطلق SDK الاستثناء ValidationError قبل أي استدعاء عبر الشبكة إذا كان أحد المداخل مفقودًا.

posts.bulk_publish

انشر منشورًا واحدًا لعدة مواقع على Google وFacebook باستدعاء واحد. هذه هي الطريقة الموصى بها للنشر: يستهدف sites المنصتين افتراضيًا، وتُحوَّل الرسالة الواحدة (أو قاموس dict الذي يحدد نصًا لكل منصة) إلى مدخل واحد لكل منصة، وتُرمَّز معرّفات المواقع تلقائيًا، ويُتحقَّق من صحة حمولة الطلب من جانب العميل قبل أي استدعاء عبر الشبكة.

Python
client.posts.bulk_publish(    *,    name: str,    location_ids: list[str | int],    message: str | dict[str, str],    sites: list[str] | None = None,    post_type: str = "ANNOUNCEMENT",    cta_type: str | None = None,    cta_url: str | None = None,    media_url: str | None = None,    scheduled_dates: dict | None = None,    context_info: dict | None = None,    additional_fields: dict | None = None,) -> APIObject
الوسيطةالنوعالوصف
namestrاسم الحملة الداخلي (لا يظهر للعملاء). مطلوب.
location_idslist[str | int]جميع المواقع المراد النشر لها (معرّفات رقمية أو بصيغة base64). مطلوب.
messagestr | dictنص المنشور لجميع المنصات، أو قاموس dict يحدد نصًا لكل منصة. مطلوب.
siteslist[str]المنصات المستهدفة. القيمة الافتراضية هي ["GOOGLE", "FACEBOOK"].
post_typestrANNOUNCEMENT (الافتراضي)، أو EVENT، أو OFFER، أو COVID19، أو PRODUCT.
cta_typestrزر اختياري للدعوة إلى اتخاذ إجراء؛ يتطلب cta_url.
cta_urlstrوجهة زر الدعوة إلى اتخاذ إجراء.
media_urlstrعنوان URL اختياري لصورة متاحة للعامة تُرفق على كل منصة.
scheduled_datesdictنطاق زمني اختياري لـ {"startDatetime", "endDatetime"}.
context_infodictتفاصيل الحدث أو العرض عندما يتطلبها post_type.
additional_fieldsdictحقول camelCase إضافية غير متداخلة تُدمج كما هي.
Python
result = client.posts.bulk_publish(  name="Holiday hours",  location_ids=[16808, 16809, 16810],  message="Open until 10pm through the holidays!",  media_url="https://cdn.example.com/holiday.jpg",  cta_type="LEARN_MORE",  cta_url="https://example.com/holiday-hours",)print(result.socialPost.id, result.socialPost.status)  # INPROGRESS, publishes async

posts.create_announcement

أنشئ منشورًا من نوع ANNOUNCEMENT: رسالة عادية مع دعوة اختيارية إلى اتخاذ إجراء ووسائط اختيارية. القيمة الافتراضية لـ sites هي ["GOOGLE"].

Python
client.posts.create_announcement(    *,    name: str,    location_ids: list[str | int],    message: str | dict[str, str],    sites: list[str] | None = None,    cta_type: str | None = None,    cta_url: str | None = None,    media_url: str | None = None,    scheduled_dates: dict | None = None,    additional_fields: dict | None = None,) -> APIObject
Python
result = client.posts.create_announcement(  name="Grand Opening",  location_ids=[16808],  message="Acme Dental is now open!",  sites=["GOOGLE"],  cta_type="LEARN_MORE",  cta_url="https://acmedental.example.com/opening",)print(result.socialPost.id)

posts.create_event

أنشئ منشورًا من نوع EVENT بعنوان ونطاق زمني له بداية ونهاية. يتطلب Google عنوان الحدث؛ ويُطلق SDK الاستثناء ValidationError إذا كان العنوان مفقودًا. start_day وend_day تاريخان (YYYY-MM-DD)؛ أما start_time وend_time فهما سلسلتان نصيتان للعرض مثل "10:00am".

Python
client.posts.create_event(    *,    name: str,    location_ids: list[str | int],    message: str | dict[str, str],    title: str,    start_day: str,    end_day: str,    start_time: str | None = None,    end_time: str | None = None,    sites: list[str] | None = None,    cta_type: str | None = None,    cta_url: str | None = None,    media_url: str | None = None,    scheduled_dates: dict | None = None,    additional_fields: dict | None = None,) -> APIObject
Python
result = client.posts.create_event(  name="Free checkup day",  location_ids=[16808],  message="Join us for free dental checkups!",  title="Free Checkup Day",  start_day="2026-08-01",  end_day="2026-08-01",  start_time="10:00am",  end_time="4:00pm",  cta_type="BOOK",  cta_url="https://acmedental.example.com/book",)print(result.socialPost.id)

posts.create_offer

أنشئ منشورًا من نوع OFFER يتضمن قسيمة وخصمًا وشروطًا. يحدد title اسم العرض وهو مطلوب؛ ويحدد start_day وend_day (YYYY-MM-DD) بداية صلاحيته ونهايتها.

Python
client.posts.create_offer(    *,    name: str,    location_ids: list[str | int],    message: str | dict[str, str],    title: str,    coupon_code: str | None = None,    discount: str | None = None,    redeem_url: str | None = None,    terms_conditions: str | None = None,    start_day: str | None = None,    end_day: str | None = None,    sites: list[str] | None = None,    cta_type: str | None = None,    cta_url: str | None = None,    media_url: str | None = None,    scheduled_dates: dict | None = None,    additional_fields: dict | None = None,) -> APIObject
Python
result = client.posts.create_offer(  name="Summer whitening sale",  location_ids=[16808],  message="20% off teeth whitening all week!",  title="Summer Whitening Sale",  coupon_code="SUMMER20",  discount="20%",  redeem_url="https://acmedental.example.com/sale",  terms_conditions="One per patient. Not valid with other offers.",  start_day="2026-08-01",  end_day="2026-08-07",)print(result.socialPost.id)

posts.create

أنشئ منشورًا من قاموس dict خام لمتن الطلب. تمرر الحقول دون تداخل في camelCase، وتضعها الدالة المساعدة داخل الكائن input الذي تتطلبه API قبل الإرسال: يكون متن الطلب المرسل عبر الشبكة {"input": {...}}، ولا يكون أبدًا متنًا غير متداخل. يجب أن يكون locationIds مرمّزًا مسبقًا بصيغة base64. يُفضَّل استخدام أساليب الإنشاء محددة الأنواع أعلاه للاستفادة من الوسيطات المسماة، والترميز التلقائي للمعرّفات، والتحقق من الصحة من جانب العميل.

Python
client.posts.create(body: dict) -> APIObject

المطلوب: postName وlocationIds (base64) وpostType وpostSites.

Python
result = client.posts.create({  "postName": "Grand Opening",  "locationIds": ["TG9jYXRpb246MTY4MDg="],  "postType": "ANNOUNCEMENT",  "postSites": ["GOOGLE"],  "postMessage": [{"site": "GOOGLE", "message": "We are now open!"}],})print(result.socialPost.id)

posts.retrieve

اجلب منشورًا مع محتواه وحالة نشره على كل منصة وتحليلاته. استعلم دوريًا باستخدام هذا الأسلوب بعد الإنشاء حتى تصبح قيمة status هي SUCCESS.

Python
client.posts.retrieve(post_id: str) -> APIObject
Python
post = client.posts.retrieve("U29jaWFsUG9zdDo0NDEyMg==")print(post.status)for detail in post.publishDetails:  print(detail.site, detail.submissionError)

posts.delete

احذف منشورًا وأزله من كل منصة نُشر عليها.

Python
client.posts.delete(post_id: str) -> APIObject
Python
client.posts.delete("U29jaWFsUG9zdDo0NDEyMg==")

posts.list_for_location

اسرد حملات المنشورات التي تستهدف موقعًا. تُقسَّم النتائج إلى صفحات باستخدام الإزاحة: تحتوي النتيجة على .records بالإضافة إلى .pageInfo الذي يحتوي على totalPages وtotalRecords وhasNextPage. تَرِد الاستجابة ضمن postsByLocation.

يرفض هذا المسار tag، لذا يقبل SDK هذه الوسيطة منذ الإصدار 0.5.3 للحفاظ على التوافق مع الإصدارات السابقة ولا يرسلها أبدًا عبر الشبكة. استخدم posts.bulk_list_for_location عندما تحتاج إلى التصفية حسب الوسوم.

Python
client.posts.list_for_location(    location_id: str | int,    *,    tag: str = "all",    page: int | None = None,    per_page: int | None = None,    filters: dict | None = None,    sort_fields: dict | None = None,) -> APIObject
Python
result = client.posts.list_for_location(16808, page=1, per_page=10)for post in result.records:  print(post.id, post.name)print(result.pageInfo.totalRecords)

posts.bulk_retrieve

اجلب حملة جماعية (تشمل عدة مواقع) مع حالة النشر والتحليلات لكل موقع.

Python
client.posts.bulk_retrieve(bulk_post_id: str) -> APIObject
Python
bulk = client.posts.bulk_retrieve("QnVsa1Bvc3Q6OTk=")print(bulk.status)

posts.bulk_list_for_location

اسرد الحملات الجماعية (التي تشمل عدة مواقع) التي تتضمن موقعًا معينًا. المعلمات وبنية النتيجة مماثلة لما في posts.list_for_location.

Python
client.posts.bulk_list_for_location(    location_id: str | int,    *,    tag: str = "all",    page: int | None = None,    per_page: int | None = None,    filters: dict | None = None,    sort_fields: dict | None = None,) -> APIObject
Python
result = client.posts.bulk_list_for_location(16808, page=1, per_page=10)for campaign in result.records:  print(campaign.id, campaign.name)

انظر أيضًا