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 הנחה של N אחוז בקניית כמות M. חייבים להשתתף 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

פלט בלבד. המספר המקסימלי של מבצעים שצריך להחזיר. יכול להיות שהשירות יחזיר פחות מהערך הזה. הערך המקסימלי הוא 250. ערכים מעל 250 יומרו לערך 250. אם לא מציינים ערך, המערכת תחזיר את המספר המקסימלי של המבצעים.
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 המבצע חל רק על החנויות שצוינו.