Package google.shopping.merchant.promotions.v1beta

אינדקס

PromotionsService

שירות לניהול מבצעים על מוצרים.

GetPromotion

rpc GetPromotion(GetPromotionRequest) returns (Promotion)

מאחזר את פרטי המבצע מחשבון Merchant Center.

אחרי שמוסיפים או מעדכנים את פרטי המבצע, יכול להיות שיחלפו כמה דקות עד שאפשר יהיה לאחזר את המבצע המעודכן.

היקפי ההרשאות

נדרש היקף ההרשאות הבא של OAuth:

  • https://www.googleapis.com/auth/content

למידע נוסף, קראו את המאמר סקירה כללית של OAuth 2.0.
InsertPromotion

rpc InsertPromotion(InsertPromotionRequest) returns (Promotion)

מוסיף מבצע לחשבון Merchant Center שלכם. אם הוא כבר קיים, הוא מעדכן את המבצע במקום זאת.

היקפי ההרשאות

נדרש היקף ההרשאות הבא של OAuth:

  • https://www.googleapis.com/auth/content

למידע נוסף, קראו את המאמר סקירה כללית של OAuth 2.0.
ListPromotions

rpc ListPromotions(ListPromotionsRequest) returns (ListPromotionsResponse)

בתיבת הדו-שיח הזו מפורטים המבצעים בחשבון Merchant Center שלכם. התשובה עשויה להכיל פחות פריטים ממה שצוין על ידי pageSize. אפשר להסתמך על pageToken כדי לדעת אם יש פריטים נוספים שצריך לבקש.

אחרי שמוסיפים או מעדכנים מבצע, יכול להיות שיחלפו כמה דקות עד שאפשר יהיה לאחזר את המבצע המעודכן לאחר עיבוד.

היקפי ההרשאות

נדרש היקף ההרשאות הבא של OAuth:

  • https://www.googleapis.com/auth/content

למידע נוסף, קראו את המאמר סקירה כללית של OAuth 2.0.

מאפיינים

מאפיינים.

שדות
product_applicability

ProductApplicability

חובה. המבצע חל על כל המוצרים או על רק מוצרים ספציפיים.
offer_type

OfferType

חובה. סוג המבצע. אפשר להשתמש במאפיין הזה כדי לציין אם הלקוחות צריכים קוד שובר כדי לממש את המבצע.
generic_redemption_code

string

זה שינוי אופציונלי. קוד מימוש גנרי של מבצע לשימוש עם השדה offerType, והוא חייב לעמוד בדרישות המינימליות.
long_title

string

חובה. שם ארוך למבצע.
coupon_value_type

CouponValueType

חובה. המאפיין coupon value type משמש לציון סוג המבצע שאתם מציעים. חובה לשלוח כמה מאפיינים בהתאם לסוג ערך השובר שנבחר.
promotion_destinations[]

DestinationEnum

חובה. רשימת היעדים שעליהם חל המבצע. אם לא תציינו ערך נתמך של יעד במקור הנתונים, המבצע יוצג במודעות שופינג ובכרטיסי מוצר חינמיים כברירת מחדל.

יכול להיות ששלחתם בעבר את הערכים הבאים בתור יעדים למוצרים שלכם: Shopping Actions, Surfaces across Google, Local surfaces across Google. כדי לייצג את הערכים האלה, צריך להשתמש בפונקציה FREE_LISTINGS, FREE_LOCAL_LISTINGS, LOCAL_INVENTORY_ADS. פרטים נוספים זמינים במאמר יעד המבצע.
item_id_inclusion[]

string

זה שינוי אופציונלי. סינון המוצרים לפי מזהה הפריט של המבצע. המאפיינים של סינון המוצרים רלוונטיים רק כשמאפיין המוצרים שעליהם חל המבצע product_applicability מוגדר כ-specific_products.
brand_inclusion[]

string

זה שינוי אופציונלי. סינון המוצרים לפי המותג של המבצע. המאפיינים של סינון המוצרים רלוונטיים רק כשמאפיין המוצרים שעליהם חל המבצע product_applicability מוגדר כ-specific_products.
item_group_id_inclusion[]

string

זה שינוי אופציונלי. סינון המוצרים לפי מזהה קבוצת הפריטים של המבצע. המאפיינים של סינון המוצרים רלוונטיים רק כאשר הערך של מאפיין המוצרים שעליהם חל המבצע [product_applicability] הוא specific_products.
product_type_inclusion[]

string

זה שינוי אופציונלי. סינון המוצרים לפי סוג המוצר שבמבצע. המאפיינים של סינון המוצרים רלוונטיים רק כשמאפיין המוצרים שעליהם חל המבצע product_applicability מוגדר כ-specific_products.
item_id_exclusion[]

string

זה שינוי אופציונלי. סינון מוצרים לפי החרגה של מזהה פריט במבצע. המאפיינים של סינון המוצרים רלוונטיים רק כשמאפיין המוצרים שעליהם חל המבצע product_applicability מוגדר כ-specific_products.
brand_exclusion[]

string

זה שינוי אופציונלי. סינון מוצרים לפי החרגת מותגים במבצע. המאפיינים של סינון המוצרים רלוונטיים רק כשמאפיין המוצרים שעליהם חל המבצע product_applicability מוגדר כ-specific_products.
item_group_id_exclusion[]

string

זה שינוי אופציונלי. סינון מוצרים לפי מזהה קבוצת הפריטים. המאפיינים של סינון המוצרים רלוונטיים רק כשמאפיין המוצרים שעליהם חל המבצע product_applicability מוגדר כ-specific_products. החרגה של המבצע.
product_type_exclusion[]

string

זה שינוי אופציונלי. סינון מוצרים לפי החרגה של סוג המוצר במבצע. המאפיינים של סינון המוצרים רלוונטיים רק כשמאפיין המוצרים שעליהם חל המבצע product_applicability מוגדר כ-specific_products.
minimum_purchase_amount

Price

זה שינוי אופציונלי. סכום רכישה מינימלי למבצע.
minimum_purchase_quantity

int64

זה שינוי אופציונלי. כמות רכישה מינימלית במבצע.
limit_quantity

int64

זה שינוי אופציונלי. כמות מקסימלית של רכישה במבצע.
limit_value

Price

זה שינוי אופציונלי. מחיר מוצר מקסימלי במבצע.
percent_off

int64

זה שינוי אופציונלי. ההנחה באחוזים שמוצעת במבצע.
money_off_amount

Price

זה שינוי אופציונלי. סכום ההנחה הכספית שמוצע במבצע.
get_this_quantity_discounted

int64

זה שינוי אופציונלי. מספר הפריטים בהנחה במבצע. המאפיין מוגדר כאשר couponValueType שווה ל-buy_m_get_n_money_off או ל-buy_m_get_n_percent_off.
free_gift_value

Price

זה שינוי אופציונלי. שווי מתנה במסגרת המבצע.
free_gift_description

string

זה שינוי אופציונלי. תיאור המתנה במסגרת המבצע.
free_gift_item_id

string

זה שינוי אופציונלי. מזהה פריט המתנה במסגרת המבצע.
promotion_effective_time_period

Interval

חובה. TimePeriod ייצוג של תאריכי התוקף של המבצע. המאפיין הזה מציין שאפשר לבדוק את המבצע בחנות הווירטואלית במהלך התקופה הזו.
promotion_display_time_period

Interval

זה שינוי אופציונלי. TimePeriod ייצוג של תאריכי הצגת המבצע. המאפיין הזה מציין את התאריך והשעה שבהם המבצע יהיה זמין ב-Google.com ובמודעות שופינג. אם לא תציינו את תקופת הזמן להצגת המבצע promotion_display_time_period, תקופת התוקף של המבצע promotion_effective_time_period תקבע את התאריך והשעה שבהם המבצע יהיה פעיל ב-Google.com ובמודעות שופינג.
store_applicability

StoreApplicability

זה שינוי אופציונלי. אם המבצע חל על כל החנויות, או רק על חנויות ספציפיות. אם לא ציינת את המוצרים שעליהם חל המבצע, תופיע הודעת שגיאה לגבי מבצעים במודעות מלאי של חנויות מקומיות. שגיאה מסוג INVALID_ARGUMENT תיזרק אם store_applicability מוגדר לערך ALL_STORES ו-store_codes_inclusion או score_code_exclusion מוגדר כערך.
store_codes_inclusion[]

string

זה שינוי אופציונלי. קודי חנויות שייכללו במבצע. המאפיינים של מסנן החנויות רלוונטיים רק כשהמאפיין store_applicability מוגדר כ-specific_stores.

קוד החנות (מזהה החנות שרשום בפרופיל העסק) של החנות הפיזית שבה המוצר נמכר. מידע נוסף זמין במפרט נתוני מלאי המוצרים בחנויות המקומיות.
store_codes_exclusion[]

string

זה שינוי אופציונלי. קודי חנויות שלא ייכללו במבצע. המאפיינים של מסנן החנויות רלוונטיים רק כשהמאפיין store_applicability מוגדר כ-specific_stores.
promotion_url

string

זה שינוי אופציונלי. כתובת ה-URL של הדף באתר של המוכר שבו מוצג המבצע. אם לא ציינת promotion_url, מבצעים שקשורים למודעות מלאי של חנויות מקומיות יציגו הודעת שגיאה. כתובת ה-URL משמשת כדי לאשר שהמבצע תקף ואפשר לממש אותו.

CouponValueType

סוג ערך שובר של מבצע.

טיפוסים בני מנייה (enum)
COUPON_VALUE_TYPE_UNSPECIFIED מציין שסוג ערך השובר לא צוין.
MONEY_OFF סוג ערך שובר הנחה.
PERCENT_OFF סוג ערך שובר באחוזים.
BUY_M_GET_N_MONEY_OFF בקניית כמות M, מקבלים הנחה של N כסף על סוג ערך השובר. יש לכלול את minimum_purchase_quantity ואת get_this_quantity_discounted. חובה לכלול גם את money_off_amount.
BUY_M_GET_N_PERCENT_OFF בקניית כמות M, מקבלים הנחה של N אחוזים בערך שובר. יש לכלול את minimum_purchase_quantity ואת get_this_quantity_discounted. חובה לכלול גם את percent_off_percentage.
BUY_M_GET_MONEY_OFF קונים כמות M ומקבלים הנחה. minimum_purchase_quantity וגם money_off_amount צריכים להופיע.
BUY_M_GET_PERCENT_OFF קונים כמות M ומקבלים הנחה. minimum_purchase_quantity וגם percent_off_percentage צריכים להופיע.
FREE_GIFT מתנה עם תיאור בלבד.
FREE_GIFT_WITH_VALUE מתנה עם ערך כספי.
FREE_GIFT_WITH_ITEM_ID מתנה עם מזהה פריט.
FREE_SHIPPING_STANDARD סוג ערך רגיל של שובר משלוח חינם.
FREE_SHIPPING_OVERNIGHT סוג הערך של שובר למשלוח חינם תוך 24 שעות.
FREE_SHIPPING_TWO_DAY סוג הערך של שובר למשלוח חינם תוך יומיים בלבד.

GetPromotionRequest

בקשת הודעה ל-method GetPromotion.

שדות
name

string

חובה. שם המבצע שצריך לאחזר. פורמט: accounts/{account}/promotions/{promotions}

InsertPromotionRequest

בקשת הודעה ל-method InsertPromotion.

שדות
parent

string

חובה. החשבון שאליו יתווסף שובר הפרסום. פורמט: accounts/{account}
promotion

Promotion

חובה. המבצע להוספה.
data_source

string

חובה. מקור הנתונים של הפורמט מבצע: accounts/{account}/dataSources/{datasource}.

ListPromotionsRequest

בקשת הודעה ל-method ListPromotions.

שדות
parent

string

חובה. החשבון שעבורו רוצים להציג מבצעים שעובדו. פורמט: accounts/{account}
page_size

int32

פלט בלבד. המספר המקסימלי של מבצעים שצריך להחזיר. ייתכן שהשירות יחזיר פחות מהערך הזה. הערך המקסימלי הוא 1,000. ערכים מעל 1,000 יועברו ל-1,000. אם לא צויין ערך, יוחזר מספר המבצעים המקסימלי.
page_token

string

פלט בלבד. אסימון דף, שהתקבל מקריאה קודמת ב-ListPromotions. צריך לספק אותה כדי לאחזר את הדף הבא.

במהלך החלוקה לדפים, כל שאר הפרמטרים שסופקו ל-ListPromotions חייבים להתאים לקריאה שסיפקה את אסימון הדף.

ListPromotionsResponse

הודעת תשובה לשיטה ListPromotions.

שדות
promotions[]

Promotion

המבצעים שעובדו מהחשבון שצוין.
next_page_token

string

אסימון, שניתן לשלוח בתור page_token כדי לאחזר את הדף הבא. אם השדה הזה יושמט, אין דפים נוספים.

OfferType

סוג מבצע של מבצע.

טיפוסים בני מנייה (enum)
OFFER_TYPE_UNSPECIFIED סוג ההצעה לא ידוע.
NO_CODE סוג המבצע ללא קוד.
GENERIC_CODE סוג המבצע עם קוד. יש לציין קוד מימוש גנרי למבצע כאשר offerType = GENERIC_CODE.

ProductApplicability

המוצר או רשימת המוצרים שעליהם חל המבצע.

טיפוסים בני מנייה (enum)
PRODUCT_APPLICABILITY_UNSPECIFIED המוצרים שעליהם חל המבצע לא ידועים.
ALL_PRODUCTS רלוונטי לכל המוצרים.
SPECIFIC_PRODUCTS רלוונטי רק למוצר אחד או לרשימת מוצרים אחת.

תוכן מקודם

מייצג מבצע. מידע נוסף זמין במאמרים הבאים.

מאפייני הקלט של המבצעים הנדרשים כדי לעבור בדיקות אימות נתונים מוגדרים בעיקר למטה:

אחרי שמוסיפים ומעדכנים את פרטי המבצע, יכול להיות שיחלפו כמה דקות עד שאפשר יהיה לאחזר את המבצע הסופי.

שדות
name

string

מזהה. שם הקידום. פורמט: accounts/{account}/promotions/{promotion}
promotion_id

string

חובה. המשתמש סיפק מזהה מבצע שמזהה את המבצע באופן ייחודי. כדי למנוע פסילות של מבצעים, צריך לעמוד בדרישות המינימליות.
content_language

string

חובה. קוד שפה בן שתי אותיות לפי תקן ISO 639-1 שמשויך למבצע.

מבצעים זמינים רק בשפות נבחרות.
target_country

string

חובה. מדינת היעד שמשמשת כחלק מהמזהה הייחודי. מיוצג כקוד של אזור CLDR.

התכונה 'מבצעים' זמינה רק במדינות מסוימות. בכרטיסי מוצר חינמיים ובמודעות שופינג מודעות מלאי של חנויות מקומיות.
redemption_channel[]

RedemptionChannel

חובה. ערוץ מימוש של המבצע. צריך להזין לפחות ערוץ אחד.
data_source

string

פלט בלבד. מקור הנתונים הראשי של המבצע.
attributes

Attributes

זה שינוי אופציונלי. רשימה של מאפייני מבצע.
custom_attributes[]

CustomAttribute

זה שינוי אופציונלי. רשימה של מאפיינים מותאמים אישית (שהמוכר סיפק). אפשר להשתמש בו גם כדי לשלוח כל מאפיין של מפרט הנתונים בגרסה הכללית (לדוגמה, { "name": "size type", "value": "regular" }). האפשרות הזו שימושית לשליחת מאפיינים שלא נחשפו במפורש על ידי ה-API.
promotion_status

PromotionStatus

פלט בלבד. הסטטוס של מבצע, בעיות באימות נתונים, כלומר מידע על מבצע שמחושב באופן אסינכרוני.
version_number

int64

זה שינוי אופציונלי. מייצג את הגרסה הקיימת (העדכניות) של המבצע, שניתן להשתמש בה כדי לשמור על הסדר הנכון כשמבצעים כמה עדכונים בו-זמנית.

אם המדיניות מוגדרת, המערכת מונעת את ההוספה של פריטים כשמספר הגרסה נמוך ממספר הגרסה הנוכחי של המבצע הקיים. אפשר לבצע הוספה מחדש (לדוגמה, רענון המבצע אחרי 30 ימים) עם הערך הנוכחי של version_number.

אם הפעולה נמנעת, המערכת תבטל את החריגה שבוטלה.

PromotionStatus

הסטטוס של קידום המכירות.

שדות
destination_statuses[]

DestinationStatus

פלט בלבד. היעדים שאליהם מיועד המבצע.
item_level_issues[]

ItemLevelIssue

פלט בלבד. רשימה של בעיות שקשורות למבצע.
creation_date

Timestamp

פלט בלבד. התאריך שבו נוצר קידום המכירות בפורמט ISO 8601: תאריך, שעה וקיזוז. לדוגמה: 2020-01-02T09:00:00+01:00 או 2020-01-02T09:00:00Z
last_update_date

Timestamp

פלט בלבד. התאריך שבו סטטוס המבצע עודכן לאחרונה בפורמט ISO 8601: תאריך, שעה וקיזוז. לדוגמה: 2020-01-02T09:00:00+01:00 או 2020-01-02T09:00:00Z

DestinationStatus

הסטטוס של היעד שצוין.

שדות
reporting_context

ReportingContextEnum

פלט בלבד. השם של יעד המבצע.
status

State

פלט בלבד. הסטטוס של היעד שצוין.

ארץ

המצב הנוכחי של המבצע.

טיפוסים בני מנייה (enum)
STATE_UNSPECIFIED מצב קידום לא ידוע.
IN_REVIEW קידום הסרטון נמצא בבדיקה.
REJECTED קידום המכירות נדחה.
LIVE המבצע אושר ופעיל.
STOPPED המוכר הפסיק את המבצע.
EXPIRED קידום המכירות כבר לא פעיל.
PENDING המבצע לא הופסק וכל הביקורות מאושרות, אבל תאריך הפעילות חל בעתיד.

ItemLevelIssue

הבעיה שמשויכת למבצע.

שדות
code

string

פלט בלבד. קוד השגיאה של הבעיה.
severity

Severity

פלט בלבד. איך הבעיה הזו משפיעה על הצגת המבצע.
resolution

string

פלט בלבד. האם המוכר יכול לפתור את הבעיה.
attribute

string

פלט בלבד. שם המאפיין, אם הבעיה נגרמת על ידי מאפיין יחיד.
reporting_context

ReportingContextEnum

פלט בלבד. היעד שאליו קשורה הבעיה.
description

string

פלט בלבד. תיאור קצר של הבעיה באנגלית.
detail

string

פלט בלבד. תיאור מפורט של הבעיה באנגלית.
documentation

string

פלט בלבד. כתובת ה-URL של דף אינטרנט שעוזר לפתור את הבעיה.
applicable_countries[]

string

פלט בלבד. רשימת קודי מדינות (ISO 3166-1 alpha-2) שבהם הבעיה רלוונטית למוצר.

מידת החומרה

חומרת הבעיה.

טיפוסים בני מנייה (enum)
SEVERITY_UNSPECIFIED לא צוין.
NOT_IMPACTED הבעיה הזו מייצגת אזהרה ואין לה השפעה ישירה על המבצע.
DEMOTED קידום המכירות יורד, וסביר להניח שהביצועים שלו יהיו מוגבלים בתוצאות החיפוש
DISAPPROVED בגלל בעיה המבצע נפסל.

RedemptionChannel

ערוץ של קידום מכירות.

טיפוסים בני מנייה (enum)
REDEMPTION_CHANNEL_UNSPECIFIED מציין שהערוץ לא צוין.
IN_STORE מציין שהערוץ נמצא בחנות. זה זהה לערוץ אחד (local) שמשמש את products.
ONLINE מציין שהערוץ במצב אונליין.

StoreApplicability

קודי חנויות או רשימה של קודי חנויות שעליהם חל המבצע. רק למבצעים במודעות מלאי של חנויות מקומיות.

טיפוסים בני מנייה (enum)
STORE_APPLICABILITY_UNSPECIFIED קודי החנויות שעליהם חל המבצע לא ידועים.
ALL_STORES המבצע תקף לכל החנויות.
SPECIFIC_STORES המבצע תקף רק לחנויות שצוינו.