Informacje dotyczące interfejsu API Shopify Scripts

Skrypty są pisane przy użyciu interfejsu API Ruby, który zapewnia dużą kontrolę i elastyczność.

Istnieją różne typy skryptów. Typ przypisuje się do skryptu podczas tworzenia skryptu w aplikacji Script Editor na podstawie wybranego szablonu skryptu:

Skrypty pozycji pojedynczych

Skrypty pozycji pojedynczych wpływają na pozycje w koszyku i mogą zmieniać ceny oraz przyznawać rabaty. Skrypty te są uruchamiane po dokonaniu zmiany w koszyku.

Skrypty pozycji pojedynczych obniżające opłatę subskrypcyjną mają zastosowanie tylko do pierwszej płatności za subskrypcję. Kolejne płatności za subskrypcję nie są obniżane przez skrypt.

Niektóre metody mogą być stosowane tylko w skryptach pozycji liniowych.

Skrypty wysyłki

Skrypty wysyłki współdziałają z wysyłką i mogą zmieniać metody wysyłki oraz przyznawać rabaty na stawki wysyłki. Skrypty te są uruchamiane po przejściu na stronę opcji wysyłki podczas realizacji zakupu.

Skrypty pozycji obniżające stawkę wysyłki subskrypcji mają zastosowanie tylko do pierwszej płatności za subskrypcję. Kolejne płatności nie są obniżane przez skrypt.

Niektóre metody mogą być stosowane tylko w skryptach wysyłki.

Skrypty płatności

Skrypty płatności współdziałają z płatnościami i mogą zmieniać nazwy, ukrywać i zmieniać kolejność bramek płatniczych Należy pamiętać, że skrypty płatności nie działają z bramkami płatniczymi wyświetlanymi przed ekranem realizacji zakupu, takimi jak Apple Pay. Takie skrypty są uruchamiane po przejściu na stronę płatności podczas realizacji zakupu.

Niektóre metody mogą być stosowane tylko w skryptach płatności.

Na tej stronie

Metody ogólne

Poniższe metody można stosować w każdym typie skryptu:

Dane wejściowe

Metody skryptu wykorzystujące dane wejściowe
Metoda	Typ zwrotu	Opis
.cart	Koszyk	Zwraca modyfikowalny obiekt Koszyk.
.locale	ciąg znaków	Zwraca ustawienia regionalne klienta. Na przykład `en`, `fr` lub `pt-BR`.

Koszyk

Obiekt Koszyk jest dostępny tylko w sklepie online. Dostęp do obiektu Koszyk jest możliwy w przypadku niektórych przerwanych realizacji zakupu. Jeśli jednak strona realizacji zakupu została zamknięta, klient próbujący wyświetlić stronę przerwanej realizacji zakupu zostaje przekierowany na wstępnie wypełnioną stronę realizacji zakupu, a obiekt Koszyk już nie istnieje. Jest to spowodowane pominięciem witryny sklepu przez e-mail dotyczący przerwanej realizacji zakupu.

Metody skryptu wykorzystujące obiekt Koszyk
Metoda	Typ zwrotu	Opis
.customer	Klient	Zwraca właściciela koszyka (jeśli istnieje).
.shipping_address	ShippingAddress	Zwraca adres wysyłki właściciela koszyka (jeśli istnieje).
.discount_code	różny	Zwroty: `nil`, jeśli koszyk nie ma kodu rabatowego `CartDiscount::FixedAmount`, jeśli koszyk ma stałą kwotę rabatu `CartDiscount::Percentage`, jeśli koszyk ma rabat procentowy `CartDiscount::Shipping`, jeśli koszyk ma rabat na wysyłkę Zwraca jeden kod rabatowy (zob. ograniczenia) `discount_code` jest obecny, jeśli do koszyka zastosowano rabat. Nie musi to oznaczać zmiany ceny koszyka. Na przykład, jeśli rabat dotyczy koszyków o wartości powyżej 50 zł, a skrypt obniża cenę koszyka poniżej 50 zł, `discount_code` istnieje nadal, ale cena koszyka się nie zmienia. Zobacz przykład `discount_code`.
.line_items	List<LineItem>	Zwraca listę zawierającą pozycje pojedyncze w koszyku.
.presentment_currency	List<String>	Zwraca walutę lokalną (wyświetlaną) klienta (w formacie ISO 4217). Na przykład USD.
.subtotal_price	Pieniądze	Zwraca sumę częściową ceny koszyka po zastosowaniu rabatów dla pozycji pojedynczych, ale przed zastosowaniem kodów rabatowych.
.total_weight	gramy	Zwraca całkowitą wagę wszystkich pozycji pojedynczych w koszyku.

CartDiscount::FixedAmount

Metody skryptu wykorzystujące obiekt CartDiscount::FixedAmount
Metoda	Typ zwrotu	Opis
.code	Ciąg znaków	Zwraca kod rabatowy użyty do zastosowania rabatu.
.amount	Pieniądze	Zwraca kwotę rabatu.
.reject({ message: String })	Zero	Odrzuca kod rabatowy zastosowany do koszyka. Wymagana jest wiadomość `message`.
.rejected?	Wartość logiczna	Wskazuje, czy kod rabatowy został odrzucony.

CartDiscount::Percentage

Metody skryptu wykorzystujące obiekt CartDiscount::Percentage
Metoda	Typ zwrotu	Opis
.code	Ciąg znaków	Zwraca kod rabatowy użyty do zastosowania rabatu.
.percentage	Ułamek dziesiętny	Zwraca kwotę procentową rabatu.
.reject({ message: String })	Zero	Odrzuca kod rabatowy zastosowany do koszyka. Wymagana jest wiadomość `message`.
.rejected?	Wartość logiczna	Wskazuje, czy kod rabatowy został odrzucony.

CartDiscount::Shipping

Metody skryptu wykorzystujące obiekt CartDiscount::Shipping
Metoda	Typ zwrotu	Opis
.code	Ciąg znaków	Zwraca kod rabatowy użyty do zastosowania rabatu.
.reject({ message: String })	Zero	Odrzuca kod rabatowy zastosowany do koszyka. Wymagana jest wiadomość `message`.
.rejected?	Wartość logiczna	Wskazuje, czy kod rabatowy został odrzucony.

Klient

Metody skryptu wykorzystujące obiekt Klient
Metoda	Typ zwrotu	Opis
.id	Liczba całkowita	Zwraca numer identyfikacyjny klienta.
.email	Ciąg znaków	Zwraca adres e-mail klienta.
.tags	List<Tag>	Zwraca listę ciągów znaków reprezentujących wszystkie tagi ustawione dla klienta.
.orders_count	Liczba całkowita	Zwraca całkowitą liczbę zamówień złożonych przez klienta.
.total_spent	Pieniądze	Zwraca całkowitą kwotę wydaną przez klienta na wszystkie zamówienia.
.accepts_marketing?	Wartość logiczna	Określa, czy klient wyraża zgodę na marketing.

LineItem

<tdgramy

Metody skryptu wykorzystujące obiekt LineItem
Metoda	Typ zwrotu	Opis
.grams	Zwraca całkowitą wagę pozycji pojedynczej.
.line_price	Pieniądze	Cena pozycji pojedynczej
.discounted?	Wartość logiczna	Zwraca informację, czy cena pozycji została obniżona przez skrypt czy ręcznie zastosowany rabat. Użycie kodów rabatowych nie wpływa na zwracaną wartość.
.properties	hash	Zwraca właściwości, które zostały określone dla tej pozycji pojedynczej
.variant	Wariant	Zwraca określony wariant produktu reprezentowany przez pozycję pojedynczą.
.quantity	Liczba całkowita	Zwraca ilość tej pozycji pojedynczej.
.selling_plan_id	Liczba całkowita	Zwraca identyfikator planu sprzedaży dla pozycji. Ta metoda jest przydatna, gdy sklep sprzedaje subskrypcje i chcesz, aby skrypt wykrył, kiedy wariant produktu jest sprzedawany w ramach subskrypcji.

Lista

Metody skryptu wykorzystujące obiekt Lista
Metoda	Typ zwrotu	Opis
.new	Lista	Tworzy nowy obiekt do reprezentowania listy.
.[]	Element lub brak	Zwraca element pod określonym indeksem.
.&	Lista	Zwraca nową listę zawierającą elementy wspólne dla dwóch list, bez duplikatów.
.delete_if	Lista	Usuwanie elementów za pomocą opcjonalnego bloku kodu. Zapoznaj się z dokumentacją metody języka Ruby `delete_if`.
.empty?	Wartość logiczna	Zwraca wartość `true`, jeśli lista nie zawiera żadnych elementów.
.first	Element lub brak	Zwraca pierwszy element lub `nil`, jeśli lista jest pusta.
.index(*args, &block)	int lub nil	Zwraca indeks pierwszego elementu listy. Jeśli zamiast argumentu zostanie podany blok, zwraca indeks pierwszego elementu, dla którego blok ma wartość PRAWDA.
.rindex(*args, &block)	int lub nil	Zwraca indeks ostatniego elementu listy. Jeśli zamiast argumentu zostanie podany blok, zwraca indeks pierwszego elementu, dla którego blok ma wartość PRAWDA.
.last	Element lub brak	Zwraca ostatni element lub `nil`, jeśli lista jest pusta.
.length	int	Zwraca liczbę elementów na liście.
.size	int	Alias dla długości.
.each(*args, &block)	Lista	Wywołuje blok jednorazowo dla każdego elementu na liście, przekazując element jako parametr do bloku.

ShippingAddress

Metody skryptu wykorzystujące obiekt ShippingAddress
Metoda	Typ zwrotu	Opis
.name	ciąg znaków	Zwraca nazwisko osoby powiązanej z adresem wysyłki.
.address1	ciąg znaków	Zwraca część adresu ulicy z adresu wysyłki.
.address2	ciąg znaków	Zwraca opcjonalne dodatkowe pole części adresu ulicy z adresu wysyłki.
.phone	ciąg znaków	Zwraca numer telefonu z adresu wysyłki.
.city	ciąg znaków	Zwraca miasto z adresu wysyłki.
.zip	ciąg znaków	Zwraca kod pocztowy z adresu wysyłki.
.province	ciąg znaków	Zwraca województwo/prowincję/stan z adresu wysyłki.
.province_code	ciąg znaków	Zwraca skróconą wartość województwa/prowincji/stanu z adresu wysyłki.
.country_code	ciąg znaków	Zwraca skróconą wartość kraju z adresu wysyłki.

Pieniądze

Metody skryptu wykorzystujące obiekt Pieniądze
Metoda	Typ zwrotu	Opis
.derived_from_presentment(customer_cents:X)	Pieniądze	Konwertuje kwotę (w centach) z lokalnej (wyświetlanej) waluty klienta na walutę sklepu. W tej metodzie przyjmowany jest parametr `customer_cents`, który przyjmuje liczbę w centach. Na przykład `Money.derived_from_presentment(customer_cents: 500)`.
.new	Pieniądze	Tworzy nowy obiekt reprezentujący cenę.
.zero	Pieniądze	Tworzy nowy obiekt z ceną wynoszącą zero.
+	Pieniądze	Dodaje dwa obiekty `Pieniądze`.
-	Pieniądze	Odejmuje jeden obiekt `Pieniądze` od innego.
*	Pieniądze	Mnoży obiekt `Pieniądze` przez liczbę.

Przykłady obiektów Money

Money.new(cents: 1000)

Tworzy obiekt Money reprezentujący 1000 centów lub 10 USD.

Money.new(cents: 100) * 50

Tworzy obiekt Money reprezentujący 1 USD, a następnie mnoży tę kwotę przez 50. Zwraca obiekt Money reprezentujący 50 USD.

Variant

Metody skryptu wykorzystujące obiekt Wariant
Metoda	Typ zwrotu	Opis
.id	Liczba całkowita	Zwraca numer identyfikacyjny wariantu.
.price	Pieniądze	Zwraca cenę jednostkową wariantu.
.product	Produkt	Zwraca powiązany produkt wariantu.
.skus	List<String>	Zwraca jednostki magazynowania (SKU) wariantu, które są często używane do śledzenia zapasów.
.title	Ciąg znaków	Zwraca tytuł wariantu.

Produkt

