Di chuyển từ phiên bản 1 beta sang phiên bản 1

Hướng dẫn này giúp bạn di chuyển từ Merchant API v1beta sang v1, phiên bản đầu tiên cho giai đoạn Cung cấp công khai. Phiên bản v1 có một số điểm cập nhật và một vài thay đổi có thể yêu cầu bạn cập nhật mã. Những thay đổi này được thiết kế để đơn giản hoá API và cải thiện việc quản lý tài khoản Merchant Center của bạn.

Những điểm khác biệt chính

Sau đây là những thay đổi quan trọng nhất mà bạn cần lưu ý khi di chuyển từ v1beta sang v1:

• Đăng ký một lần cho ít nhất một nhà phát triển API để sử dụng Merchant API: Bạn sẽ cần gọi phương thức registerGcp (chỉ một lần cho mỗi dự án Google Cloud dùng để xác thực) để cung cấp thông tin liên hệ của mình. Nhờ đó, bạn có thể sử dụng API và nhận thông tin cập nhật cũng như thông báo liên quan đến Merchant API. Bạn sẽ không thể sử dụng bất kỳ API v1 hoặc v1alpha nào cho đến khi hoàn tất bước này. Để biết hướng dẫn, hãy xem phần Đăng ký làm nhà phát triển
• Product.attributes đổi tên: Trường Product.attributes đã được đổi tên thành Product.productAttributes.
• Xoá thông tin thuế ở cấp sản phẩm: Các trường taxes và taxCategory đã bị xoá khỏi đối tượng Product.productAttributes. Hãy xem bài viết về thuế trong Trung tâm trợ giúp của Google Merchant Center để biết thêm thông tin
• Thay đổi đối với trường GTIN: Trường gtin trong đối tượng Product.productAttributes đã được đổi tên thành gtins để phản ánh chính xác hơn rằng trường này có thể chứa nhiều giá trị. Trường gtin trong đối tượng OrderTrackingSignals.lineItemDetails hiện là array và cũng đã được đổi tên thành gtins.
• Xoá trường kênh: Trường channel đã bị xoá khỏi sản phẩm, dữ liệu đầu vào của sản phẩm và nguồn dữ liệu. Chúng tôi đã giới thiệu một trường boolean mới, legacyLocal, để chỉ định rõ ràng các sản phẩm chỉ được bán tại cửa hàng thực tế. Lưu ý: Trường legacyLocal là một trường phụ trợ giúp quá trình di chuyển và cuối cùng sẽ không được dùng nữa khi các phương thức tiếp thị trực tuyến và tại địa phương có thể được nhắm đến hoàn toàn bằng một nguồn sản phẩm duy nhất. Hãy xem bảng trong phần sau để biết thêm thông tin.
• Các trường mới cho thuộc tính kho hàng tại khu vực và tại địa phương:
  • Tất cả các trường RegionalInventory, ngoại trừ name, account và region, hiện được bao bọc trong một đối tượng mới có tên là regionalInventoryAttributes. Ví dụ: thuộc tính RegionalInventory.price hiện nằm trong RegionalInventory.regionalInventoryAttributes.price.
  • Tất cả các trường LocalInventory, ngoại trừ name, account và storeCode, hiện được bao bọc trong một đối tượng mới có tên là localInventoryAttributes. Ví dụ: thuộc tính LocalInventory.price hiện nằm trong LocalInventory.localInventoryAttributes.price.
• Xoá customAttributes khỏi kho hàng theo khu vực và tại địa phương: Trường customAttributes đã bị xoá khỏi cả tài nguyên RegionalInventory và LocalInventory.
• Cải tiến quy trình tạo tài khoản: Đã xoá trường users dư thừa khỏi CreateAndConfigureAccountRequest. Sử dụng trường user số ít để liên kết một người dùng ban đầu với một tài khoản mới.
• Một số loại thuộc tính đã được thay đổi từ chuỗi thành enum: Một số trường trong Product và Inventory tài nguyên có danh sách ngắn các giá trị được xác định đã được thay đổi từ loại string thành loại enum để xác thực dữ liệu tốt hơn (ví dụ: trường Product.ProductAttributes.condition hiện là enum).
• Xoá phương thức cập nhật chính sách trả lại hàng trực tuyến: Phương thức onlineReturnPolicy.update sẽ bị xoá trong v1. Thay vào đó, hãy tạo chính sách trả hàng trực tuyến bằng phương thức onlineReturnPolicy.create.

Cách di chuyển

Phiên bản v1beta của Merchant API dự kiến sẽ ngừng hoạt động từ ngày 28 tháng 2 năm 2026. Để biết thêm thông tin về lịch trình ngừng sử dụng, hãy xem hướng dẫn về việc tạo phiên bản Merchant API.

• Bước đầu tiên trong quá trình di chuyển là thực hiện quy trình đăng ký nhà phát triển một lần (Xem phần Đăng ký làm nhà phát triển). Bạn phải gọi phương thức registerGcp cho từng dự án Google Cloud mà bạn dùng để xác thực trước khi mọi phương thức v1 hoạt động.

• Bất kể bạn gọi API như thế nào (bằng REST, gRPC hoặc bằng cách sử dụng thư viện ứng dụng), bạn đều có thể di chuyển theo từng giai đoạn. Điều này có nghĩa là bạn có thể cập nhật và di chuyển mã của mình từng API một (ví dụ: di chuyển API Products sang v1 trong khi vẫn giữ API Accounts trên v1beta) mà không cần phải cập nhật toàn bộ quy trình tích hợp cùng một lúc.

Thông tin chi tiết về các thay đổi đối với trường

Bảng này cung cấp thông tin so sánh chi tiết về các trường đã thay đổi giữa phiên bản v1beta và v1.

v1beta	v1	Mô tả
Product.gtin	Product.gtins	Chúng tôi đã đổi tên trường cho GTIN.
Product.taxes	Đã xoá	Đã xoá trường taxes
Product.taxCategory	Đã xoá	Đã xoá trường taxCategory
Product.channel	Đã xoá	Đã xoá trường channel. Sử dụng trường legacyLocal cho các trường hợp sử dụng tại địa phương.
Product.attributes	Product.productAttributes	Trường attributes đã được đổi tên thành productAttributes.
availability, condition, gender, includedDestinations và excludedDestinations trong các trường Product được biểu thị dưới dạng strings (hoặc array của strings)	Các trường này hiện là enums (hoặc array của enums)	Các trường có danh sách ngắn gồm các giá trị được xác định đã thay đổi từ loại string thành enum.
price, salePrice, salePriceEffectiveDate và availability trong RegionalInventory	Đã chuyển vào RegionalInventory.regionalInventoryAttributes	Các trường này đã được chuyển sang regionalInventoryAttributes.
Trường RegionalInventory.availability là string	RegionalInventory.regionalInventoryAttributes.availability hiện là enums	Đã thay đổi loại tình trạng còn hàng từ string thành enum.
price, salePrice, salePriceEffectiveDate, availability, quantity, pickupMethod, pickupSla và instoreProductLocation trong LocalInventory	Đã chuyển vào LocalInventory.localInventoryAttributes	Các trường này đã được chuyển sang localInventoryAttributes.
Trường LocalInventory.availability là string	LocalInventory.localInventoryAttributes.availability hiện là enums	Đã thay đổi loại tình trạng còn hàng từ string thành enum.
LocalInventory.customAttributes	Đã xoá	Chúng tôi không còn hỗ trợ thuộc tính tuỳ chỉnh cho kho hàng tại địa phương nữa.
RegionalInventory.customAttributes	Đã xoá	Thuộc tính tuỳ chỉnh không còn được hỗ trợ cho kho hàng theo khu vực.
ProductInput.channel	Đã xoá	Đã xoá trường channel. Sử dụng trường legacyLocal cho các trường hợp sử dụng tại địa phương.
DataSource.channel	Đã xoá	Đã xoá trường channel. Sử dụng trường legacyLocal cho các trường hợp sử dụng tại địa phương.
Không có	ProductInput.legacyLocal	Một trường boolean mới cho biết rằng một sản phẩm chỉ có thể nhắm đến các phương thức tiếp thị tại địa phương. Mã nhận dạng tài nguyên sản phẩm sẽ có tiền tố "local~".
Không có	Product.legacyLocal	Một trường boolean mới cho biết rằng một sản phẩm chỉ được bán tại cửa hàng địa phương và không có sẵn để mua trực tuyến.
Không có	DataSource.legacyLocal	Một trường boolean mới cho biết rằng một nguồn dữ liệu chỉ chứa những sản phẩm được bán tại cửa hàng địa phương.
OrderTrackingSignals.LineItemDetails.gtin	OrderTrackingSignals.LineItemDetails.gtins	Trường gtin đã được đổi tên thành gtins và hiện là một mảng gồm các chuỗi (thay vì một chuỗi).
CreateAndConfigureAccountRequest.users	Đã xoá	Đã xoá trường users. Sử dụng trường user để thêm quản trị viên ban đầu vào tài khoản.