„Shopify“ scenarijų API vadovas

Scenarijai rašomi naudojant „Ruby“ API, kuri suteikia daug valdymo galimybių ir lankstumo.

Yra skirtingų tipų scenarijų. Scenarijui tipas priskiriamas, kai jį kuriate programėlėje „Script Editor“, atsižvelgiant į tai, kurį scenarijaus šabloną pasirenkate pradžiai:

Prekių pozicijų scenarijai

Prekių pozicijų scenarijai paveikia krepšelyje esančias prekių pozicijas ir gali keisti kainas bei suteikti nuolaidas. Šie scenarijai paleidžiami, kai atliekami pakeitimai krepšelyje.

Prekių pozicijų scenarijai, taikantys nuolaidą prenumeratai, galioja tik pirmajam prenumeratos mokėjimui. Vėlesniems mokėjimams scenarijus nuolaidos netaiko.

Kai kurie metodai gali būti naudojami tik prekių pozicijų scenarijuose.

Pristatymo scenarijai

Pristatymo scenarijai sąveikauja su pristatymu ir gali keisti pristatymo būdus bei taikyti nuolaidas pristatymo tarifams. Šie scenarijai paleidžiami, kai atsiskaitymo metu pasiekiamas pristatymo parinkčių puslapis.

Pristatymo scenarijai, taikantys nuolaidą prenumeratos pristatymo tarifui, galioja tik pirmajam prenumeratos mokėjimui. Vėlesniems mokėjimams scenarijus nuolaidos netaiko.

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

Mokėjimų valdymo scenarijai

Mokėjimų valdymo scenarijai sąveikauja su mokėjimais ir gali pervardyti, paslėpti bei pertvarkyti mokėjimo sietuvus. Atminkite, kad mokėjimų valdymo scenarijai nesąveikauja su mokėjimo sietuvais, rodomais prieš atsiskaitymo ekraną, pvz., „Apple Pay“. Šie scenarijai paleidžiami, kai atsiskaitymo metu pasiekiamas mokėjimo puslapis.

Kai kurie metodai gali būti naudojami tik mokėjimų valdymo scenarijuose.

Bendrieji metodai

Toliau nurodytus metodus galima naudoti bet kokio tipo scenarijuose:

Įvestis

Skripto įvesties metodai
MetodasGrąžinimo tipasAprašas
.cartKrepšelisGrąžina keičiamą krepšelio objektą.
.localeeilutėGrąžina kliento lokalę. Pavyzdžiui, en, fr arba pt-BR.

Krepšelis

Krepšelio objektas pasiekiamas tik internetinėje parduotuvėje. Kai kurie nebaigti atsiskaitymai turi prieigą prie krepšelio objekto. Tačiau, jei atsiskaitymas buvo uždarytas, o tada klientas apsilanko nebaigto atsiskaitymo puslapyje, jis nukreipiamas į iš anksto užpildytą atsiskaitymą ir krepšelio objektas nebeegzistuoja. Taip yra todėl, kad vitrina buvo apeita naudojant apleisto krepšelio atsiskaitymo el. laišką.

Scenarijaus metodai, naudojantys krepšelio objektą
MetodasGrąžinimo tipasAprašas
.customerKlientasGrąžina krepšelio savininką (jei toks yra).
.shipping_addressShippingAddressGrąžina krepšelio savininko pristatymo adresą (jei toks yra).
.discount_codekinta Grąžina:

discount_code yra, jei krepšeliui buvo pritaikyta nuolaida. Tai nebūtinai reiškia, kad krepšelio kaina keičiasi. Pavyzdžiui, jei nuolaida taikoma didesnės nei 50 $ vertės krepšeliams, o scenarijus sumažina krepšelio kainą žemiau 50 $, discount_code vis tiek išlieka, tačiau krepšelio kaina nesikeičia.

<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>&lt;LineItem&gt;</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>&lt;String&gt;</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

Scenarijaus metodai, naudojantys objektą „CartDiscount::FixedAmount“
MetodasGrąžinimo tipasAprašas
.codeEilutėGrąžina nuolaidos kodą, kuris buvo panaudotas nuolaidai pritaikyti.
.amountPinigaiGrąžina piniginę nuolaidos sumą.
.reject({ message: String })nilAtmeta krepšeliui pritaikytą nuolaidos kodą. Būtina nurodyti message.
.rejected?BulioGrąžina, ar nuolaidos kodas buvo atmestas.

CartDiscount::Percentage

Scenarijaus metodai, naudojantys objektą „CartDiscount::Percentage“
MetodasGrąžinimo tipasAprašas
.codeEilutėGrąžina nuolaidos kodą, kuris buvo panaudotas nuolaidai pritaikyti.
.percentageDešimtainisGrąžina nuolaidos dydį procentais.
.reject({ message: String })nilAtmeta krepšeliui pritaikytą nuolaidos kodą. Būtina nurodyti message.
.rejected?BulioGrąžina, ar nuolaidos kodas buvo atmestas.

CartDiscount::Shipping

Scenarijaus metodai, naudojantys objektą „CartDiscount::Shipping“
MetodasGrąžinimo tipasAprašas
.codeEilutėGrąžina nuolaidos kodą, kuris buvo panaudotas nuolaidai pritaikyti.
.reject({ message: String })nilAtmeta krepšeliui pritaikytą nuolaidos kodą. Būtina nurodyti message.
.rejected?BulioGrąžina, ar nuolaidos kodas buvo atmestas.

Klientas

Scenarijaus metodai, naudojantys objektą „Customer“
MetodasGrąžinimo tipasAprašas
.idIntegerGrąžina kliento ID numerį.
.emailEilutėGrąžina kliento el. pašto adresą.
.tagsList<Tag>Grąžina eilučių sąrašą, kuriame pateikiamos visos klientui priskirtos žymos.
.orders_countIntegerGrąžina bendrą kliento pateiktų užsakymų skaičių.
.total_spentPinigaiGrąžina bendrą sumą, kurią klientas išleido visiems užsakymams.
.accepts_marketing?BulioGrąžina, ar klientas sutinka gauti rinkodaros pranešimus.

Prekių pozicija

Scenarijaus metodai, naudojantys objektą „LineItem“
MetodasGrąžinimo tipasAprašas
.gramsgramaiGrąžina bendrą prekių pozicijos svorį.
.line_pricePinigaiPrekių pozicijos kaina.
.discounted?BulioGrąžina, ar prekių pozicijos kainai nuolaida buvo pritaikyta scenarijumi, ar rankiniu būdu. Nuolaidų kodų naudojimas grąžinamai vertei įtakos neturi.
.propertieshashGrąžina ypatybes, kurios buvo nurodytos šiai prekių pozicijai.
.variantVariantasGrąžina konkretų gaminio variantą, kurį atitinka ši prekių pozicija.
.quantityIntegerGrąžina šios prekių pozicijos kiekį.
.selling_plan_idIntegerGrąžina prekių pozicijos pardavimo plano ID. Šis metodas naudingas, kai parduotuvė parduoda prenumeratas ir norite, kad scenarijus aptiktų, kai produkto variantas yra parduodamas kaip prenumerata.

Sąrašas

Scenarijaus metodai, naudojantys objektą „List“
MetodasGrąžinimo tipasAprašas
.newSąrašasSukuria naują objektą, atitinkantį sąrašą.
.[]Elementas arba nil

Grąžina elementą pagal nurodytą indeksą.

.&Sąrašas

Grąžina naują sąrašą, kuriame yra abiem sąrašams bendri elementai be dublikatų.

.delete_ifSąrašasIštrina elementus naudojant pasirenkamą kodo bloką. Žr. „Ruby“ delete_if metodo dokumentaciją.
.empty?Bulio

Grąžina true, jei sąraše nėra elementų.

.firstElementas arba nil

Grąžina pirmąjį elementą arba nil, jei sąrašas tuščias.

.index(*args, &block)int arba nil

Grąžina pirmojo sąrašo elemento indeksą. Jei vietoj argumento pateikiamas blokas, grąžinamas pirmojo elemento, kuriam blokas grąžina reikšmę „true“, indeksas.

.rindex(*args, &block)int arba nil

Grąžina paskutinio sąrašo elemento indeksą. Jei vietoj argumento pateikiamas blokas, grąžinamas pirmojo elemento, kuriam blokas grąžina reikšmę „true“, indeksas.

.lastElementas arba nil

Grąžina paskutinį elementą arba nil, jei sąrašas tuščias.

.lengthint

Grąžina elementų skaičių sąraše.

.sizeint

„length“ pseudonimas.

.each(*args, &block)Sąrašas

Iškviečia bloką vieną kartą kiekvienam sąrašo elementui, perduodant elementą kaip parametrą blokui.

Pristatymo adresas

Scenarijaus metodai, naudojantys objektą „ShippingAddress“
MetodasGrąžinimo tipasAprašas
.nameeilutėGrąžina asmens, susieto su pristatymo adresu, vardą ir pavardę.
.address1eilutėGrąžina pristatymo adreso gatvės adreso dalį.
.address2eilutėGrąžina pasirenkamą papildomą pristatymo adreso gatvės adreso dalies lauką.
.phoneeilutėGrąžina pristatymo adreso telefono numerį.
.cityeilutėGrąžina pristatymo adreso miestą.
.zipeilutėGrąžina pristatymo adreso ZIP kodą.
.provinceeilutėGrąžina pristatymo adreso provinciją / valstiją.
.province_codeeilutėGrąžina sutrumpintą pristatymo adreso provincijos / valstijos reikšmę.
.country_codeeilutėGrąžina sutrumpintą pristatymo adreso šalies reikšmę.

Pinigai

Scenarijaus metodai, naudojantys objektą „Money“
MetodasGrąžinimo tipasAprašas
.derived_from_presentment(customer_cents:X)PinigaiKonvertuoja sumą (centais) iš kliento vietinės (pristatymo) valiutos į Jūsų parduotuvės valiutą. Šis metodas priima parametrą customer_cents, kuris priima skaičių centais. Pavyzdžiui, Money.derived_from_presentment(customer_cents: 500).
.newPinigaiSukuria naują objektą, kuris vaizduoja kainą.
.zeroPinigai

Sukuria naują objektą, kurio kaina lygi nuliui.

+PinigaiSudedami du Money objektai.
-PinigaiIš vieno Money objekto atimamas kitas.
*PinigaiMoney objektas padauginamas iš skaičiaus.

Money pavyzdžiai

Money.new(cents: 1000)

Sukuria Money objektą, vaizduojantį 1 000 centų, arba 10 USD.

Money.new(cents: 100) * 50

Sukuria Money objektą, vaizduojantį 1 USD, tada padaugina šią sumą iš 50. Grąžina Money objektą, vaizduojantį 50 USD.

Variantas

Scenarijaus metodai, naudojantys objektą „Variant“
MetodasGrąžinimo tipasAprašas
.idIntegerGrąžina varianto ID numerį.
.pricePinigaiGrąžina varianto vieneto kainą.
.productProduktasGrąžina susijusį varianto produktą.
.skusList<String>Grąžina varianto atsargų laikymo vienetus (SKU), kurie dažnai naudojami inventoriui sekti.
.titleEilutėGrąžina varianto pavadinimą.

Produktas

Scenarijaus metodai, naudojantys objektą „Product“
MetodasGrąžinimo tipasAprašas
.idIntegerGrąžina produkto ID numerį.
.gift_card?BulioGrąžina, ar produktas yra dovanų kortelė.
.tagsList<Tag>Grąžina eilučių, vaizduojančių šiam produktui nustatytas žymas, sąrašą.
.product_typeEilutėKategorija, kuria galima pažymėti produktą ir kuri dažniausiai naudojama filtravimui bei paieškai.
.vendorEilutėGrąžina šio produkto pardavėją.

Kernel

Kernel yra „Ruby“ modulis, kuris įtraukiamas į kiekvieną klasę. Dėl to jo metodai pasiekiami kiekvienam objektui. Šie metodai veikia taip pat, kaip globaliosios funkcijos kitose kalbose.

Scenarijaus metodai, naudojantys objektą „Kernel“
MetodasGrąžinimo tipasAprašas
.exitnėraUžbaigia dabartinio scenarijaus vykdymą be klaidų. Jei tai įvykdoma prieš ką nors priskiriant Output.cart, scenarijus neturi jokio poveikio. Tai naudingas būdas išeiti iš scenarijų, pavyzdžiui, jei klientas negali paleisti scenarijaus.

Kernel pavyzdys

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

Prekių pozicijų metodai

Toliau nurodytus metodus galima naudoti tik užsakymo eilučių skriptuose:

Krepšelis

Scenarijaus metodai, naudojantys objektą „Cart“ prekių pozicijų scenarijuose
MetodasGrąžinimo tipasAprašas
.subtotal_price_wasPinigaiGrąžina krepšelio tarpinę sumą prieš pritaikant bet kokias nuolaidas.
.subtotal_price_changed?BulioGrąžina, ar pasikeitė tarpinė suma.

Prekių pozicija

Scenarijaus metodai, naudojantys objektą „LineItem“ prekių pozicijų scenarijuose
MetodasGrąžinimo tipasAprašas
.change_line_price(Money new_price, { message: String }) PinigaiPakeičia prekės pozicijos kainą į nurodytą sumą. Būtina nurodyti message. new_price turi būti mažesnė už dabartinę kainą.
.original_line_pricePinigaiGrąžina pradinę prekės pozicijos kainą prieš pritaikant scenarijus ir nuolaidas.
.line_price_wasPinigaiGrąžina prekės pozicijos kainą prieš dabartiniam scenarijui pritaikant pakeitimus.
.line_price_changed?BulioGrąžina, ar pasikeitė prekės pozicijos kaina.
.change_properties(hash new_properties, { message: String }) hashNustato naujas prekių pozicijos ypatybes. Pradinis ypatybių maišos kodas (hash) saugomas properties_was, o metodui perduotas ypatybių maišos kodas tampa naujomis prekių pozicijos ypatybėmis.
.properties_washashGrąžina pradinį prekės pozicijos ypatybių maišos kodą (hash) prieš pritaikant bet kokius pakeitimus.
.properties_changed?BulioGrąžina, ar buvo pakeistos prekių pozicijos ypatybės.
.split({ take: Integer })Prekių pozicijaPadalija vieną prekių poziciją į dvi. take nurodo, kokį kiekį reikia atskirti nuo pradinės prekių pozicijos, norint sukurti naują prekių poziciją.

.split pavyzdys

Šis scenarijaus pavyzdys padalija prekių poziciją, pavadintą original_line_item, į dvi prekių pozicijas. Naujos prekių pozicijos kiekis yra 1 (nurodyta take: 1). Tada scenarijus pritaiko naujai prekių pozicijai kainą su nuolaida ir pranešimą „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

Variantas

Scenarijaus metodai, naudojantys objektą „Variant“ prekių pozicijų scenarijuose
MetodasGrąžinimo tipasAprašas
.compare_at_pricePinigaiGrąžina varianto palyginamąją kainą. Grąžina nil, jei variantas neturi palyginamosios kainos.

Pristatymo metodai

Šiuos metodus galima naudoti pristatymo scenarijuose:

Įvestis

Scenarijaus metodai, naudojantys objektą „Input“ pristatymo scenarijuose
MetodasGrąžinimo tipasAprašas
.shipping_ratesShippingRateListGrąžina visų siuntimo tarifų sąrašą.

ShippingRateList

Scenarijaus metodai, naudojantys „ShippingRateList“ objektą pristatymo scenarijuose
MetodasGrąžinimo tipasAprašas
.delete_ifShippingRateListIštrina siuntimo tarifus naudojant pasirinktinį kodo bloką. Žr. dokumentaciją apie „Ruby“ delete_if metodą.
.sort!ShippingRateListSurūšiuoja siuntimo tarifus naudojant palyginimo operatorių arba pasirinktinį kodo bloką. Žr. dokumentaciją apie „Ruby“ sort! metodą.
.sort_by!ShippingRateListSurūšiuoja siuntimo tarifus naudojant pasirinktinį kodo bloką. Žr. dokumentaciją apie „Ruby“ sort_by! metodą.

ShippingRate

Scenarijaus metodai, naudojantys „ShippingRate“ objektą pristatymo scenarijuose
MetodasGrąžinimo tipasAprašas
.codeEilutėGrąžina siuntimo tarifo kodą.
.markupPinigaiGrąžina siuntimo tarifo antkainį, jei taikoma.
.nameEilutėGrąžina siuntimo tarifo pavadinimą. Jį galima modifikuoti naudojant metodą change_name.
.pricePinigaiGrąžina siuntimo tarifo kainą.
.sourceEilutėGrąžina su siuntimo tarifu susietą šaltinį (vežėją), jei taikoma. Jo negalima modifikuoti.
.change_name(String new_name)Eilutė Pakeičia siuntimo tarifo pavadinimą (ne daugiau kaip 255 simboliai). Šaltinio negalima pakeisti, ištrinti ar paslėpti.
.apply_discount(Money discount, { message: String })PinigaiPritaiko nurodytos fiksuotos sumos nuolaidą. Kaina negali būti mažesnė nei 0. Būtina nurodyti pranešimą.
.phone_required?BulioGrąžina reikšmę true, jei norint gauti siuntimo tarifą būtina nurodyti telefono numerį, arba reikšmę false, jei telefono numeris nebūtinas.

Mokėjimo būdai

Mokėjimų valdymo scenarijuose galima naudoti šiuos metodus:

Įvestis

Scenarijaus metodai, naudojantys „Input“ objektą mokėjimų valdymo scenarijuose
MetodasGrąžinimo tipasAprašas
.payment_gatewaysPaymentGatewaysListGrąžina visų parduotuvės mokėjimo sietuvų sąrašą.

PaymentGatewayList

Scenarijaus metodai, naudojantys „PaymentGatewayList“ objektą mokėjimų valdymo scenarijuose
MetodasGrąžinimo tipasAprašas
.delete_ifPaymentGatewayListIštrina mokėjimo sietuvus naudojant pasirinktinį kodo bloką. Žr. dokumentaciją apie „Ruby“ delete_if metodą.
.sort!PaymentGatewayListSurūšiuoja mokėjimo sietuvus naudojant palyginimo operatorių arba pasirinktinį kodo bloką. Žr. dokumentaciją apie „Ruby“ sort! metodą.
.sort_by!PaymentGatewayListSurūšiuoja mokėjimo sietuvus naudojant pasirinktinį kodo bloką. Žr. dokumentaciją apie „Ruby“ sort_by! metodą.

PaymentGateway

MetodasGrąžinimo tipasAprašas
.nameEilutėGrąžina mokėjimo sietuvo pavadinimą.
.enabled_card_brandsList<String>

Jei mokėjimo sietuvas palaiko kreditines korteles, grąžinamas parduotuvės priimamų kreditinių kortelių tipų sąrašas. Jei sietuvas nepalaiko kreditinių kortelių, grąžinamas tuščias sąrašas.

.change_name(String new_name)EilutėPakeičia mokėjimo sietuvo pavadinimą. Mokėjimo sietuvų su logotipais pervardyti negalima.

Pavyzdžiai

Toliau pateiktame prekių pozicijų scenarijaus pavyzdyje, kai klientas užsako produktą, kuris nėra dovanų kortelė, produkto kaina sumažinama 9 $. Taip pat rodoma bendra suma, kurią klientas išleido per visus apsilankymus Jūsų parduotuvėje:

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

Sužinoti daugiau

Sužinokite daugiau apie: