מדריך עזר ל-API של סקריפטים של Shopify

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

קיימים סוגים שונים של סקריפטים. לסקריפט מוקצה סוג בעת יצירתו ביישום Script Editor, בהתבסס על תבנית הסקריפט שאיתה תבחר להתחיל:

סקריפטים של פריטי שורה

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

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

קיימות שיטות שניתן להשתמש בהן רק בסקריפטים של פריטי שורה.

סקריפטים של שילוח

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

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

<p>Some methods <a href="#shipping-methods">can only be used in shipping scripts</a>.</p>

סקריפטים של תשלום

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

קיימות שיטות שניתן להשתמש בהן רק בסקריפטים של תשלום.

בעמוד זה

שיטות כלליות

השיטות הבאות ניתנות לשימוש בכל סוג של סקריפט:

קלט

שיטות קלט של סקריפט
שיטה	סוג החזרה	תיאור
.cart	Cart	מחזירה אובייקט סל ניתן לשינוי.
.locale	מחרוזת	מחזירה את ההגדרות האזוריות של הלקוח. לדוגמה, `en`, `fr` או `pt-BR`.

Cart

אובייקט הסל זמין רק בחנות המקוונת. לחלק מהתשלומים הנטושים יש גישה לאובייקט הסל. עם זאת, אם תהליך תשלום נסגר ולאחר מכן לקוח מבקר בתשלום הנטוש, הוא נשלח לתשלום שמולא מראש ואובייקט הסל כבר אינו קיים. הסיבה לכך היא שדוא"ל התשלום הנטוש עקף את חזית החנות.

שיטות סקריפט המשתמשות באובייקט Cart
שיטה	סוג החזרה	תיאור
.customer	Customer	מחזירה את הבעלים של הסל (אם קיים).
.shipping_address	ShippingAddress	מחזירה את הכתובת לשילוח של הבעלים של הסל (אם קיימת).
.discount_code	משתנה	מחזירה: `nil` אם אין קוד הנחה בסל `CartDiscount::FixedAmount` אם בסל מוחל סכום הנחה קבוע `CartDiscount::Percentage` אם בסל מוחלת הנחה באחוזים `CartDiscount::Shipping` אם בסל מוחלת הנחה על שילוח מחזירה קוד הנחה בודד (ראה מגבלות) `discount_code` קיים אם יושמה הנחה על הסל. עובדה זו לא בהכרח אומרת שמחיר הסל ישתנה. לדוגמה, אם הנחה חלה על סלים בשווי של מעל 50 דולר, וסקריפט מפחית את מחיר הסל מתחת ל-50 דולר, `discount_code` עדיין יהיה קיים אך מחיר הסל לא ישתנה. <p><a href="/manual/checkout-settings/script-editor/examples/vat-script">See an example of <code>discount_code</code></a>.</p> </td> </tr> <tr> <td scope="row">.line_items</td> <td><a href="#list">List</a><LineItem></td> <td>Returns a list containing the line items in the cart.</td> </tr> <tr> <td scope="row">.presentment_currency</td> <td><a href="#list">List</a><String></td> <td>Returns the customer's local (presentment) currency (in <a href="https://www.iso.org/iso-4217-currency-codes.html">ISO 4217</a> format). For example, USD. </td> </tr> <tr> <td scope="row">.subtotal_price</td> <td><a href="#money">Money</a></td> <td>Returns the subtotal price of the cart after line item discounts are applied but before discount codes are applied.</td> </tr> <tr> <td scope="row">.total_weight</td> <td><a href="https://shopify.dev/api/liquid/objects/line_item#line_item-grams">grams</a></td> <td>Returns the total weight of all the line items in the cart.</td> </tr>

CartDiscount::FixedAmount

שיטות סקריפט המשתמשות באובייקט CartDiscount::FixedAmount
שיטה	סוג החזרה	תיאור
.code	מחרוזת	מחזירה את קוד ההנחה ששימש להחלת ההנחה.
.amount	Money	מחזירה את סכום הכסף של ההנחה.
.reject({ message: String })	nil	מסרבת לקוד ההנחה שהוחל על הסל. חובה לספק `message` (הודעה).
.rejected?	בוליאני	מחזירה אם היה סירוב לקוד ההנחה.

CartDiscount::Percentage

שיטות סקריפט המשתמשות באובייקט CartDiscount::Percentage
שיטה	סוג החזרה	תיאור
.code	מחרוזת	מחזירה את קוד ההנחה ששימש להחלת ההנחה.
.percentage	עשרוני	מחזירה את אחוז ההנחה.
.reject({ message: String })	nil	מסרבת לקוד ההנחה שהוחל על הסל. חובה לספק `message` (הודעה).
.rejected?	בוליאני	מחזירה אם היה סירוב לקוד ההנחה.

CartDiscount::Shipping

שיטות סקריפט המשתמשות באובייקט CartDiscount::Shipping
שיטה	סוג החזרה	תיאור
.code	מחרוזת	מחזירה את קוד ההנחה ששימש להחלת ההנחה.
.reject({ message: String })	nil	מסרבת לקוד ההנחה שהוחל על הסל. חובה לספק `message` (הודעה).
.rejected?	בוליאני	מחזירה אם היה סירוב לקוד ההנחה.

Customer

שיטות סקריפט המשתמשות באובייקט Customer
שיטה	סוג החזרה	תיאור
.id	Integer	מחזיר את מספר המזהה של הלקוח.
.email	מחרוזת	מחזיר את כתובת הדוא"ל של הלקוח.
.tags	List<Tag>	מחזיר רשימה של מחרוזות המייצגות תגים שהוגדרו ללקוח.
.orders_count	Integer	מחזיר את המספר הכולל של ההזמנות שלקוח ביצע.
.total_spent	Money	מחזיר את הסכום הכולל שהלקוח הוציא על כל ההזמנות.
.accepts_marketing?	בוליאני	מחזיר אם הלקוח מאשר קבלת תוכן שיווקי.

LineItem

שיטות Script המשתמשות באובייקט LineItem
שיטה	סוג החזרה	תיאור
.grams	grams	מחזיר את המשקל הכולל של פריט השורה.
.line_price	Money	המחיר של פריט השורה.
.discounted?	בוליאני	מחזיר אם המחיר של פריט השורה הוזל על ידי סקריפט או על ידי הנחה שהוחלה באופן ידני. שימוש בקוד הנחה לא משפיע על הערך המוחזר.
.properties	hash	מחזיר את המאפיינים שצוינו עבור פריט שורה זה.
.variant	Variant	מחזיר את גרסת המוצר הספציפית המיוצגת על ידי פריט השורה.
.quantity	Integer	מחזיר את הכמות של פריט שורה זה.
.selling_plan_id	Integer	מחזיר את המזהה של תוכנית המכירה עבור פריט השורה. שיטה זו שימושית כאשר החנות מוכרת מינויים וברצונך שהסקריפט יזהה מתי גרסת מוצר נמכרת כמינוי.

List

שיטות Script המשתמשות באובייקט List
שיטה	סוג החזרה	תיאור
.new	List	יוצר אובייקט חדש המייצג רשימה.
.[]	רכיב או nil	מחזיר את הרכיב באינדקס שצוין.
.&	List	מחזיר רשימה חדשה המכילה רכיבים משותפים לשתי הרשימות, ללא כפילויות.
.delete_if	List	מוחק רכיבים באמצעות בלוק קוד אופציונלי. מידע נוסף מופיע בתיעוד של השיטה `delete_if` ב-Ruby.
.empty?	בוליאני	מחזיר `true` אם הרשימה לא מכילה רכיבים.
.first	רכיב או nil	מחזיר את הרכיב הראשון או `nil` אם הרשימה ריקה.
.index(*args, &block)	int או nil	מחזיר את האינדקס של הרכיב הראשון ברשימה. אם ניתן בלוק במקום ארגומנט, מחזיר את האינדקס של הרכיב הראשון שעבורו הבלוק הוא true.
.rindex(*args, &block)	int או nil	מחזיר את האינדקס של הרכיב האחרון ברשימה. אם ניתן בלוק במקום ארגומנט, מחזיר את האינדקס של הרכיב הראשון שעבורו הבלוק הוא true.
.last	רכיב או nil	מחזיר את הרכיב האחרון או `nil` אם הרשימה ריקה.
.length	int	מחזיר את מספר הרכיבים ברשימה.
.size	int	כינוי ל-length.
.each(*args, &block)	List	קורא לבלוק פעם אחת עבור כל רכיב ברשימה, ומעביר את הרכיב כפרמטר לבלוק.

ShippingAddress

שיטות Script המשתמשות באובייקט ShippingAddress
שיטה	סוג החזרה	תיאור
.name	מחרוזת	מחזיר את שם האדם המשויך לכתובת לשילוח.
.address1	מחרוזת	מחזיר את חלק כתובת הרחוב מתוך הכתובת לשילוח.
.address2	מחרוזת	מחזיר את שדה הרשות הנוסף של חלק כתובת הרחוב מתוך הכתובת לשילוח.
.phone	מחרוזת	מחזיר את מספר הטלפון של הכתובת לשילוח.
.city	מחרוזת	מחזיר את העיר של הכתובת לשילוח.
.zip	מחרוזת	מחזיר את המיקוד של הכתובת לשילוח.
.province	מחרוזת	מחזיר את המחוז/המדינה של הכתובת לשילוח.
.province_code	מחרוזת	מחזיר את הערך המקוצר של המחוז/המדינה של הכתובת לשילוח.
.country_code	מחרוזת	מחזיר את הערך המקוצר של המדינה של הכתובת לשילוח.

Money

שיטות Script המשתמשות באובייקט Money
שיטה	סוג החזרה	תיאור
.derived_from_presentment(customer_cents:X)	Money	ממיר סכום (בסנטים) מהמטבע המקומי של הלקוח (המטבע המוצג) למטבע של החנות שלך. שיטה זו מקבלת את הפרמטר `customer_cents`, שמקבל מספר בסנטים. לדוגמה, `Money.derived_from_presentment(customer_cents: 500)`.
.new	Money	יוצר אובייקט חדש המייצג מחיר.
.zero	Money	יוצר אובייקט חדש עם מחיר אפס.
+	Money	מחבר שני אובייקטי `Money`.
-	Money	מחסר אובייקט `Money` אחד מאחר.
*	Money	מכפיל אובייקט `Money` במספר.

דוגמאות ל-Money

Money.new(cents: 1000)

יוצר אובייקט Money המייצג 1000 סנט, או $10.

Money.new(cents: 100) * 50

יוצר אובייקט Money המייצג $1, ולאחר מכן מכפיל את הסכום הזה ב-50. מחזיר אובייקט Money המייצג $50.

גרסה

שיטות סקריפט שמשתמשות באובייקט Variant
שיטה	סוג החזרה	תיאור
.id	Integer	מחזיר את מספר המזהה (ID) של הגרסה.
.price	Money	מחזיר את המחיר ליחידה של הגרסה.
.product	Product	מחזיר את המוצר המשויך לגרסה.
.skus	List<String>	מחזיר את המק"טים (SKU) של הגרסה, שלרוב משמשים למעקב אחר המלאי.
.title	מחרוזת	מחזיר את הכותרת של הגרסה.

מוצר

שיטות סקריפט שמשתמשות באובייקט Product
שיטה	סוג החזרה	תיאור
.id	Integer	מחזיר את מספר המזהה של המוצר.
.gift_card?	בוליאני	מחזיר האם המוצר הוא כרטיס מתנה.
.tags	List<Tag>	מחזיר רשימה של מחרוזות המייצגות את התגים שהוגדרו עבור מוצר זה.
.product_type	מחרוזת	סיווג שניתן לתייג איתו מוצר, משמש לרוב לסינון ולחיפוש.
.vendor	מחרוזת	מחזיר את הספק של מוצר זה.

Kernel

Kernel הוא מודול ב-Ruby שנכלל בכל מחלקה. כתוצאה מכך, השיטות שלו זמינות לכל אובייקט. שיטות אלו פועלות באותו אופן שבו פועלות פונקציות גלובליות בשפות אחרות.

שיטות סקריפט שמשתמשות באובייקט Kernel
שיטה	סוג החזרה	תיאור
.exit	ללא	מסיים את ביצוע הסקריפט הנוכחי ללא שגיאה. אם פעולה זו מופעלת לפני שמוקצה משהו ל-`Output.cart`, לסקריפט לא תהיה כל השפעה. זוהי דרך שימושית לצאת מסקריפטים, לדוגמה, אם הלקוח לא זכאי להפעיל את הסקריפט.

דוגמה ל-Kernel

customer = Input.cart.customer
if customer && customer.email.end_with?("@mycompany.com")
  # Employees are not eligible for this promotion.
  exit
end

שיטות של פריט שורה

השיטות הבאות ניתנות לשימוש רק בסקריפטים של פריטי שורה:

Cart

שיטות סקריפט שמשתמשות באובייקט Cart בסקריפטים של פריטי שורה
שיטה	סוג החזרה	תיאור
.subtotal_price_was	Money	מחזיר את סכום הביניים של הסל לפני שהוחלו עליו הנחות כלשהן.
.subtotal_price_changed?	בוליאני	מחזיר האם סכום הביניים השתנה.

LineItem

שיטות סקריפט שמשתמשות באובייקט LineItem בסקריפטים של פריטי שורה
שיטה	סוג החזרה	תיאור
.change_line_price(Money new_price, { message: String })	Money	משנה את המחיר של פריט השורה לסכום שצוין. נדרשת `message`. `new_price` חייב להיות נמוך מהמחיר הנוכחי.
.original_line_price	Money	מחזיר את המחיר המקורי של פריט השורה לפני החלת סקריפטים והנחות.
.line_price_was	Money	מחזיר את המחיר של פריט השורה לפני שהוחלו עליו שינויים על-ידי הסקריפט הנוכחי.
.line_price_changed?	בוליאני	מחזיר האם המחיר של פריט השורה השתנה.
.change_properties(hash new_properties, { message: String })	hash	מגדיר מאפיינים חדשים לפריט שורה. ה-hash של המאפיינים המקוריים מאוחסן ב-`properties_was` וה-hash של המאפיינים שמועבר לשיטה הופך למאפיינים החדשים של פריט השורה.
.properties_was	hash	מחזיר את ה-hash של המאפיינים המקוריים של פריט השורה לפני שהוחלו שינויים כלשהם.
.properties_changed?	בוליאני	מחזיר האם המאפיינים של פריט השורה השתנו.
.split({ take: Integer })	LineItem	מפצל פריט שורה לשני פריטי שורה. `take` מציין איזו כמות יש להסיר מפריט השורה המקורי כדי ליצור את פריט השורה החדש.

דוגמה ל-.split

סקריפט דוגמה זה מפצל פריט שורה בשם original_line_item לשני פריטי שורה. לפריט השורה החדש יש כמות של 1 (מצוין על-ידי take: 1). לאחר מכן, הסקריפט מחיל מחיר מוזל על פריט השורה החדש עם ההודעה "Third hat for 5 dollars".

if original_line_item.quantity >= 3
  new_line_item = original_line_item.split(take: 1)
  new_line_item.change_line_price(Money.new(cents: 500), message: "Third hat for 5 dollars")
  cart.line_items << new_line_item
end

גרסה

שיטות סקריפט שמשתמשות באובייקט Variant בסקריפטים של פריטי שורה
שיטה	סוג החזרה	תיאור
.compare_at_price	Money	מחזיר את מחיר ההשוואה של הגרסה. מחזיר `nil` אם לגרסה אין מחיר השוואה.

שיטות שילוח

השיטות הבאות ניתנות לשימוש בסקריפטים של שילוח:

קלט

שיטות סקריפט שמשתמשות באובייקט Input בסקריפטים של שילוח
שיטה	סוג החזרה	תיאור
.shipping_rates	ShippingRateList	מחזיר רשימה של כל תעריפי השילוח.

ShippingRateList

שיטות סקריפט שמשתמשות באובייקט ShippingRateList בסקריפטים של שילוח
שיטה	סוג החזרה	תיאור
.delete_if	ShippingRateList	מחיקת תעריפי שילוח באמצעות בלוק קוד אופציונלי. ראו את התיעוד של שיטת ה-`delete_if` של Ruby.
.sort!	ShippingRateList	מיון תעריפי השילוח באמצעות אופרטור ההשוואה או באמצעות בלוק קוד אופציונלי. ראו את התיעוד של שיטת ה-`sort!` של Ruby.
.sort_by!	ShippingRateList	מיון תעריפי השילוח באמצעות בלוק קוד אופציונלי. ראו את התיעוד של שיטת ה-`sort_by!` של Ruby.

ShippingRate

שיטות סקריפט המשתמשות באובייקט ShippingRate בסקריפטים של שילוח
שיטה	סוג החזרה	תיאור
.code	מחרוזת	מחזירה את הקוד של תעריף השילוח.
.markup	Money	מחזירה את הייקור של תעריף שילוח, אם רלוונטי.
.name	מחרוזת	מחזירה את השם של תעריף השילוח. ניתן לשנות אותו באמצעות השיטה `change_name`.
.price	Money	מחזירה את המחיר של תעריף השילוח.
.source	מחרוזת	מחזירה את המקור (חברת השילוח) המשויך לתעריף השילוח, אם רלוונטי. לא ניתן לשנות אותו.
.change_name(String new_name)	מחרוזת	משנה את השם (עד 255 תווים) של תעריף השילוח. לא ניתן לשנות, למחוק או להסתיר את המקור.
.apply_discount(Money discount, { message: String })	Money	מחילה הנחה בסכום הקבוע שצוין. לא ניתן להפחית את המחיר אל מתחת ל-0. חובה לצרף הודעה.
.phone_required?	בוליאני	מחזירה `true` אם נדרש מספר טלפון כדי לקבל את תעריף השילוח, או `false` אם לא נדרש מספר טלפון.

שיטות תשלום

ניתן להשתמש בשיטות הבאות בסקריפטים של תשלום:

קלט

שיטות סקריפט המשתמשות באובייקט Input בסקריפטים של תשלום
שיטה	סוג החזרה	תיאור
.payment_gateways	PaymentGatewaysList	מחזירה רשימה של כל שערי התשלום בחנות.

PaymentGatewayList

שיטות סקריפט המשתמשות באובייקט PaymentGatewayList בסקריפטים של תשלום
שיטה	סוג החזרה	תיאור
.delete_if	PaymentGatewayList	מחיקת שערי תשלום באמצעות בלוק קוד אופציונלי. ראו את התיעוד של שיטת ה-`delete_if` של Ruby.
.sort!	PaymentGatewayList	מיון שערי התשלום באמצעות אופרטור ההשוואה או באמצעות בלוק קוד אופציונלי. ראו את התיעוד של שיטת ה-`sort!` של Ruby.
.sort_by!	PaymentGatewayList	מיון שערי התשלום באמצעות בלוק קוד אופציונלי. ראו את התיעוד של שיטת ה-`sort_by!` של Ruby.

PaymentGateway

שיטה	סוג החזרה	תיאור
.name	מחרוזת	מחזירה את השם של שער התשלום.
.enabled_card_brands	List<String>	אם שער התשלום תומך בכרטיסי אשראי, מחזירה רשימה של סוגי כרטיסי האשראי שהחנות מקבלת. אם השער אינו תומך בכרטיסי אשראי, מחזירה רשימה ריקה.
.change_name(String new_name)	מחרוזת	משנה את השם של שער התשלום. לא ניתן לשנות שם של שערי תשלום עם לוגו.

דוגמאות

בדוגמה הבאה של סקריפט פריטי שורה, כאשר לקוח מזמין מוצר שאינו כרטיס מתנה, המחיר של המוצר מופחת ב-$9. בנוסף, מוצג הסכום הכולל שהלקוח הוציא במהלך כל הביקורים שלו בחנות:

customer = Input.cart.customer
Input.cart.line_items.each do |line_item|
  product = line_item.variant.product
  next if product.gift_card?
  line_item.change_line_price(line_item.line_price - Money.new(cents: 900), message: customer.total_spent)
end

Output.cart = Input.cart

למידע נוסף

למידע נוסף על: