مرجع واجهة برمجة التطبيقات (API) لـ Shopify Scripts

تُكتب البرامج النصية باستخدام واجهة برمجة التطبيقات (API) لـ Ruby والتي تمنحك قدرًا كبيرًا من التحكم والمرونة.

هناك أنواع مختلفة للبرامج النصية. يُخصّص نوع للبرنامج النصي عند إنشائه في تطبيق Script Editor، بناءً على قالب البرنامج النصي الذي تختار البدء به:

البرامج النصية للبنود

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

البرامج النصية للبنود التي تطبق خصماً على الاشتراك تسري فقط على الدفعة الأولى من الاشتراك. لا يطبق البرنامج النصي أي خصم على الدفعات اللاحقة.

بعض الطرق لا يمكن استخدامها إلا في البرامج النصية للبنود.

البرامج النصية للشحن

تتفاعل البرامج النصية للشحن مع الشحن، ويمكنها تغيير طرق الشحن ومنح خصومات على أسعار الشحن. يتم تشغيل هذه البرامج النصية عندما تصل عملية الدفع إلى صفحة خيارات الشحن.

البرامج النصية للشحن التي تطبق خصماً على سعر شحن الاشتراك تسري فقط على الدفعة الأولى من الاشتراك. لا يطبق البرنامج النصي أي خصم على الدفعات اللاحقة.

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

البرامج النصية للدفع

تتفاعل البرامج النصية للدفع مع المدفوعات، ويمكنها إعادة تسمية بوابات الدفع وإخفائها وإعادة ترتيبها. لاحظ أن البرامج النصية للدفع لا تتفاعل مع بوابات الدفع التي تظهر قبل شاشة الدفع، مثل Apple Pay. يتم تشغيل هذه البرامج النصية عندما تصل عملية الدفع إلى صفحة الدفع.

بعض الطرق لا يمكن استخدامها إلا في البرامج النصية للدفع.

في هذه الصفحة

الطرق العامة

يمكن استخدام الطرق التالية في أي نوع من البرامج النصية:

الإدخال

طرق إدخال البرنامج النصي
الطريقة	نوع الإرجاع	الوصف
.cart	سلة التسوق	تُرجع كائن سلة تسوق قابل للتغيير.
.locale	سلسلة نصية	تُرجع الإعدادات المحلية للعميل. على سبيل المثال، `en`، أو `fr`، أو `pt-BR`.

سلة التسوق

يتوفر كائن سلة التسوق فقط في المتجر الإلكتروني. تمتلك بعض عمليات الدفع المتروكة صلاحية الوصول إلى كائن سلة التسوق. مع ذلك، إذا أُغلقت عملية الدفع ثم زار العميل عملية الدفع المتروكة، فسيتم توجيهه إلى صفحة الدفع المعبأة مسبقاً ولن يعود كائن سلة التسوق موجوداً. يرجع ذلك إلى تخطي واجهة المتجر عبر رسالة إلكترونية لعملية الدفع المتروكة.

طرق البرنامج النصي التي تستخدم كائن سلة التسوق
الطريقة	نوع الإرجاع	الوصف
.customer	العميل	تُرجع مالك سلة التسوق (إن وُجد).
.shipping_address	عنوان الشحن	تُرجع عنوان الشحن لمالك سلة التسوق (إن وُجد).
.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	مبلغ مالي	تُرجع المبلغ المالي للخصم.
.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?	قيمة منطقية	تُرجع ما إذا كان قد تم رفض رمز الخصم.

العميل

طرق البرنامج النصي التي تستخدم كائن العميل
الطريقة	نوع الإرجاع	الوصف
.id	عدد صحيح	يُرجع رقم معرّف العميل.
.email	سلسلة نصية	يُرجع عنوان البريد الإلكتروني للعميل.
.tags	List<Tag>	يُرجع قائمة بسلاسل نصية تمثل أي علامات تم تعيينها للعميل.
.orders_count	عدد صحيح	يُرجع إجمالي عدد الطلبات التي قدمها العميل.
.total_spent	مبلغ مالي	يُرجع إجمالي المبلغ الذي أنفقه العميل على جميع الطلبات.
.accepts_marketing?	قيمة منطقية	يُرجع ما إذا كان العميل يقبل التسويق.

LineItem

طرق البرنامج النصي التي تستخدم كائن LineItem
الطريقة	نوع الإرجاع	الوصف
.grams	جرامات	يُرجع إجمالي وزن عنصر السطر.
.line_price	مبلغ مالي	سعر عنصر السطر.
.discounted?	قيمة منطقية	يُرجع ما إذا كان قد تم خصم سعر عنصر السطر بواسطة برنامج نصي أو خصم مطبّق يدويًا. لا يؤثر استخدام أكواد الخصم على القيمة المُرجعة.
.properties	تجزئة	يُرجع الخصائص التي تم تحديدها لعنصر السطر هذا.
.variant	متغير	يُرجع متغير المنتج المحدد الذي يمثله عنصر السطر.
.quantity	عدد صحيح	يُرجع كمية عنصر السطر هذا.
.selling_plan_id	عدد صحيح	يُرجع معرّف خطة البيع لعنصر السطر. تُعد هذه الطريقة مفيدة عندما يبيع المتجر اشتراكات وتريد أن يكتشف البرنامج النصي متى يتم بيع متغير منتج كاشتراك.

List

طرق البرنامج النصي التي تستخدم كائن 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

طرق البرنامج النصي التي تستخدم كائن ShippingAddress
الطريقة	نوع الإرجاع	الوصف
.name	سلسلة نصية	يُرجع اسم الشخص المرتبط بعنوان الشحن.
.address1	سلسلة نصية	يُرجع جزء عنوان الشارع من عنوان الشحن.
.address2	سلسلة نصية	يُرجع الحقل الإضافي الاختياري لجزء عنوان الشارع من عنوان الشحن.
.phone	سلسلة نصية	يُرجع رقم هاتف عنوان الشحن.
.city	سلسلة نصية	يُرجع مدينة عنوان الشحن.
.zip	سلسلة نصية	يُرجع الرمز البريدي لعنوان الشحن.
.province	سلسلة نصية	يُرجع المقاطعة/الولاية لعنوان الشحن.
.province_code	سلسلة نصية	يُرجع القيمة المختصرة للمقاطعة/الولاية لعنوان الشحن.
.country_code	سلسلة نصية	يُرجع القيمة المختصرة لبلد عنوان الشحن.

Money

طرق البرنامج النصي التي تستخدم كائن Money
الطريقة	نوع الإرجاع	الوصف
.derived_from_presentment(customer_cents:X)	مبلغ مالي	يُحوّل مبلغًا (بالسنتات) من العملة المحلية للعميل (عملة العرض) إلى عملة متجرك. تقبل هذه الطريقة المعلمة `customer_cents`، والتي تقبل رقمًا بالسنتات. على سبيل المثال، `Money.derived_from_presentment(customer_cents: 500)`.
.new	مبلغ مالي	يُنشئ كائنًا جديدًا لتمثيل السعر.
.zero	مبلغ مالي	ينشئ كائنًا جديدًا بسعر صفر.
+	مبلغ مالي	يجمع كائني `Money`.
-	مبلغ مالي	يطرح كائن `Money` من كائن آخر.
*	مبلغ مالي	يضرب كائن `Money` في رقم.

أمثلة على Money

Money.new(cents: 1000)

ينشئ كائن Money يمثل 1000 سنت، أو 10 دولارات.

Money.new(cents: 100) * 50

ينشئ كائن Money يمثل دولارًا واحدًا، ثم يضرب هذا المبلغ في 50. ويُرجع كائن Money يمثل 50 دولارًا.

المتغير (Variant)

أساليب البرنامج النصي التي تستخدم كائن Variant
الطريقة	نوع الإرجاع	الوصف
.id	عدد صحيح	يُرجع رقم مُعرّف المتغير.
.price	مبلغ مالي	يُرجع سعر الوحدة للمتغير.
.product	Product	يُرجع المنتج المرتبط بالمتغير.
.skus	List<String>	يُرجع وحدات الاحتفاظ بالمخزون (SKUs) للمتغير، والتي تُستخدم غالبًا لتتبع المخزون.
.title	سلسلة نصية	يُرجع عنوان المتغير.

المنتج (Product)

أساليب البرنامج النصي التي تستخدم كائن Product
الطريقة	نوع الإرجاع	الوصف
.id	عدد صحيح	يُرجع رقم مُعرّف المنتج.
.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 في البرامج النصية للبنود
الطريقة	نوع الإرجاع	الوصف
.subtotal_price_was	مبلغ مالي	يُرجع سعر المجموع الفرعي لسلة التسوق قبل تطبيق أي خصومات.
.subtotal_price_changed?	قيمة منطقية	يُرجع ما إذا كان سعر المجموع الفرعي قد تغيّر.

LineItem

أساليب البرنامج النصي التي تستخدم كائن LineItem في البرامج النصية للبنود
الطريقة	نوع الإرجاع	الوصف
.change_line_price(Money new_price, { message: String })	مبلغ مالي	يغيّر سعر البند إلى المبلغ المحدَّد. ويُشترط وجود رسالة `message`. كما يجب أن يكون السعر الجديد `new_price` أقل من السعر الحالي.
.original_line_price	مبلغ مالي	يُرجع السعر الأصلي للبند قبل تطبيق البرامج النصية والخصومات.
.line_price_was	مبلغ مالي	يُرجع سعر البند قبل تطبيق التغييرات بواسطة البرنامج النصي الحالي.
.line_price_changed?	قيمة منطقية	يُرجع ما إذا كان سعر البند قد تغيّر.
.change_properties(hash new_properties, { message: String })	تجزئة	يعيِّن خصائص جديدة للبند. يتم تخزين تجزئة الخصائص الأصلية في `properties_was` وتصبح تجزئة الخصائص التي يتم تمريرها إلى الأسلوب هي الخصائص الجديدة للبند.
.properties_was	تجزئة	يُرجع تجزئة الخصائص الأصلية للبند قبل تطبيق أي تغييرات.
.properties_changed?	قيمة منطقية	يُرجع ما إذا كانت خصائص البند قد تغيّرت.
.split({ take: Integer })	LineItem	يقسّم بندًا إلى بندين. يحدد `take` الكمية التي يجب إزالتها من البند الأصلي لإنشاء البند الجديد.

مثال على .split

يقسّم هذا البرنامج النصي كمثال بندًا يُسمى original_line_item إلى بندين. يحتوي البند الجديد على كمية مقدارها 1 (محددة بواسطة take: 1). ويطبّق البرنامج النصي بعد ذلك سعرًا مخفَّضًا على البند الجديد مع الرسالة "قبعة ثالثة مقابل 5 دولارات".

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)

أساليب البرنامج النصي التي تستخدم كائن Variant في البرامج النصية للبنود
الطريقة	نوع الإرجاع	الوصف
.compare_at_price	مبلغ مالي	يُرجع السعر المقارن للمتغير. ويُرجع `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	مبلغ مالي	تُرجع الزيادة في سعر الشحن، إن وُجدت.
.name	سلسلة نصية	تُرجع اسم سعر الشحن. ويمكن تعديله باستخدام طريقة `change_name`.
.price	مبلغ مالي	تُرجع سعر الشحن.
.source	سلسلة نصية	تُرجع المصدر (شركة النقل) المرتبط بسعر الشحن، إن وُجد. ولا يمكن تعديله.
.change_name(String new_name)	سلسلة نصية	تُغيّر اسم سعر الشحن (بحد أقصى 255 حرفًا). لا يمكن تغيير المصدر أو حذفه أو إخفاؤه.
.apply_discount(Money discount, { message: String })	مبلغ مالي	تطبق خصمًا بالمبلغ الثابت المُحدد. لا يمكن تقليل السعر إلى ما دون الصفر. يُشترط وجود رسالة.
.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

معرفة المزيد

معرفة المزيد حول: