Tài liệu tham khảo về API Đoạn mã Shopify

Các đoạn mã được viết bằng API Ruby giúp bạn có được mức độ kiểm soát và tính linh hoạt cao.

Có nhiều loại đoạn mã khác nhau. Khi bạn tạo đoạn mã trong ứng dụng Script Editor, đoạn mã đó được gán loại dựa trên mẫu đoạn mã bạn chọn để bắt đầu:

Đoạn mã mục hàng

Đoạn mã tùy chỉnh mục hàng ảnh hưởng đến các mục hàng trong giỏ hàng, đồng thời có thể thay đổi giá và cấp quyền giảm giá. Những đoạn mã này chạy khi có thay đổi đối với giỏ hàng.

Đoạn mã tùy chỉnh mục hàng dùng để giảm giá cho đăng ký chỉ áp dụng đối với khoản thanh toán đầu tiên của đăng ký đó. Các khoản thanh toán tiếp theo sẽ không được giảm giá bởi đoạn mã.

Một số phương thức chỉ có thể sử dụng trong đoạn mã tùy chỉnh mục hàng.

Đoạn mã tùy chỉnh vận chuyển

Đoạn mã tùy chỉnh vận chuyển tương tác với quá trình vận chuyển, đồng thời có thể thay đổi phương thức vận chuyển và cấp quyền giảm giá đối với phí vận chuyển. Các đoạn mã này chạy khi trang thanh toán chuyển đến trang tùy chọn vận chuyển.

Đoạn mã tùy chỉnh vận chuyển dùng để giảm giá phí vận chuyển cho đăng ký chỉ áp dụng đối với khoản thanh toán đầu tiên của đăng ký đó. Các khoản thanh toán tiếp theo sẽ không được giảm giá bởi đoạn mã.

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

Đoạn mã tùy chỉnh thanh toán

Đoạn mã tùy chỉnh thanh toán tương tác với khoản thanh toán, đồng thời có thể đổi tên, ẩn và sắp xếp lại cổng thanh toán. Lưu ý rằng đoạn mã tùy chỉnh thanh toán không tương tác với những cổng thanh toán hiển thị trước màn hình thanh toán, chẳng hạn như Apple Pay. Các đoạn mã này chạy khi trang thanh toán chuyển đến trang thanh toán.

Một số phương thức chỉ có thể sử dụng trong đoạn mã tùy chỉnh thanh toán.

Trên trang này

Phương thức chung

Bạn có thể sử dụng các phương thức sau trong mọi loại đoạn mã:

Dữ liệu đầu vào

Phương thức dữ liệu đầu vào của đoạn mã
Phương thức	Loại trả về	Mô tả
.cart	Giỏ hàng	Trả về đối tượng giỏ hàng có thể sửa đổi.
.locale	chuỗi	Trả về ngôn ngữ và vùng của khách hàng. Ví dụ: `en`, `fr` hoặc `pt-BR`.

Giỏ hàng

Đối tượng giỏ hàng chỉ có trên cửa hàng trực tuyến. Một số giao dịch thanh toán bỏ dở có quyền truy cập vào đối tượng giỏ hàng. Tuy nhiên, nếu trang thanh toán đã bị đóng và sau đó khách hàng truy cập vào giao dịch thanh toán bỏ dở, họ sẽ được chuyển đến trang thanh toán đã điền sẵn thông tin và đối tượng giỏ hàng không còn tồn tại nữa. Lý do là vì email về giao dịch thanh toán bỏ dở đã bỏ qua cửa hàng.

Phương thức đoạn mã sử dụng đối tượng Giỏ hàng
Phương thức	Loại trả về	Mô tả
.customer	Khách hàng	Trả về chủ sở hữu giỏ hàng (nếu có).
.shipping_address	ShippingAddress	Trả về địa chỉ giao hàng của chủ sở hữu giỏ hàng (nếu có).
.discount_code	thay đổi	Trả về: `nil` nếu giỏ hàng không có mã giảm giá `CartDiscount::FixedAmount` nếu giỏ hàng có số tiền giảm giá cố định `CartDiscount::Percentage` nếu giỏ hàng có phần trăm giảm giá `CartDiscount::Shipping` nếu giỏ hàng có giảm giá vận chuyển Trả về một mã giảm giá duy nhất (xem phần Giới hạn) `discount_code` sẽ hiển thị nếu mã giảm giá đã được áp dụng cho giỏ hàng. Điều này không có nghĩa là giá của giỏ hàng sẽ thay đổi. Ví dụ: nếu khoản giảm giá áp dụng cho giỏ hàng có giá trị trên 50 USD và đoạn mã làm giảm giá trị giỏ hàng xuống dưới 50 USD, thì `discount_code` vẫn xuất hiện nhưng giá của giỏ hàng không thay đổi. <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

Phương thức đoạn mã sử dụng đối tượng CartDiscount::FixedAmount
Phương thức	Loại trả về	Mô tả
.code	Chuỗi	Trả về mã giảm giá dùng để áp dụng khoản giảm giá.
.amount	Tiền	Trả về số tiền của khoản giảm giá.
.reject({ message: String })	nil	Từ chối mã giảm giá áp dụng cho giỏ hàng. Bắt buộc phải có `message`.
.rejected?	Boolean	Trả về thông tin cho biết mã giảm giá có bị từ chối hay không.

CartDiscount::Percentage

Phương thức đoạn mã sử dụng đối tượng CartDiscount::Percentage
Phương thức	Loại trả về	Mô tả
.code	Chuỗi	Trả về mã giảm giá dùng để áp dụng khoản giảm giá.
.percentage	Số thập phân	Trả về phần trăm của khoản giảm giá.
.reject({ message: String })	nil	Từ chối mã giảm giá áp dụng cho giỏ hàng. Bắt buộc phải có `message`.
.rejected?	Boolean	Trả về thông tin cho biết mã giảm giá có bị từ chối hay không.

CartDiscount::Shipping

Phương thức đoạn mã sử dụng đối tượng CartDiscount::Shipping
Phương thức	Loại trả về	Mô tả
.code	Chuỗi	Trả về mã giảm giá dùng để áp dụng khoản giảm giá.
.reject({ message: String })	nil	Từ chối mã giảm giá áp dụng cho giỏ hàng. Bắt buộc phải có `message`.
.rejected?	Boolean	Trả về thông tin cho biết mã giảm giá có bị từ chối hay không.

Khách hàng

Phương thức đoạn mã sử dụng đối tượng Khách hàng
Phương thức	Loại trả về	Mô tả
.id	Số nguyên	Trả về số ID của khách hàng.
.email	Chuỗi	Trả về địa chỉ email của khách hàng.
.tags	Danh sách<Thẻ>	Trả về danh sách chuỗi đại diện cho mọi thẻ được thiết lập cho khách hàng.
.orders_count	Số nguyên	Trả về tổng số đơn hàng mà khách hàng đã đặt.
.total_spent	Tiền	Trả về tổng số tiền mà khách hàng đã chi tiêu cho tất cả đơn hàng.
.accepts_marketing?	Boolean	Trả về thông tin cho biết khách hàng có chấp nhận tiếp thị hay không.

LineItem

Các phương thức tập lệnh sử dụng đối tượng LineItem
Phương thức	Loại trả về	Mô tả
.grams	grams	Trả về tổng trọng lượng của mục hàng.
.line_price	Tiền	Giá của mục hàng.
.discounted?	Boolean	Trả về thông tin cho biết giá của mục hàng có được giảm qua một tập lệnh hay khoản giảm giá áp dụng thủ công không. Việc sử dụng mã giảm giá không ảnh hưởng đến giá trị trả về.
.properties	hash	Trả về các thuộc tính đã chỉ định cho mục hàng này.
.variant	Variant	Trả về biến thể sản phẩm cụ thể do mục hàng đại diện.
.quantity	Số nguyên	Trả về số lượng của mục hàng này.
.selling_plan_id	Số nguyên	Trả về ID của gói bán hàng đối với mục hàng. Phương thức này hữu ích khi cửa hàng bán gói đăng ký và bạn muốn tập lệnh phát hiện khi biến thể sản phẩm được bán dưới dạng gói đăng ký.

List

Các phương thức tập lệnh sử dụng đối tượng List
Phương thức	Loại trả về	Mô tả
.new	List	Tạo đối tượng mới để đại diện cho một danh sách.
.[]	Phần tử hoặc nil	Trả về phần tử ở chỉ mục đã chỉ định.
.&	List	Trả về danh sách mới chứa các phần tử chung của hai danh sách và không có phần tử trùng lặp.
.delete_if	List	Xóa phần tử bằng khối mã tùy chọn. Xem tài liệu về phương thức `delete_if` của Ruby.
.empty?	Boolean	Trả về `true` nếu danh sách không có phần tử nào.
.first	Phần tử hoặc nil	Trả về phần tử đầu tiên hoặc `nil` nếu danh sách trống.
.index(*args, &block)	int hoặc nil	Trả về chỉ mục của phần tử đầu tiên trong danh sách. Nếu sử dụng khối mã thay cho đối số, trả về chỉ mục của phần tử đầu tiên mà khối đó đúng (true).
.rindex(*args, &block)	int hoặc nil	Trả về chỉ mục của phần tử cuối cùng trong danh sách. Nếu sử dụng khối mã thay cho đối số, trả về chỉ mục của phần tử đầu tiên mà khối đó đúng (true).
.last	Phần tử hoặc nil	Trả về phần tử cuối cùng hoặc `nil` nếu danh sách trống.
.length	int	Trả về số lượng phần tử trong danh sách.
.size	int	Bí danh của length.
.each(*args, &block)	List	Gọi một khối mã một lần cho từng phần tử trong danh sách, truyền phần tử đó làm tham số cho khối.

ShippingAddress

Các phương thức tập lệnh sử dụng đối tượng ShippingAddress
Phương thức	Loại trả về	Mô tả
.name	chuỗi	Trả về tên của người gắn với địa chỉ giao hàng.
.address1	chuỗi	Trả về phần địa chỉ đường phố của địa chỉ giao hàng.
.address2	chuỗi	Trả về trường bổ sung tùy chọn của phần địa chỉ đường phố trong địa chỉ giao hàng.
.phone	chuỗi	Trả về số điện thoại của địa chỉ giao hàng.
.city	chuỗi	Trả về thành phố của địa chỉ giao hàng.
.zip	chuỗi	Trả về mã ZIP của địa chỉ giao hàng.
.province	chuỗi	Trả về tỉnh/tiểu bang của địa chỉ giao hàng.
.province_code	chuỗi	Trả về giá trị viết tắt của tỉnh/tiểu bang trong địa chỉ giao hàng.
.country_code	chuỗi	Trả về giá trị viết tắt của quốc gia trong địa chỉ giao hàng.

Money

Các phương thức tập lệnh sử dụng đối tượng Money
Phương thức	Loại trả về	Mô tả
.derived_from_presentment(customer_cents:X)	Tiền	Chuyển đổi số tiền (tính bằng xu) từ đơn vị tiền tệ địa phương (đơn vị tiền tệ hiển thị) của khách hàng sang tiền tệ của cửa hàng. Phương thức này chấp nhận tham số `customer_cents`, nhận vào một số tính bằng xu. Ví dụ: `Money.derived_from_presentment(customer_cents: 500)`.
.new	Tiền	Tạo đối tượng mới để đại diện cho một mức giá.
.zero	Tiền	Tạo đối tượng mới có mức giá bằng 0.
+	Tiền	Cộng hai đối tượng `Money`.
-	Tiền	Trừ một đối tượng `Money` khỏi đối tượng khác.
*	Tiền	Nhân đối tượng `Money` với một số.

Ví dụ về Money

Money.new(cents: 1000)

Tạo đối tượng Money đại diện cho 1000 xu, tức là $10.

Money.new(cents: 100) * 50

Tạo đối tượng Money đại diện cho 1 đô la, sau đó nhân số tiền đó với 50. Trả về đối tượng Money đại diện cho 50 đô la.

Mẫu mã

Các phương thức tập lệnh sử dụng đối tượng Variant
Phương thức	Loại trả về	Mô tả
.id	Số nguyên	Trả về số ID của mẫu mã.
.price	Tiền	Trả về đơn giá của mẫu mã.
.product	Product	Trả về sản phẩm liên kết của mẫu mã.
.skus	List<String>	Trả về các đơn vị lưu kho (SKU) của mẫu mã, thường được dùng để theo dõi hàng tồn kho.
.title	Chuỗi	Trả về tiêu đề của mẫu mã.

Sản phẩm

Các phương thức tập lệnh sử dụng đối tượng Product
Phương thức	Loại trả về	Mô tả
.id	Số nguyên	Trả về số ID của sản phẩm.
.gift_card?	Boolean	Trả về kết quả cho biết sản phẩm có phải là thẻ quà tặng hay không.
.tags	Danh sách<Thẻ>	Trả về một danh sách các chuỗi đại diện cho những thẻ được đặt cho sản phẩm này.
.product_type	Chuỗi	Phân loại mà sản phẩm có thể được gắn thẻ, thường dùng để lọc và tìm kiếm.
.vendor	Chuỗi	Trả về nhà cung cấp của sản phẩm này.

Kernel

Kernel là mô-đun Ruby có trong mọi lớp. Do đó, các phương thức của Kernel có thể dùng cho mọi đối tượng. Các phương thức này hoạt động giống như hàm toàn cục trong những ngôn ngữ khác.

Các phương thức tập lệnh sử dụng đối tượng Kernel
Phương thức	Loại trả về	Mô tả
.exit	không có	Kết thúc quá trình thực thi tập lệnh hiện tại mà không có lỗi. Nếu thao tác này chạy trước khi có bất kỳ giá trị nào được gán cho `Output.cart` thì tập lệnh sẽ không có tác dụng. Đây là cách hữu ích để thoát tập lệnh, ví dụ: nếu khách hàng không đủ điều kiện chạy tập lệnh.

Ví dụ về Kernel

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

Phương thức mục hàng

Các phương thức sau chỉ dùng được trong tập lệnh mục hàng:

Giỏ hàng

Các phương thức tập lệnh sử dụng đối tượng Cart trong tập lệnh mục hàng
Phương thức	Loại trả về	Mô tả
.subtotal_price_was	Tiền	Trả về giá tổng phụ của giỏ hàng trước khi áp dụng bất kỳ khoản giảm giá nào.
.subtotal_price_changed?	Boolean	Trả về kết quả cho biết giá tổng phụ đã thay đổi hay chưa.

LineItem

Các phương thức tập lệnh sử dụng đối tượng LineItem trong tập lệnh mục hàng
Phương thức	Loại trả về	Mô tả
.change_line_price(Money new_price, { message: String })	Tiền	Thay đổi giá của mục hàng thành số tiền được chỉ định. Bắt buộc phải có `message`. `new_price` phải thấp hơn giá hiện tại.
.original_line_price	Tiền	Trả về giá ban đầu của mục hàng trước khi áp dụng tập lệnh và giảm giá.
.line_price_was	Tiền	Trả về giá của mục hàng trước khi tập lệnh hiện tại áp dụng thay đổi.
.line_price_changed?	Boolean	Trả về kết quả cho biết giá của mục hàng đã thay đổi hay chưa.
.change_properties(hash new_properties, { message: String })	hash	Đặt thuộc tính mới cho một mục hàng. Hash thuộc tính ban đầu được lưu trong `properties_was` và hash thuộc tính được chuyển đến phương thức sẽ trở thành các thuộc tính mới của mục hàng.
.properties_was	hash	Trả về hash thuộc tính ban đầu của mục hàng trước khi áp dụng bất kỳ thay đổi nào.
.properties_changed?	Boolean	Trả về kết quả cho biết thuộc tính của mục hàng đã thay đổi hay chưa.
.split({ take: Integer })	LineItem	Tách một mục hàng thành hai mục hàng. `take` chỉ định số lượng cần lấy từ mục hàng ban đầu để tạo mục hàng mới.

Ví dụ về .split

Tập lệnh ví dụ này tách mục hàng có tên original_line_item thành hai mục hàng. Mục hàng mới có số lượng là 1 (được chỉ định bởi take: 1). Sau đó, tập lệnh áp dụng mức giá đã chiết khấu cho mục hàng mới kèm theo thông báo "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

Mẫu mã

Các phương thức tập lệnh sử dụng đối tượng Variant trong tập lệnh mục hàng
Phương thức	Loại trả về	Mô tả
.compare_at_price	Tiền	Trả về giá so sánh của mẫu mã. Trả về `nil` nếu mẫu mã không có giá so sánh.

Phương thức vận chuyển

Các phương thức sau có thể dùng trong tập lệnh vận chuyển:

Dữ liệu đầu vào

Các phương thức tập lệnh sử dụng đối tượng Input trong tập lệnh vận chuyển
Phương thức	Loại trả về	Mô tả
.shipping_rates	ShippingRateList	Trả về danh sách tất cả phí vận chuyển.

