Bạn có thể dùng API Đồ thị trên Instagram để tạo và quản lý Thẻ sản phẩm trong tính năng Mua sắm trên Instagram thuộc File phương tiện trên Instagram của Doanh nghiệp trên Instagram.
Lưu ý: Kể từ ngày 10/08/2023, một số doanh nghiệp không có Cửa hàng đã bật tính năng thanh toán sẽ không thể gắn thẻ sản phẩm của họ bằng API Đăng nội dung nữa. Như vậy, cả API lẫn giao diện gốc đều sẽ bị ảnh hưởng, đồng thời thẻ sản phẩm sẽ bị gỡ khỏi các bài viết trước đây. Khách hàng vẫn có thể gắn thẻ sản phẩm từ Cửa hàng đã bật tính năng thanh toán trên Facebook và Instagram. Bạn vẫn có thể sử dụng trường shopping_product_tag_eligibility
để kiểm tra xem một tài khoản Instagram có đủ điều kiện gắn thẻ sản phẩm bằng API Đăng nội dung hay không.
Quy trình chung để gắn thẻ sản phẩm như sau:
instagram_shopping_tag_products
và catalog_management
(một số điểm cuối gắn thẻ sản phẩm cần có những quyền này), ứng dụng của bạn phải được liên kết với một doanh nghiệp đã được xác minh.GET /{ig-user-id}
- Kiểm tra điều kiện gắn thẻ của người dùng ứng dụng.GET /{ig-user-id}/available_catalogs
- Lấy danh sách các danh mục sản phẩm của người dùng ứng dụng.GET /{ig-user-id}/catalog_product_search
- Lấy danh sách các sản phẩm đủ điều kiện gắn thẻ trong danh mục của người dùng ứng dụng.POST /{ig-user-id}/media
- Tạo vùng chứa file phương tiện được gắn thẻ (bước 1 trong quy trình đăng).POST /{ig-user-id}/media_publish
- Đăng vùng chứa file phương tiện được gắn thẻ (bước 2 trong quy trình đăng).GET /{ig-media-id}/product_tags
- Lấy các thẻ trong File phương tiện đã đăng trên Instagram.DELETE /{ig-media-id}/product_tags
- Xóa các thẻ trong File phương tiện đã đăng trên Instagram.POST /{ig-media-id}/product_tags
- Tạo hoặc cập nhật các thẻ trong File phương tiện đã đăng trên Instagram.GET /{ig-user-id}/product_appeal
- Lấy thông tin kháng nghị về sản phẩm.POST /{ig-user-id}/product_appeal
- Kháng nghị quyết định từ chối sản phẩm.GET /{ig-media-id}/children
- Lấy danh sách File phương tiện trên Instagram thuộc File phương tiện quay vòng trên Instagram.Yêu cầu trường shopping_product_tag_eligibility
trên điểm cuối Người dùng Instagram để xác định xem tài khoản Kinh doanh trên Instagram đã thiết lập Cửa hàng trên Instagram hay chưa. Những tài khoản chưa thiết lập Cửa hàng trên Instagram sẽ không đủ điều kiện gắn thẻ sản phẩm.
GET /{ig-user-id}?fields=shopping_product_tag_eligibility
Trả về true
nếu Tài khoản kinh doanh trên Instagram đã liên kết với một Cửa hàng được phê duyệt trên Instagram trong Trình quản lý kinh doanh. Nếu không, hệ thống sẽ trả về false
.
curl -i -X GET \
"https://graph.facebook.com/v19.0
/90010177253934?fields=shopping_product_tag_eligibility&access_token=EAAOc..."
{ "shopping_product_tag_eligibility": true, "id": "90010177253934" }
Dùng điểm cuối Danh mục hiện có của người dùng Instagram để lấy danh mục sản phẩm của Tài khoản kinh doanh trên Instagram.
GET /{ig-user-id}/available_catalogs
Trả về một mảng danh mục và siêu dữ liệu của những danh mục này. Phản hồi có thể bao gồm các trường thông tin danh mục sau:
catalog_id
- ID danh mục.catalog_name
- Tên danh mục.shop_name
- Tên cửa hàng.product_count
- Tổng số sản phẩm trong danh mục.Danh mục mang tính cộng tác (chẳng hạn như danh mục của đối tác mua sắm hoặc danh mục của người sáng tạo nội dung liên kết tiếp thị) không được hỗ trợ.
curl -i -X GET \
"https://graph.facebook.com/v19.0
/90010177253934?fields=available_catalogs&access_token=EAAOc..."
{ "available_catalogs": { "data": [ { "catalog_id": "960179311066902", "catalog_name": "Jay's Favorite Snacks", "shop_name": "Jay's Bespoke", "product_count": 11 } ] }, "id": "90010177253934" }
Dùng điểm cuối Tìm kiếm sản phẩm trong danh mục của người dùng Instagram để lấy một bộ sưu tập sản phẩm trong danh mục đó mà bạn có thể dùng để gắn thẻ file phương tiện. Hỗ trợ mẫu mã sản phẩm.
Mặc dù API này sẽ không trả về lỗi khi đăng bài viết được gắn thẻ sản phẩm chưa phê duyệt, nhưng thẻ đó sẽ không hiển thị trên bài viết đã đăng cho đến khi sản phẩm được phê duyệt. Do đó, bạn chỉ nên cho phép người dùng ứng dụng đăng bài viết có thẻ sản phẩm mà review_status
của sản phẩm này là approved
. Theo mặc định, trường này được trả về cho mỗi sản phẩm khi bạn lấy các sản phẩm đủ điều kiện của người dùng ứng dụng.
GET /{ig-user-id}/catalog_product_search
catalog_id
- (bắt buộc) ID danh mục.q
- Chuỗi cần tìm kiếm trong từng tên sản phẩm hoặc số SKU của sản phẩm (cột ID nội dung trong giao diện quản lý danh mục). Nếu không có chuỗi nào được chỉ định, hệ thống sẽ trả về tất cả sản phẩm đủ điều kiện gắn thẻ. Trả về đối tượng chứa một mảng sản phẩm đủ điều kiện gắn thẻ và siêu dữ liệu của những sản phẩm này. Hỗ trợ phân trang dựa vào con trỏ. Phản hồi có thể bao gồm các trường thông tin sản phẩm sau:
image_url
- URL hình ảnh sản phẩm.is_checkout_flow
- Nếu giá trị là true
thì có thể mua sản phẩm trực tiếp trong ứng dụng Instagram. Nếu giá trị là false
thì phải mua sản phẩm trong ứng dụng/trang web của người dùng ứng dụng.merchant_id
- ID người bán.product_id
- ID sản phẩm.product_name
- Tên sản phẩm.retailer_id
- ID nhà bán lẻ.review_status
- Trạng thái xét duyệt. Giá trị có thể là approved
, outdated
, pending
, rejected
. Sản phẩm đã phê duyệt có thể hiển thị trong Cửa hàng trên Instagram của người dùng ứng dụng. Tuy nhiên, trạng thái đã phê duyệt không cho biết tình trạng hàng (ví dụ: sản phẩm có thể hết hàng). Chỉ những thẻ được liên kết với sản phẩm có review_status
là approved
mới hiển thị trên bài viết đã đăng.
curl -i -X GET \
"https://graph.facebook.com/v19.0
/90010177253934/catalog_product_search?catalog_id=960179311066902&q=gummy&access_token=EAAOc..."
{ "data": [ { "product_id": 3231775643511089, "merchant_id": 90010177253934, "product_name": "Gummy Wombats", "image_url": "https://scont...", "retailer_id": "oh59p9vzei", "review_status": "approved", "is_checkout_flow": true, "product_variants": [ { "product_id": 5209223099160494 }, { "product_id": 7478222675582505, "variant_name": "Green Gummy Wombats" } ] } ] }
Dùng điểm cuối File phương tiện của người dùng Instagram để tạo một vùng chứa file phương tiện cho hình ảnh hoặc video. Ngoài ra, hãy xem phần Tạo vùng chứa file phương tiện được gắn thẻ cho thước phim hoặc thẻ quay vòng.
POST /{ig-user-id}/media
image_url
- (chỉ bắt buộc đối với hình ảnh) Đường dẫn đến hình ảnh. Hình ảnh của bạn phải nằm trên máy chủ công khai.user_tags
- (chỉ hình ảnh) Một mảng tên người dùng công khai và tọa độ x/y cho bất kỳ người dùng Instagram công khai nào mà bạn muốn gắn thẻ trong hình ảnh. Mảng này phải ở định dạng JSON, đồng thời phải chứa thuộc tính username
, x
và y
. Ví dụ: [{username:'natgeo',x:0.5,y:1.0}]
. Các giá trị x
và y
phải là float (số thực) bắt nguồn từ phía trên cùng bên trái của hình ảnh và nằm trong khoảng 0.0
- 1.0
. Người dùng được gắn thẻ sẽ nhận được thông báo khi bạn đăng file phương tiện.video_url
- (chỉ bắt buộc đối với video) Đường dẫn đến video. Video của bạn phải nằm trên máy chủ công khai.thumb_offset
- (chỉ video) Vị trí (tính bằng mili giây) của khung hình dành cho ảnh bìa dạng thu nhỏ của video. Giá trị mặc định là 0
, đây là khung hình đầu tiên của video.product_tags
- (bắt buộc) Một mảng đổi tượng chỉ định các thẻ sản phẩm để thêm vào hình ảnh hoặc video. Bạn có thể chỉ định tối đa 20 thẻ cho bài viết có ảnh và video trên bảng feed và tổng cộng tối đa 20 thẻ cho mỗi bài viết có thẻ quay vòng (tối đa 5 thẻ cho mỗi trang chiếu quay vòng).
product_id
- (bắt buộc) ID sản phẩm.x
- (chỉ hình ảnh) Float (số thực) cho biết tỷ lệ phần trăm khoảng cách từ cạnh trái của hình ảnh file phương tiện đã đăng. Giá trị phải nằm trong khoảng 0.0
- 1.0
.y
- (chỉ hình ảnh) Float (số thực) cho biết tỷ lệ phần trăm khoảng cách từ cạnh trên cùng của hình ảnh file phương tiện đã đăng. Giá trị phải nằm trong khoảng 0.0
- 1.0
.Nếu thao tác này thành công, API sẽ trả về một ID vùng chứa mà bạn có thể dùng để đăng vùng chứa.
curl -i -X POST \
"https://graph.facebook.com/v19.0
/90010177253934/media?image_url=https%3A%2F%2Fupl...&location_id=7640348500&product_tags=%5B%0A%20%20%7B%0A%20%20%20%20product_id%3A'3231775643511089'%2C%0A%20%20%20%20x%3A%200.5%2C%0A%20%20%20%20y%3A%200.8%0A%20%20%7D%0A%5D&access_token=EAAOc..."
Bạn có thể tham khảo chuỗi phần tải dữ liệu POST được giải mã HTML dưới đây:
https://graph.facebook.com/v12.0/90010177253934/media?image_url=https://upl...&location_id=7640348500 &product_tags=[ { product_id:'3231775643511089', x: 0.5, y: 0.8 } ]&access_token=EAAOc...
{ "id": "17969578066508312" }
Dùng điểm cuối File phương tiện của người dùng Instagram để tạo vùng chứa file phương tiện cho thước phim. Ngoài ra, hãy xem phần Tạo vùng chứa file phương tiện được gắn thẻ hoặc Thẻ quay vòng.
POST /{ig-user-id}/media
media_type
- Bạn phải chỉ định loại file phương tiện REELS
.video_url
- Đường dẫn đến video cho Thước phim. Video của bạn phải nằm trên máy chủ công khai. Video của bạn phải đáp ứng Quy cách thước phim.thumb_offset
- Vị trí (tính bằng mili giây) của khung hình dành cho ảnh bìa dạng thu nhỏ của video. Giá trị mặc định là 0
, đây là khung hình đầu tiên của video.caption
- Chú thích cho Thước phim.product_tags
- (bắt buộc) Một mảng đối tượng chỉ định các thẻ sản phẩm để thêm vào Thước phim. Bạn có thể chỉ định tối đa 30 thẻ. Các thẻ và ID sản phẩm phải là duy nhất. Hỗ trợ thẻ cho sản phẩm hết hàng. Mỗi đối tượng phải chứa các thông tin sau:product_id
- (bắt buộc) ID sản phẩm.location_id
- ID của Trang liên kết với vị trí mà bạn muốn gắn thẻ video. Để biết chi tiết, hãy xem phần Thông số chuỗi truy vấn file phương tiện của người dùng Instagram.share_to_feed
- true
để yêu cầu video xuất hiện trên cả tab Bảng feed lẫn Reels. false
để yêu cầu video chỉ xuất hiện trên tab Reels.access_token
- Mã truy cập dành cho người dùng của bạn.Nếu thao tác này thành công, API sẽ trả về một ID vùng chứa mà bạn có thể dùng để đăng vùng chứa.
curl -i -X POST \
"https://graph.facebook.com/v19.0
/90010177253934/media?media_type=REELS&video_url=https://upl...&product_tags=%5B%0A%20%20%7B%0A%20%20%20%20product_id%3A'3231775643511089'%0A%20%20%7D%0A%5D&access_token=EAAOc..."
Bạn có thể tham khảo chuỗi phần tải dữ liệu POST được giải mã HTML dưới đây:
https://graph.facebook.com/v12.0/90010177253934/media?media_type=REELS&video_url=https://upl... &product_tags=[ { product_id:'3231775643511089' } ]&access_token=EAAOc...
{ "id": "17969578066508312" }
Dùng điểm cuối Đăng file phương tiện của người dùng Instagram để đăng vùng chứa file phương tiện được gắn thẻ. Bạn có thể thay mặt người dùng ứng dụng đăng tối đa 25 vùng chứa file phương tiện được gắn thẻ trong vòng 24 giờ. Nếu bạn đang đăng thẻ quay vòng, hãy xem phần Thẻ quay vòng. Chỉ những sản phẩm có review_status
là approved
mới hiển thị trên bài viết đã đăng. Nếu bất kỳ sản phẩm nào trong số này hết hàng, thẻ của sản phẩm đó vẫn sẽ hiển thị trên bài viết đã đăng.
POST /{ig-user-id}/media_publish
creation_id
- (bắt buộc) ID vùng chứa thẻ quay vòng.Nếu thao tác này thành công, API sẽ trả về một ID file phương tiện trên Instagram.
curl -i -X POST \
"https://graph.facebook.com/v19.0
/90010177253934/media_publish?creation_id=17969578066508312&access_token=EAAOc"
{ "id": "90010778325754" }
Dùng điểm cuối Thẻ sản phẩm trong file phương tiện trên Instagram để lấy các thẻ trong file phương tiện đã đăng.
GET /{ig-media-id}/product_tags
Trả về một mảng thẻ sản phẩm và siêu dữ liệu của những thẻ này trong File phương tiện trên Instagram. Phản hồi có thể bao gồm các trường thông tin thẻ sản phẩm sau:
product_id
- ID sản phẩm.merchant_id
- ID người bán.name
- Tên sản phẩm.price_string
- Giá sản phẩm.image_url
- URL hình ảnh sản phẩm.review_status
- Cho biết trạng thái đủ điều kiện của thẻ sản phẩm. Các giá trị có thể là:approved
- Sản phẩm được phê duyệt.rejected
- Sản phẩm đã bị từ chối.pending
- Vẫn đang xét duyệt.outdated
- Sản phẩm đã được phê duyệt nhưng chưa được chỉnh sửa và cần phải phê duyệt lại.""
- Không có trạng thái xét duyệt.no_review
- Không có trạng thái xét duyệt.is_checkout
- Nếu giá trị là true
thì có thể mua sản phẩm trực tiếp qua ứng dụng Instagram. Nếu giá trị là false
thì chỉ có thể mua sản phẩm trên trang web của người bán.stripped_price_string
- Chuỗi giá ngắn của sản phẩm (giá hiển thị trong không gian hạn chế, chẳng hạn như $100
thay cho 100 USD
).string_sale_price_string
- Giá khuyến mãi của sản phẩm.x
- Float (số thực) cho biết tỷ lệ phần trăm khoảng cách từ cạnh trái của hình ảnh file phương tiện. Giá trị nằm trong khoảng 0.0
- 1.0
.y
- Float (số thực) cho biết tỷ lệ phần trăm khoảng cách từ cạnh trên cùng của hình ảnh file phương tiện. Giá trị nằm trong khoảng 0.0
- 1.0
.
curl -i -X GET \
"https://graph.facebook.com/v19.0
/90010778325754/product_tags?access_token=EAAOc..."
{ "data": [ { "product_id": 3231775643511089, "merchant_id": 90010177253934, "name": "Gummy Wombats", "price_string": "$3.50", "image_url": "https://scont...", "review_status": "approved", "is_checkout": true, "stripped_price_string": "$3.50", "x": 0.5, "y": 0.80000001192093 } ] }
Dùng điểm cuối Thẻ sản phẩm trong file phương tiện trên Instagram để tạo hoặc cập nhật các thẻ trong File phương tiện trên Instagram hiện có.
POST /{ig-media-id}/product_tags
updated_tags
- (bắt buộc) Một mảng gồm các đối tượng chỉ định thẻ sản phẩm sẽ dùng để gắn thẻ hình ảnh hoặc video (tối đa 5 thẻ; các thẻ và ID sản phẩm phải là duy nhất). Mỗi đối tượng phải chứa các thông tin sau:product_id
- (bắt buộc) ID sản phẩm. Nếu File phương tiện trên Instagram chưa được gắn thẻ ID này, thẻ đó sẽ được thêm vào File phương tiện trên Instagram. Nếu file phương tiện đã được gắn thẻ ID này, tọa độ hiển thị của thẻ đó sẽ được cập nhật.x
- (chỉ hình ảnh, bắt buộc) Float (số thực) cho biết tỷ lệ phần trăm khoảng cách từ cạnh trái của hình ảnh file phương tiện đã đăng. Giá trị phải nằm trong khoảng 0.0
- 1.0
.y
- (chỉ hình ảnh, bắt buộc) Float (số thực) cho biết tỷ lệ phần trăm khoảng cách từ cạnh trên cùng của hình ảnh file phương tiện đã đăng. Giá trị phải nằm trong khoảng 0.0
- 1.0
.Hoạt động gắn thẻ file phương tiện sẽ được tính cộng cho đến khi đạt đến giới hạn 5 thẻ. Nếu file phương tiện được nhắm mục tiêu đã được gắn thẻ một sản phẩm trong yêu cầu, các giá trị x
và y
của thẻ cũ sẽ được cập nhật giá trị mới (không thêm thẻ mới).
Trả về true
nếu có thể cập nhật sản phẩm. Nếu không, hệ thống sẽ trả về false
.
curl -i -X POST \
"https://graph.facebook.com/v19.0
/90010778325754/product_tags?updated_tags=%5B%0A%20%20%7B%0A%20%20%20%20product_id%3A'3859448974125379'%2C%0A%20%20%20%20x%3A%200.5%2C%0A%20%20%20%20y%3A%200.8%0A%20%20%7D%0A%5D&access_token=EAAOc..."
Bạn có thể tham khảo chuỗi phần tải dữ liệu POST được giải mã HTML dưới đây:
https://graph.facebook.com/v12.0/90010778325754/product_tags?updated_tags=[ { product_id:'3859448974125379', x: 0.5, y: 0.8 } ]&access_token=EAAOc...
{ "success": true }
Dùng điểm cuối Thẻ sản phẩm trong file phương tiện trên Instagram để xóa các thẻ trong File phương tiện trên Instagram đã đăng có chứa Thước phim.
DELETE /{ig-media-id}/product_tags
deleted_tags
- (bắt buộc) Một mảng chứa các thông tin sau của mỗi thẻ sản phẩm cần xóa:merchant_id
- (bắt buộc) ID người bán.product_id
- (bắt buộc) ID sản phẩm.Trả về true
nếu xóa thẻ thành công. Nếu không, hệ thống sẽ trả về false
.
curl -i -X DELETE \
"https://graph.facebook.com/v19.0
/90010778325754/product_tags?deleted_tags=%5B%0A%20%20%7B%0A%20%20%20%20product_id%3A'3859448974125379'%2C%0A%20%20%20%20merchant_id%3A'90010177253934'%0A%20%20%7D%0A%5D&access_token=EAAOc..."
Bạn có thể tham khảo chuỗi phần tải dữ liệu POST được giải mã HTML dưới đây:
https://graph.facebook.com/v12.0/90010778325754/product_tags?deleted_tags=[ { product_id:'3859448974125379', merchant_id:'90010177253934' } ]&access_token=EAAOc...
{ "success": true }
Dùng điểm cuối Kháng nghị về sản phẩm của người dùng Instagram nếu bạn muốn cung cấp cho người dùng ứng dụng cách kháng nghị quyết định từ chối sản phẩm (thẻ của những sản phẩm bị từ chối sẽ không hiển thị trên bài viết đã đăng). Mặc dù không bắt buộc, nhưng bạn nên cung cấp cho người dùng ứng dụng cách kháng nghị quyết định từ chối hoặc khuyên họ làm vậy thông qua Trình quản lý kinh doanh.
POST /{ig-user-id}/product_appeal
appeal_reason
- (bắt buộc) Giải thích lý do sản phẩm nên được phê duyệt.product_id
- (bắt buộc) ID sản phẩm.Trả về true
nếu chúng tôi có thể nhận được yêu cầu mà bạn gửi. Nếu không, hệ thống sẽ trả về false
. Phản hồi không cho biết kết quả kháng nghị.
curl -i -X POST \
"https://graph.facebook.com/v19.0
/90010177253934/product_appeal?appeal_reason=product%20is%20a%20toy%20and%20not%20a%20real%20weapon&product_id=4382881195057752&access_token=EAAOc..."
{ "success": true }
Dùng điểm cuối Kháng nghị về sản phẩm của người dùng Instagram để lấy trạng thái kháng nghị của một sản phẩm bị từ chối nhất định:
GET /{ig-user-id}/product_appeal
product_id
- (bắt buộc) ID sản phẩm.Trả về siêu dữ liệu trạng thái kháng nghị. Phản hồi có thể bao gồm các trường thông tin kháng nghị sau:
eligible_for_appeal
- Cho biết liệu có thể kháng nghị quyết định hay không (có nếu giá trị là true
, không nếu giá trị là false
).product_id
- ID sản phẩm.review_status
- Trạng thái xét duyệt. Giá trị có thể là:approved
- Sản phẩm được phê duyệt.rejected
- Sản phẩm đã bị từ chối.pending
- Vẫn đang xét duyệt.outdated
- Sản phẩm đã được phê duyệt nhưng chưa được chỉnh sửa và cần phải phê duyệt lại.""
- Không có trạng thái xét duyệt.no_review
- Không có trạng thái xét duyệt.
curl -i -X GET \
"https://graph.facebook.com/v19.0
/90010177253934/product_appeal?product_id=4029274203846188&access_token=EAAOc..."
{ "data": [ { "product_id": 4029274203846188, "review_status": "approved", "eligible_for_appeal": false } ] }
Bạn có thể đăng thẻ quay vòng (album) chứa tổng cộng tối đa 10 hình ảnh, video được gắn thẻ hoặc kết hợp cả hai. Để đăng như vậy, khi thực hiện bước 1 trong 3 bước của quy trình đăng bài viết quay vòng, bạn chỉ cần tạo vùng chứa file phương tiện được gắn thẻ cho từng hình ảnh/video được gắn thẻ mà bạn muốn hiển thị trong album quay vòng rồi tiếp tục quy trình đăng thẻ quay vòng như cách bạn thường làm.
Để lấy ID của File phương tiện trên Instagram trong album quay vòng, hãy dùng điểm cuối File phương tiện con trên Instagram.