Metody skryptu wykorzystujące obiekt Produkt
Metoda	Typ zwrotu	Opis
.id	Liczba całkowita	Zwraca numer identyfikacyjny produktu.
.gift_card?	Wartość logiczna	Wskazuje, czy produkt jest kartą prezentową.
.tags	List<Tag>	Zwraca listę ciągów znaków reprezentujących tagi ustawione dla tego produktu.
.product_type	Ciąg znaków	Kategoryzacja, za pomocą której produkt można oznaczyć produkt, używana często do filtrowania i wyszukiwania.
.vendor	Ciąg znaków	Zwraca dostawcę tego produktu.

Kernel

Kernel to moduł Ruby, który jest zawarty w każdej klasie. W rezultacie jego metody są dostępne dla każdego obiektu. Metody te działają w taki sam sposób, jak funkcje globalne w innych językach.

Metody skryptu wykorzystujące obiekt Kernel
Metoda	Typ zwrotu	Opis
.exit	none	Kończy wykonywanie bieżącego skryptu bez błędów. W przypadku uruchomienia zanim cokolwiek zostanie przypisane do `Output.cart`, skrypt nie przyniesie żadnego efektu. Jest to przydatna metoda wyjścia ze skryptów, jeśli klient nie jest uprawniony do uruchomienia skryptu.

Przykład obiektu Kernel

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

Metody pozycji pojedynczych

Poniższe metody są używane tylko w skryptach pozycji pojedynczych:

Koszyk

Metody skryptu wykorzystujące obiekt Koszyk w skryptach pozycji pojedynczych
Metoda	Typ zwrotu	Opis
.subtotal_price_was	Pieniądze	Zwraca sumę częściową koszyka przed zastosowaniem rabatów.
.subtotal_price_changed?	Wartość logiczna	Określa, czy zmieniła się cena cząstkowa.

LineItem

Metody skryptu wykorzystujące obiekt LineItem w skryptach pozycji pojedynczych
Metoda	Typ zwrotu	Opis
.change_line_price(Pieniądze new_price, { message: String })	Pieniądze	Zmienia cenę pozycji pojedynczej na określoną kwotę. Wymagana jest wiadomość `message`. Nowa cena `new_price` musi być niższa od bieżącej.
.original_line_price	Pieniądze	Zwraca oryginalną cenę pozycji pojedynczej przed zastosowaniem skryptów i rabatów.
.line_price_was	Pieniądze	Zwraca cenę pozycji pojedynczej przed zastosowaniem zmian przez bieżący skrypt.
.line_price_changed?	Wartość logiczna	Określa, czy cena pozycji pojedynczej uległa zmianie.
.change_properties(hash new_properties, { message: String })	hash	Ustawia nowe właściwości pozycji pojedynczej. Skrót właściwości oryginalnych jest przechowywany w `properties_was`, a skrót właściwości przekazany do metody staje się nowymi właściwościami pozycji pojedynczej.
.properties_was	hash	Zwraca skrót oryginalnych właściwości pozycji pojedynczej przed zastosowaniem zmian.
.properties_changed?	Wartość logiczna	Określa, czy właściwości pozycji pojedynczej uległy zmianie.
.split({ take: Integer })	LineItem	Dzieli pozycję pojedynczą na dwie pozycje. `take` określa, jaką ilość należy usunąć z oryginalnej pozycji pojedynczej, aby utworzyć nową pozycję.

Przykładowy .split

Ten przykładowy skrypt dzieli pozycję pojedynczą o nazwie original_line_item na dwie pozycje. Nowa pozycja pojedyncza ma ilość 1 (określoną przez take: 1). Następnie skrypt stosuje obniżoną cenę do nowej pozycji pojedynczej z wiadomością: „Trzeci kapelusz za 5 dolarów”.

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

Wariant

Metody skryptu wykorzystujące obiekt Wariant w skryptach pozycji pojedynczych
Metoda	Typ zwrotu	Opis
.compare_at_price	Pieniądze	Zwraca cenę do porównania wariantu. Zwraca `nil`, jeśli wariant nie ma ceny do porównania.

Metody wysyłki

Poniższe metody są używane w skryptach wysyłki:

Dane wejściowe

Metody skryptu wykorzystujące obiekt Dane wejściowe w skryptach wysyłki
Metoda	Typ zwrotu	Opis
.shipping_rates	ShippingRateList	Zwraca listę wszystkich stawek wysyłki.

ShippingRateList

Metody skryptu wykorzystujące obiekt ShippingRateList w skryptach wysyłki
Metoda	Typ zwrotu	Opis
.delete_if	ShippingRateList	Usuwanie stawek wysyłki za pomocą opcjonalnego bloku kodu. Zapoznaj się z dokumentacją metody języka Ruby `delete_if`.
.sort!	ShippingRateList	Sortowanie stawek wysyłki za pomocą operatora porównania lub opcjonalnego bloku kodu. Zapoznaj się z dokumentacją metody języka Ruby `sort!`.
.sort_by!	ShippingRateList	Sortowanie stawek wysyłki za pomocą opcjonalnego bloku kodu. Zapoznaj się z dokumentacją metody języka Ruby `sort_by!`.

ShippingRate

Metody skryptu wykorzystujące obiekt ShippingRate w skryptach wysyłki
Metoda	Typ zwrotu	Opis
.code	Ciąg znaków	Zwraca kod stawki wysyłki.
.markup	Pieniądze	Zwraca znacznik stawki wysyłki, jeśli taki występuje.
.name	Ciąg znaków	Zwraca nazwę stawki wysyłki. Można ją zmienić za pomocą metody `change_name`.
.price	Pieniądze	Zwraca cenę stawki wysyłki.
.source	Ciąg znaków	Zwraca źródło (przewoźnika) powiązane ze stawką wysyłki (w odpowiednich przypadkach). Nie można go modyfikować.
.change_name(String new_name)	Ciąg znaków	Zmienia nazwę (maksymalnie 255 znaków) stawki wysyłki. Źródła nie można zmienić, usunąć ani ukryć.
.apply_discount(Pieniądze discount, { message: String })	Pieniądze	Stosuje rabat w określonej stałej kwocie. Cena nie może zostać obniżona poniżej 0. Wymagana jest wiadomość.
.phone_required?	Wartość logiczna	Zwraca wartość `true`, jeśli numer telefonu jest wymagany do uzyskania stawki wysyłki, lub `false`, jeśli numer telefonu nie jest wymagany.

Metody płatności

Poniższe metody są używane w skryptach płatności:

Dane wejściowe

Metody skryptu wykorzystujące obiekt Dane wejściowe w skryptach płatności
Metoda	Typ zwrotu	Opis
.payment_gateways	PaymentGatewaysList	Zwraca listę wszystkich bramek płatniczych w sklepie.

PaymentGatewayList

Metody skryptu wykorzystujące obiekt PaymentGatewayList w skryptach płatności
Metoda	Typ zwrotu	Opis
.delete_if	PaymentGatewayList	Usuwanie bramek płatniczych pomocą opcjonalnego bloku kodu. Zapoznaj się z dokumentacją metody języka Ruby `delete_if`.
.sort!	PaymentGatewayList	Sortowanie bramek płatniczych za pomocą operatora porównania lub opcjonalnego bloku kodu. Zapoznaj się z dokumentacją metody języka Ruby `sort!`.
.sort_by!	PaymentGatewayList	Sortowanie bramek płatniczych za pomocą opcjonalnego bloku kodu. Zapoznaj się z dokumentacją metody języka Ruby `sort_by!`.

PaymentGateway

Metoda	Typ zwrotu	Opis
.name	Ciąg znaków	Zwraca nazwę bramki płatniczej.
.enabled_card_brands	List<String>	Jeśli bramka płatnicza obsługuje karty kredytowe, zwraca listę typów kart kredytowych akceptowanych w sklepie. Jeśli bramka nie obsługuje kart kredytowych, zwraca pustą listę.
.change_name(String new_name)	Ciąg znaków	Zmienia nazwę bramki płatniczej. Nie można zmienić nazwy bramek płatniczych z logo.

Przykłady

W poniższym przykładzie skryptu pozycji pojedynczej, gdy klient zamawia produkt, który nie jest kartą prezentową, cena produktu jest obniżana o 9 USD. Wyświetlana jest także łączna kwota wydana przez klienta podczas wszystkich wizyt w Twoim sklepie:

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

Dowiedz się więcej

Dowiedz się więcej o: