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 Phát hành chính thức. Phiên bản v1 giới thiệu một số bản 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.

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

Dưới đâ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 ít nhất một nhà phát triển API để sử dụng Merchant API: Bạn cần gọi phương thức registerGcp (chỉ một lần cho mỗi dự án trên đám mây của Google dùng để xác thực) để cung cấp thông tin liên hệ. Việc này cho phép bạn sử dụng API và nhận các bản 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ỳ v1 hoặc v1alpha API nào cho đến khi hoàn tất bước này. Để biết thêm thông tin về quy trình đăng ký, hãy xem phần Đăng ký.

  • Mã hoá tên sản phẩm: Các ProductInput.name và Product.name trường hỗ trợ mã hoá base64url không có phần đệm (RFC 4648 Mục 5). Thực hiện theo các hướng dẫn sau:

    • Trước khi mã hoá, chuỗi phải tuân theo định dạng contentLanguage~feedLabel~offerId.

    • Bạn bắt buộc phải mã hoá nếu tên sản phẩm chứa các ký tự do Merchant API sử dụng hoặc các ký tự dành riêng cho URL, chẳng hạn như:

      % . + / : ~ , ( * ! ) & ? = @ # $

    • Nếu tên sản phẩm tuân theo contentLanguage~feedLabel~offerId định dạng và không chứa bất kỳ ký tự nào do Merchant API sử dụng hoặc các ký tự dành riêng cho URL, thì bạn có thể sử dụng định dạng văn bản thuần tuý mà không cần mã hoá.

    • Để đảm bảo quá trình phân tích cú pháp nhất quán và chính xác, bạn nên sử dụng mã hoá base64url không có phần đệm cho tất cả tên sản phẩm.

  • Xoá thông tin thuế ở cấp sản phẩm: taxes và taxCategory.

  • 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 taxes và taxCategory trường đã 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 rõ 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à một 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. Một trường boolean mới là legacyLocal đã được giới thiệu để chỉ định rõ ràng các sản phẩm chỉ bán tại cửa hàng thực. 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ẽ bị ngừng hoạt động sau khi các phương thức tiếp thị Trực tuyến và Địa phương có thể được nhắm mục tiêu đầy đủ 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 theo khu vực và địa phương:

    • Tất cả các trường RegionalInventory ngoại trừ name, account và region hiện được gói 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 gói 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à đị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: Trường users dư thừa đã bị xoá khỏi CreateAndConfigureAccountRequest. Sử dụng trường user ở dạng số ít để liên kế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à một 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 đã 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 vào ngày 28 tháng 2 năm 2026. Để biết thêm thông tin về lịch trình ngừng hoạt động, hãy xem hướng dẫn về việc kiểm soát 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 Đăng ký làm nhà phát triển). Bạn phải gọi phương thức registerGcp cho mỗi dự án trên đám mây của Google mà bạn sử dụng để xác thực trước khi bất kỳ phương thức v1 nào 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 cập nhật toàn bộ quá trình tích hợp cùng một lúc.

Thay đổi chi tiết về 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ả
ProductInput.name ProductInput.name Unpadded base64url encoding được hỗ trợ và bắt buộc phải sử dụng cho tên sản phẩm chứa các ký tự do Merchant API sử dụng hoặc các ký tự dành riêng cho URL.
Product.name Product.name Unpadded base64url encoding được hỗ trợ và bắt buộc phải sử dụng cho tên sản phẩm chứa các ký tự do Merchant API sử dụng hoặc các ký tự dành riêng cho URL.
Product.gtin Product.gtins Trường cho GTIN đã được đổi tên.
Product.taxes Đã xoá Trường taxes đã bị xoá
Product.taxCategory Đã xoá Trường taxCategory đã bị xoá
Product.channel Đã xoá Trường channel đã bị xoá. Sử dụng trường legacyLocal cho các trường hợp sử dụng đị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 các giá trị được xác định đã được thay đổi từ loại string thành enum.
price, salePrice, salePriceEffectiveDate và availability trong RegionalInventory Đã chuyển sang RegionalInventory.regionalInventoryAttributes Các trường này đã được chuyển sang regionalInventoryAttributes.
Trường RegionalInventory.availability là một string RegionalInventory.regionalInventoryAttributes.availability hiện là một enums Loại trạng thái còn hàng đã thay đổi từ string thành enum.
price, salePrice, salePriceEffectiveDate, availability, quantity, pickupMethod, pickupSla và instoreProductLocation trong LocalInventory Đã chuyển sang LocalInventory.localInventoryAttributes Các trường này đã được chuyển sang localInventoryAttributes.
Trường LocalInventory.availability là một string LocalInventory.localInventoryAttributes.availability hiện là một enums Loại trạng thái còn hàng đã thay đổi từ string thành enum.
LocalInventory.customAttributes Đã xoá Thuộc tính tuỳ chỉnh không còn được hỗ trợ cho kho hàng tại địa phương.
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á Trường channel đã bị xoá. Sử dụng trường legacyLocal cho các trường hợp sử dụng địa phương.
DataSource.channel Đã xoá Trường channel đã bị xoá. Sử dụng trường legacyLocal cho các trường hợp sử dụng đị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 mục tiêu đến các phương thức tiếp thị đị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ác cửa hàng địa phương và không có sẵn để mua hàng 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ứa các sản phẩm được bán tại các 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 chuỗi (thay vì một chuỗi).
CreateAndConfigureAccountRequest.users Đã xoá Trường users đã bị xoá. Sử dụng trường user để thêm quản trị viên ban đầu vào tài khoản.

Trước
Refactor code for concurrent requests
Tiếp
Overview