Lưu ý quan trọng: Content API for Shopping sẽ ngừng hoạt động từ ngày 18 tháng 8 năm 2026.

Giới thiệu về Merchant API – API chính thức thay thế cho Content API for Shopping.

Nhận thông tin mới nhất về các tính năng mới, bản sửa lỗi và bản cập nhật của Merchant API.

Bắt đầu sử dụng Merchant API và có quyền truy cập vào dữ liệu, thông tin chi tiết và các tính năng độc đáo ở quy mô lớn.

Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

lệnh gọi tài nguyên sản phẩm

Tài nguyên products cho phép bạn linh hoạt và kiểm soát hơn 60 thuộc tính sản phẩm.Có một số trường bắt buộc, và bạn phải cung cấp các trường này để được phê duyệt xuất hiện trên Google Mua sắm. Có một số trường không bắt buộc nhưng có thể trở thành bắt buộc dựa trên nhiều điều kiện như vị trí, loại sản phẩm, sản phẩm biến thể và gói sản phẩm. Để biết thêm thông tin về hơn 60 tham số không bắt buộc mà bạn có thể định cấu hình cho sản phẩm, hãy tham khảo Quy cách dữ liệu sản phẩm.

Tài nguyên products cho phép bạn insert, get, update và delete một sản phẩm tại một thời điểm, đồng thời list tất cả sản phẩm trong cơ sở dữ liệu của Merchant Center.

Bạn có thể sử dụng tài nguyên productstatuses để kiểm tra trạng thái phê duyệt hoặc từ chối của một sản phẩm cụ thể cho một vị trí. Hãy tham khảo hướng dẫn về trạng thái sản phẩm để biết thêm thông tin về những sản phẩm có thể gặp vấn đề về chất lượng dữ liệu và những vấn đề đó có thể là gì.

Trong các ví dụ về API, chúng tôi sử dụng 3 sản phẩm: 2 áo phông Google và 1 mũ Google. Chúng tôi sử dụng một tập hợp tối thiểu dữ liệu sản phẩm được trình bày trong bảng bên dưới để thực hiện các lệnh gọi tài nguyên products nhằm chèn, lấy, cập nhật, liệt kê và xoá các sản phẩm riêng lẻ và lô sản phẩm.

Bạn nên định cấu hình thông tin Vận chuyển và Thuế ở cấp tài khoản thay vì ở cấp sản phẩm.

Đối với các tài khoản phụ nhiều người bán của Trang web thương mại, tất cả sản phẩm phải có trường external_seller_id. Xem Mã sản phẩm để biết thêm thông tin.


id	online:en:US:1111111111	online:en:US:2222222222	online:en:US:3333333333
offerId	1111111111	2222222222	3333333333
tiêu đề	Áo phông Google màu đen	Áo phông Google màu xanh lục	Mũ Google bằng vải chéo
mô tả	Áo phông Google màu đen	Áo phông Google làm từ 100% cotton	Mũ Google cổ điển
Mã nhóm mặt hàng	google_tee	google_tee
liên kết	http://my.site.com/blacktee	http://my.site.com/greentee	http://my.site.com/blackhat
điều kiện	Mới	Mới	Mới
price	21,99 USD	21,99 USD	10,99 USD
độ khả dụng	Còn hàng	Còn hàng	Còn hàng
imageLink	https://shop.example.com/store/20160512512/assets/items/images/GGOEGXXX1100.jpg	https://shop.example.com/store/20160512512/assets/items/images/GGOEGXXX0906.jpg	https://shop.example.com/store/20160512512/assets/items/images/GGOEGHPB071610.jpg
gtin (mã số sản phẩm thương mại toàn cầu)	9504000059422	9504000059446	9504000059452
mpn (mã số linh kiện của nhà sản xuất)	00638NIC	00638ANG	00638ABC
thương hiệu	Google	Google	Google
Danh mục sản phẩm của Google	Quần áo và phụ kiện > Quần áo	Quần áo và phụ kiện > Quần áo	Quần áo và phụ kiện > Phụ kiện quần áo > Mũ
màu	đen	màu xanh lục	đen
size	L	M	M
age_group	người lớn	người lớn	người lớn
gender	nam	nam	unisex
included_destination	Mua sắm Trực tiếp, Quảng cáo mua sắm	Mua sắm Trực tiếp, Quảng cáo mua sắm	Mua sắm Trực tiếp

products.insert

Để chèn một sản phẩm, hãy sử dụng URL yêu cầu sau, chỉ định mã người bán và một mẫu nội dung JSON. Lệnh chèn sẽ tạo sản phẩm mới. Nếu có giá trị cho các thuộc tính channel, contentLanguage, offerId và feedLabel đối với một sản phẩm nhất định, thì phương thức này sẽ cập nhật mục đó và thay thế tất cả dữ liệu từ các lệnh gọi API trước đó cho sản phẩm đó.

Những sản phẩm không được phép xuất hiện tại tất cả các vị trí trên 7 ngày sẽ tự động bị xoá.

Ví dụ được trình bày sẽ chèn một "Áo phông Google màu đen" mới vào các sản phẩm hiện có.

POST https://shoppingcontent.googleapis.com/content/v2.1/{merchantId}/products

Ví dụ về lệnh gọi nội dung yêu cầu cho products.insert:

{
 "kind": "content#product",
 "offerId": "1111111111",
 "title": "Google Tee Black",
 "description": "The Black Google Tee is available in unisex sizing.",
 "link": "http://my.site.com/blacktee/",
 "imageLink": "https://shop.example.com/.../images/GGOEGXXX1100.jpg",
 "contentLanguage": "en",
 "targetCountry": "US",
 "feedLabel": "US",
 "channel": "online",
 "ageGroup": "adult",
 "availability": "in stock",
 "availabilityDate": "2019-01-25T13:00:00-08:00",
 "brand": "Google",
 "color": "black",
 "condition": "new",
 "gender": "male",
 "googleProductCategory": "1604",
 "gtin": "608802531656",
 "itemGroupId": "google_tee",
 "mpn": "608802531656",
 "price": {
  "value": "21.99",
  "currency": "USD"
 },
 "sizes": [
  "Large"
 ]
}

Một sản phẩm cũng có thể có các thuộc tính tuỳ chỉnh được thiết lập trong nội dung JSON. Ví dụ: chúng ta có thể thiết lập purchase_quantity_limit cho một sản phẩm để giới hạn số lượng mặt hàng mà khách hàng có thể đặt:

"customAttributes": [
 {
   "name": "purchase_quantity_limit",
   "value": "4"
 }
]

Xin lưu ý rằng thuộc tính tuỳ chỉnh purchase_quantity_limit thiết lập hạn mức mua cho mỗi đơn đặt hàng của khách hàng theo định nghĩa sản phẩm và cũng được nguồn cấp dữ liệu hỗ trợ. Thuộc tính này hiện đang ở giai đoạn thử nghiệm cho đến khi được API hỗ trợ đầy đủ. Người bán có thể thêm mọi thuộc tính tuỳ chỉnh khác nhưng các API sẽ không xử lý thuộc tính đó theo cách cụ thể nào.

Lệnh gọi thành công sẽ trả về mã HTTP 200 và nội dung phản hồi chứa tài nguyên sản phẩm được chèn chỉ có id, offerId, contentLanguage, feedLabel và channel được điền:

{
 "kind": "content#product",
 "id": "online:en:US:1111111111",
 "offerId": "1111111111",
 "contentLanguage": "en",
 "targetCountry": "US",
 "feedLabel": "US",
 "channel": "online"
}

products.get

Để lấy thông tin về một sản phẩm cụ thể trong cơ sở dữ liệu của Merchant Center, hãy sử dụng products.get. Có thể mất vài phút để một sản phẩm mới chèn được cung cấp thông qua lệnh gọi này.

Sử dụng URL và tham số yêu cầu HTTP sau, mã người bán và mã sản phẩm (định dạng mã nhận dạng REST) cho sản phẩm mà bạn muốn lấy:

GET https://shoppingcontent.googleapis.com/content/v2.1/{merchantId}/products/{productId}

Lệnh gọi thành công sẽ trả về HTTP 200 và "tài nguyên sản phẩm" trong nội dung phản hồi. Dưới đây là dữ liệu sản phẩm mẫu được truy xuất từ một sản phẩm có mã online:en:US:1111111111:

{
 "kind": "content#product",
 "id": "online:en:US:1111111111",
 "offerId": "1111111111",
 "source": "api",
 "title": "Google Tee Black",
 "description": "The Black Google Tee is available in unisex sizing.",
 "link": "http://my.site.com/blacktee/",
 "imageLink": "https://shop.example.com/.../images/GGOEGXXX1100.jpg",
 "contentLanguage": "en",
 "targetCountry": "US",
 "feedLabel": "US",
 "channel": "online",
 "ageGroup": "adult",
 "availability": "in stock",
 "availabilityDate": "2019-01-25T13:00:00-08:00",
 "brand": "Google",
 "color": "black",
 "condition": "new",
 "gender": "male",
 "googleProductCategory": "1604",
 "gtin": "608802531656",
 "itemGroupId": "google_tee",
 "mpn": "608802531656",
 "price": {
  "value": "21.99",
  "currency": "USD"
 },
 "sizes": [
  "Large"
 ]
}

products.update

Để cập nhật một sản phẩm, hãy sử dụng URL yêu cầu sau bằng phương thức PATCH, chỉ định mã người bán, mã sản phẩm và nội dung JSON chứa dữ liệu mà bạn muốn cập nhật cho sản phẩm đó. Không giống như products.insert (yêu cầu bạn phải cung cấp tất cả các trường áp dụng), products.update chỉ yêu cầu bạn chỉ định các trường mà bạn muốn thay đổi.

Để thêm hoặc sửa đổi một thuộc tính, hãy chỉ định trường có giá trị mới trong nội dung JSON. Ví dụ được trình bày sẽ cập nhật title và description của "Áo phông Google màu đen" hiện có bằng dữ liệu sản phẩm được cung cấp trong nội dung yêu cầu, giữ nguyên tất cả các trường khác.

PATCH https://shoppingcontent.googleapis.com/content/v2.1/{merchantId}/products/{productId}

Ví dụ về lệnh gọi nội dung yêu cầu cho products.update:

{
 "title": "Google Tee Black Limited Edition",
 "description": "The Limited Edition Tee is available in unisex sizing and features a retail fit."
}

Bạn chỉ có thể cập nhật các trường cấp cao nhất thông qua yêu cầu products.update request. Nếu bạn muốn cập nhật các trường lồng nhau, bạn phải cung cấp toàn bộ đối tượng cấp cao nhất.

Ví dụ được trình bày sẽ cập nhật đối tượng salePrice cấp cao nhất (bao gồm cả các trường lồng nhau của một sản phẩm hiện có) bằng dữ liệu sản phẩm được cung cấp trong nội dung yêu cầu, giữ nguyên tất cả các trường khác.

PATCH https://shoppingcontent.googleapis.com/content/v2.1/{merchantId}/products/{productId}

{
 "salePrice": {
  "value": "17.99",
  "currency": "USD"
 }
}

Để chọn một số trường cần cập nhật mà không thay đổi các trường khác có trong nội dung yêu cầu, bạn có thể chỉ định updateMask. Tham số chuỗi truy vấn này phải là danh sách các trường được phân tách bằng dấu phẩy mà bạn muốn sửa đổi. updateMask rất hữu ích khi bạn muốn khẳng định rằng chỉ các trường được đặt tên mới được cập nhật. Việc không chỉ định updateMask tương đương với việc đánh dấu tất cả các trường trong yêu cầu cần cập nhật như trong ví dụ ở trên.

Ví dụ được trình bày sẽ chỉ cập nhật description và availability của "Áo phông Google màu đen" hiện có bằng dữ liệu sản phẩm tương ứng được cung cấp trong nội dung yêu cầu, giữ nguyên tất cả các trường khác, bao gồm cả title.

PATCH https://shoppingcontent.googleapis.com/content/v2.1/{merchantId}/products/{productId}?updateMask=description,availability

Ví dụ về lệnh gọi nội dung yêu cầu cho products.update:

{
 "title": "Google Tee Black",
 "description": "This Limited Edition is out of print.",
 "availability": "out of stock"
}

Nếu một trường được cung cấp trong danh sách updateMask nhưng không có trong nội dung yêu cầu, thì trường đó sẽ bị xoá khỏi tài nguyên Product (nếu có).

Ví dụ được trình bày sẽ sử dụng updateMask để xoá giá trị cho trường salePrice.

PATCH https://shoppingcontent.googleapis.com/content/v2.1/{merchantId}/products/{productId}?updateMask=salePrice

Nội dung yêu cầu mẫu không được chứa trường salePrice để xoá trường đó. Bạn cũng có thể không cung cấp nội dung hoặc cung cấp nội dung trống. Các trường khác sẽ được giữ nguyên với điều kiện là các trường đó không xuất hiện trong updateMask.

Để sử dụng updateMask trong yêu cầu products.custombatch, bạn phải chỉ định updateMask trong nội dung yêu cầu.

Ví dụ được trình bày sẽ cập nhật price và availability của "Áo phông Google màu đen" hiện có bằng products.custombatch với dữ liệu sản phẩm được cung cấp trong mục nhập hàng loạt, giữ nguyên tất cả các trường khác, bao gồm cả title và description.

POST https://shoppingcontent.googleapis.com/content/v2.1/products/batch

{
  "entries": [{
    "batchId": 1,
    "merchantId": "MERCHANT_ID",
    "productId": "online:en:US:1111111111",
    "method": "update",
    "product": {
      "title": "Google Tee Black",
      "description": "The Black Google Tee is available in unisex sizing.",
      "availability": "in stock",
      "price": {
        "value": "19.99",
        "currency": "USD"
      }
    },
    "updateMask": "availability,price"
  }]
}

products.delete

Để xoá một sản phẩm, hãy sử dụng products.delete với URL yêu cầu HTTP mẫu, mã người bán và mã sản phẩm (ở định dạng mã nhận dạng REST, chẳng hạn như online:en:US:1111111111) cho sản phẩm mà bạn muốn xoá:

DELETE https://shoppingcontent.googleapis.com/content/v2.1/{merchantId}/products/{productId}

Phản hồi thành công sẽ trả về HTTP Status 204 mà không có nội dung phản hồi.

products.list

products.list liệt kê tất cả sản phẩm mà người bán có trong cơ sở dữ liệu của Merchant Center. Sử dụng URL yêu cầu sau:

GET https://shoppingcontent.googleapis.com/content/v2.1/{merchantId}/products

Lệnh gọi thành công sẽ trả về HTTP 200 và dữ liệu JSON cho các sản phẩm trong khoá "resources".

Ba sản phẩm mẫu sau đây sẽ được trả về:

{
 "kind": "content#productsListResponse",
 "resources": [
  {
   "kind": "content#product",
   "id": "online:en:US:1111111111",
   "offerId": "1111111111",
   "source": "api",
   "title": "Google Tee Black",
   "description": "The Black Google Tee is available in unisex sizing.",
   "link": "http://my.site.com/blacktee/",
   "imageLink": "https://shop.example.com/.../images/GGOEGXXX1100.jpg",
   "contentLanguage": "en",
   "targetCountry": "US",
   "feedLabel": "US",
   "channel": "online",
   "ageGroup": "adult",
   "availability": "in stock",
   "availabilityDate": "2019-01-25T13:00:00-08:00",
   "brand": "Google",
   "color": "black",
   "condition": "new",
   "gender": "male",
   "googleProductCategory": "1604",
   "gtin": "608802531656",
   "itemGroupId": "google_tee",
   "mpn": "608802531656",
   "price": {
    "value": "21.99",
    "currency": "USD"
   },
   "sizes": [
    "Large"
   ]
  },
  {
   "kind": "content#product",
   "id": "online:en:US:2222222222",
   "offerId": "2222222222",
   "source": "api",
   "title": "Google Tee Green",
   "description": "100% cotton jersey fabric sets this Google t-shirt above the crowd.
    Features the google logo across the chest. Unisex sizing.",
   "link": "http://my.site.com/greentee/",
   "imageLink": "https://shop.example.com/.../images/GGOEGXXX0906.jpg",
   "contentLanguage": "en",
   "targetCountry": "US",
   "feedLabel": "US",
   "channel": "online",
   "ageGroup": "adult",
   "availability": "in stock",
   "availabilityDate": "2019-01-25T13:00:00-08:00",
   "brand": "Google",
   "color": "green",
   "condition": "new",
   "gender": "male",
   "googleProductCategory": "1604",
   "gtin": "608802531649",
   "itemGroupId": "google_tee",
   "mpn": "608802531649",
   "price": {
    "value": "21.99",
    "currency": "USD"
   },
   "sizes": [
    "Medium"
   ]
  },
  {
   "kind": "content#product",
   "id": "online:en:US:3333333333",
   "offerId": "3333333333",
   "source": "api",
   "title": "Google Twill Cap",
   "description": "Classic urban styling distinguishes this Google cap.
    Retains its shape, even when not being worn.",
   "link": "http://my.site.com/blackhat/",
   "imageLink": "https://shop.example.com/.../images/GGOEGHPB071610.jpg",
   "contentLanguage": "en",
   "targetCountry": "US",
   "feedLabel": "US",
   "channel": "online",
   "ageGroup": "adult",
   "availability": "in stock",
   "availabilityDate": "2019-01-07T13:00:00-08:00",
   "brand": "Google",
   "color": "black",
   "condition": "new",
   "gender": "male",
   "googleProductCategory": "173",
   "gtin": "689355417246",
   "mpn": "689355417246",
   "price": {
    "value": "10.99",
    "currency": "USD"
   },
   "sizes": [
    "Medium"
   ]
  }
 ]
}

ID sản phẩm

Tiếp

Chế độ hàng loạt