ShippingRateList

Các phương thức tập lệnh sử dụng đối tượng ShippingRateList trong tập lệnh vận chuyển
Phương thức	Loại trả về	Mô tả
.delete_if	ShippingRateList	Xóa phí vận chuyển bằng khối mã tùy chọn. Xem tài liệu về phương thức `delete_if` của Ruby.
.sort!	ShippingRateList	Sắp xếp các mức phí vận chuyển bằng toán tử so sánh hoặc khối mã tùy chọn. Xem tài liệu về phương thức `sort!` của Ruby.
.sort_by!	ShippingRateList	Sắp xếp các mức phí vận chuyển bằng khối mã tùy chọn. Xem tài liệu về phương thức `sort_by!` của Ruby.

ShippingRate

Các phương thức tập lệnh sử dụng đối tượng ShippingRate trong tập lệnh vận chuyển
Phương thức	Loại trả về	Mô tả
.code	Chuỗi	Trả về mã phí vận chuyển.
.markup	Tiền	Trả về mức tăng giá của phí vận chuyển, nếu có.
.name	Chuỗi	Trả về tên của phí vận chuyển. Có thể thay đổi tên bằng phương thức `change_name`.
.price	Tiền	Trả về mức giá của phí vận chuyển.
.source	Chuỗi	Trả về nguồn (hãng vận chuyển) liên kết với phí vận chuyển, nếu phù hợp. Không thể sửa đổi nguồn này.
.change_name(String new_name)	Chuỗi	Thay đổi tên (tối đa 255 ký tự) của phí vận chuyển. Không thể thay đổi, xóa hoặc ẩn nguồn.
.apply_discount(Money discount, { message: String })	Tiền	Áp dụng khoản chiết khấu bằng số tiền cố định đã chỉ định. Không thể giảm giá xuống dưới 0. Bắt buộc phải có tin nhắn.
.phone_required?	Boolean	Trả về `true` nếu cần số điện thoại để lấy phí vận chuyển, hoặc `false` nếu không cần số điện thoại.

Phương thức thanh toán

Có thể sử dụng các phương thức sau trong đoạn mã tùy chỉnh thanh toán:

Dữ liệu đầu vào

Phương thức đoạn mã sử dụng đối tượng Input trong đoạn mã tùy chỉnh thanh toán
Phương thức	Loại trả về	Mô tả
.payment_gateways	PaymentGatewaysList	Trả về danh sách tất cả cổng thanh toán trong cửa hàng.

PaymentGatewayList

Phương thức đoạn mã sử dụng đối tượng PaymentGatewayList trong đoạn mã tùy chỉnh thanh toán
Phương thức	Loại trả về	Mô tả
.delete_if	PaymentGatewayList	Xóa cổng thanh toán bằng khối mã tùy chọn. Xem tài liệu về phương thức `delete_if` của Ruby.
.sort!	PaymentGatewayList	Sắp xếp cổng thanh toán bằng toán tử so sánh hoặc bằng khối mã tùy chọn. Xem tài liệu về phương thức `sort!` của Ruby.
.sort_by!	PaymentGatewayList	Sắp xếp cổng thanh toán bằng khối mã tùy chọn. Xem tài liệu về phương thức `sort_by!` của Ruby.

PaymentGateway

Phương thức	Loại trả về	Mô tả
.name	Chuỗi	Trả về tên của cổng thanh toán.
.enabled_card_brands	List<String>	Nếu cổng thanh toán hỗ trợ thẻ tín dụng, trả về danh sách các loại thẻ tín dụng mà cửa hàng chấp nhận. Nếu cổng không hỗ trợ thẻ tín dụng, trả về danh sách trống.
.change_name(String new_name)	Chuỗi	Thay đổi tên cổng thanh toán. Không thể đổi tên cổng thanh toán có logo.

Ví dụ

Trong ví dụ về đoạn mã mục hàng sau đây, khi khách hàng đặt hàng một sản phẩm không phải là thẻ quà tặng, giá sản phẩm sẽ được giảm 9 USD. Ngoài ra, tổng số tiền khách hàng đã chi tiêu trong tất cả các lượt truy cập vào cửa hàng sẽ hiển thị:

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

Tìm hiểu thêm

Tìm hiểu thêm về: