商品標註

您可以使用 Instagram 圖形 API 在 Instagram Business 的 IG 影音素材中建立和管理 Instagram 購物商品標籤。

注意：自 2023 年 8 月 10 日起，部分未啟用結帳功能的商店的企業將無法再使用內容發佈 API 標註其商品。這將影響 API 和原生介面，且將刪除以前貼文中的商品標籤。顧客仍可以在 Facebook 和 Instagram 啟用結帳功能的情況下標註商店中的商品。您仍然可以參考 shopping_product_tag_eligibility 欄位，檢查 Instagram 帳戶是否有資格使用內容發佈 API 標記其產品。

標註商品的一般流程如下：

檢查 Instagram Business 是否具備商品標註的資格。
如果 Instagram Business 符合資格，則取得其商品目錄。
在每個目錄中搜尋符合標註資格的產品。
建立標註影音素材容器。
發佈標註影音素材容器。

限制

所有內容發佈限制皆適用於商品標註。
限時動態和直播不支援商品標註。
Instagram 創作者帳號不支援商品標註。
帳號限制在 24 小時期間內只能發佈 25 篇標註影音素材貼文。輪播廣告相簿計為單一貼文。

必備條件

請參閱每個端點的參考文件，確定每項操作所需的權限、功能和用戶存取權杖。
擁有 IG 影音素材（待標註）的 Instagram 商業帳號（IG 用戶）必須具備獲得核准的 Instagram 商店，其中具有包含產品的商品目錄。支援應用程式內部和外部 Instagram 商店結帳方式。
應用程式用戶必須在擁有 Instagram 商店的企業管理平台中擔任管理員角色，而該商店的產品正用於標註影音素材。
若要申請應用程式審查核准 instagram_shopping_tag_products 和 catalog_management 權限（多個商品標註端點的必備條件），應用程式必須與已驗證的商家相關聯。

端點

GET /{ig-user-id} - 檢查應用程式用戶的標註資格。
GET /{ig-user-id}/available_catalogs - 取得應用程式用戶的商品目錄清單。
GET /{ig-user-id}/catalog_product_search - 取得應用程式用戶目錄中符合標籤條件的產品清單。
POST /{ig-user-id}/media - 建立標註影音素材容器（發佈程序的步驟 1）。
POST /{ig-user-id}/media_publish - 發佈標註影音素材容器（發佈程序的步驟 2）。
GET /{ig-media-id}/product_tags - 取得已發佈 IG 影音素材的標籤。
DELETE /{ig-media-id}/product_tags - 刪除已發佈 IG 影音素材的標籤。
POST /{ig-media-id}/product_tags - 建立或更新已發佈 IG 影音素材的標籤。
GET /{ig-user-id}/product_appeal - 取得產品申訴資訊。
POST /{ig-user-id}/product_appeal - 對產品拒絕提出申訴。
GET /{ig-media-id}/children - 取得輪播廣告 IG 影音素材中的子 IG 影音素材清單。

取得用戶資格

要求 IG 用戶端點的 shopping_product_tag_eligibility 欄位，判定 Instagram 商業帳號是否已設定 Instagram 商店。尚未設定 Instagram 商店的帳號不符合商品標註的資格。

GET /{ig-user-id}?fields=shopping_product_tag_eligibility

如果 Instagram 商業帳號已經與企業管理平台核准的 Instagram 商店相關聯，系統便會傳回 true，否則會傳回 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"
}

取得目錄

使用 IG 用戶可用目錄端點取得 Instagram 商業帳號的商品目錄。

GET /{ig-user-id}/available_catalogs

傳回目錄的陣列及其中繼資料。回應可以包括下列目錄欄位：

catalog_id – 目錄編號。
catalog_name – 目錄名稱。
shop_name – 商店名稱。
product_count – 目錄中的產品總數。

限制

不支援協作目錄，例如購物合作夥伴目錄或聯盟行銷創作者目錄。

要求範例

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"
}

取得合格的產品

使用 IG 用戶目錄產品搜尋端點取得目錄中可用於標註影音素材的產品精選集。支援產品款式。

發佈標註未經核准產品的貼文時，API 並不會傳回錯誤，但是在產品獲得核准之前，標籤不會顯示在已發佈的貼文。因此，建議只有在貼文包含產品的 review_status 為 approved 的標籤時，才允許應用程式用戶發佈。依預設，在您取得應用程式用戶的合格產品時，系統將為每個產品傳回此欄位。

GET /{ig-user-id}/catalog_product_search

參數

catalog_id –（必填）目錄編號。
q – 要在每個產品的名稱或產品的 SKU 號碼（目錄管理介面中的內容編號欄位）中搜尋的字串。如果未指定字串，系統將傳回所有符合標註資格的產品。

傳回含有符合標註資格的產品陣列及其中繼資料的物件。支援游標型的分頁。回應可以包括下列產品欄位：

image_url – 產品圖像網址。
is_checkout_flow – 若為 true，則可以直接在 Instagram 應用程式中購買產品。若為 false，則必須在應用程式用戶的應用程式／網站購買產品。
merchant_id - 商家編號。
product_id – 產品編號。
product_name – 產品名稱。
retailer_id – 零售商編號。
review_status - 審查狀態。數值可為 approved、outdated、pending、rejected。已核准的產品可以顯示在應用程式用戶的 Instagram 商店中，但已核准的狀態並不表示供貨現況（例如，產品可能缺貨）。只有與 review_status 為 approved 的產品相關聯的標籤，才能顯示在已發佈的貼文。
product_variants – 產品款式的產品編號（product_id）和款式名稱（variant_name）。

要求範例

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"
            }
          ]
    }
  ]
}

為圖像或影片建立標註容器

使用 IG 用戶影音素材端點建立圖像或影片的影音素材容器。或者，請參閱為連續短片建立標註影音素材容器或輪播廣告。

POST /{ig-user-id}/media

參數

image_url –（僅限圖像為必填）圖像的路徑。影像必須是在公開伺服器上。
user_tags –（僅限圖像）公開用戶名稱和您想在圖像中標註的任何公開 Instagram 用戶的 x／y 座標的陣列。陣列必須採用 JSON 格式，並包含 username、x 和 y 屬性。例如，[{username:'natgeo',x:0.5,y:1.0}]。x 和 y 的值必須為從圖像左上角開始，範圍介於 0.0 至 1.0 的浮點數。標註的用戶將在系統發佈影音內容時收到通知。
video_url –（僅限影片為必填）影片的路徑。影片必須是在公開伺服器上。
thumb_offset –（僅限影片）影片封面縮圖圖像的影格位置，單位為毫秒。預設值為 0，亦即影片的第一個影格。
product_tags –（必填）指定要加入到圖像或影片的商品標註的物件陣列。最多可以為相片和影片動態消息貼文指定 20 個標籤，每個輪播廣告貼文最多可以指定共 20 個標籤（每個輪播廣告輕影片最多可以指定 5 個標籤）。
- 標籤和商品編號必須是唯一的。
- 支援缺貨產品的標籤。
- 每個物件應包含下列資訊：
  - product_id –（必填）產品編號。
  - x –（僅限圖像）表示與已發佈影音素材圖像左邊緣的百分比距離的浮點數。數值必須在 0.0 至 1.0 範圍內。
- y –（僅限圖像）表示與已發佈影音素材圖像上邊緣的百分比距離的浮點數。數值必須在 0.0 至 1.0 範圍內。

如果操作成功，API 將傳回容器編號，其可用於發佈容器。

要求範例

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..."

以下為 HTML 解碼的 POST 承載字串參考：

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"
}

為連續短片建立標註容器

使用 IG 用戶影音素材發佈端點建立連續短片的影音素材發佈容器。或者，請參閱建立標註影音素材容器或輪播廣告。

POST /{ig-user-id}/media

參數

media_type — 您必須指定媒體類型 REELS。
video_url — 連續短片影片的路徑。影片必須是在公開伺服器上。影片必須符合連續短片規格。
thumb_offset — 影片封面縮圖圖像的影格位置，單位為毫秒。預設值為 0，亦即影片的第一個影格。
caption — 連續短片的說明文字。
product_tags —（必填）指定要加入到連續短片的商品標註的物件陣列。最多可以指定 30 個標籤，標籤和商品編號必須是唯一的。支援缺貨產品的標籤。每個物件應包含下列資訊：
- product_id –（必填）產品編號。
location_id — 與您想標註影片的位置相關聯的粉絲專頁的編號。如需詳細資訊，請參閱 IG 用戶影音素材查詢字串參數。
share_to_feed — true 要求影片出現在動態消息和連續短片頁籤上。false 要求影片僅出現在連續短片頁籤上。
access_token — 您的用戶存取權杖。

如果操作成功，API 將傳回容器編號，其可用於發佈容器。

要求範例

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..."

以下為 HTML 解碼的 POST 承載字串參考：

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"
}

發佈標註影音素材容器

使用 IG 用戶影音素材發佈端點發佈標註影音素材容器。在 24 小時移動期間內，您可以代表應用程式用戶發佈最多 25 個標註影音素材容器。如果您要發佈輪播廣告，請參閱輪播廣告。只有 review_status 為 approved 的產品才會顯示在已發佈的貼文。如果這些產品中有任何一種缺貨，其標籤仍將顯示在已發佈的貼文。

POST /{ig-user-id}/media_publish

參數

creation_id –（必填）輪播廣告容器編號。

如果操作成功，API 將傳回 IG 影音素材編號。

要求範例

curl -i -X POST \
 "https://graph.facebook.com/v19.0/90010177253934/media_publish?creation_id=17969578066508312&access_token=EAAOc"

回應範例

{
  "id": "90010778325754"
}

取得影音素材的標籤

使用 IG 影音素材商品標籤端點取得已發佈影音素材的標籤。

GET /{ig-media-id}/product_tags

傳回 IG 影音素材的商品標籤陣列及其中繼資料。回應可以包括以下商品標籤欄位：

product_id - 產品編號。
merchant_id – 商家編號。
name – 產品名稱。
price_string – 產品價格。
image_url - 產品圖像網址。
review_status – 指示商品標籤資格狀態，可為以下值：
approved - 系統已核准產品。
rejected – 系統已拒絕產品。
pending – 系統仍在審查中。
outdated – 商品已獲得批准，但經過編輯，需要重新批准。
"" – 沒有審查狀態。
no_review – 沒有審查狀態。
is_checkout – 若為 true，則可以直接經由 Instagram 應用程式購買產品。若為 false，則只能在商家網站購買產品。
stripped_price_string – 產品短價格字串（價格以有限空間方式顯示，例如 $100 而不是 100 USD）。
string_sale_price_string – 產品促銷價格。
x – 表示與影音素材圖像左邊緣的百分比距離的浮點數。數值在 0.0 至 1.0 範圍內。
y – 表示與影音素材圖像上邊緣的百分比距離的浮點數。數值在 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
    }
  ]
}

標註現有影音素材

使用 IG 影音素材商品標籤端點建立或更新現有 IG 影音素材的標籤。

POST /{ig-media-id}/product_tags

參數

updated_tags –（必填）指定要用來標註圖像或影片的商品標籤的物件陣列（最多 5 個；標籤和產品編號必須不重複）。每個物件應包含下列資訊：
product_id –（必填）產品編號。如果系統未使用此編號標註 IG 影音素材，會將標籤新增至 IG 影音素材。如果系統已使用此編號標註影音素材，將會更新標籤的顯示座標。
x –（僅限圖像，必填）表示與已發佈影音素材圖像左邊緣的百分比距離的浮點數。數值必須在 0.0 至 1.0 範圍內。
y –（僅限圖像，必填）表示與已發佈影音素材圖像上邊緣的百分比距離的浮點數。數值必須在 0.0 至 1.0 範圍內。

在到達 5 個標籤限制之前，標註影音素材會累加。如果有產品已在要求中標註目標影音素材，系統將使用新值更新舊標籤的 x 和 y 值（不會新增標籤）。

如果能夠更新產品，會傳回 true，否則將傳回 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..."

以下為 HTML 解碼的 POST 承載字串參考：

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
}

刪除標籤

使用 IG 影音素材商品標籤端點刪除已發佈 IG 影音素材（包含連續短片）的標籤。

DELETE /{ig-media-id}/product_tags

參數

deleted_tags –（必填）包含下列每個要刪除之商品標籤資訊的陣列：
merchant_id –（必填）商家編號。
product_id –（必填）產品編號。

如果標籤刪除成功，會傳回 true，否則將傳回 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..."

以下為 HTML 解碼的 POST 承載字串參考：

https://graph.facebook.com/v12.0/90010778325754/product_tags?deleted_tags=[ { product_id:'3859448974125379', merchant_id:'90010177253934' } ]&access_token=EAAOc...

回應範例

{
  "success": true
}

對產品拒絕提出申訴

如果要為應用程式用戶提供對產品拒絕（遭拒絕產品的標籤不會顯示在已發佈的貼文）提出申訴的方法，請使用 IG 用戶產品申訴端點。雖然此為非必要，但仍建議您為應用程式用戶提供對拒絕提出申訴的方法，或建議他們使用企業管理平台對拒絕提出申訴。

POST /{ig-user-id}/product_appeal

參數

appeal_reason –（必填）解釋產品應獲得核准的理由。
product_id –（必填）產品編號。

如果我們能夠接收要求，會傳回 true，否則將傳回 false。回覆不表示申訴結果。

要求範例

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
}

取得申訴狀態

使用 IG 用戶產品申訴端點取得特定遭拒絕產品的申訴狀態：

GET /{ig-user-id}/product_appeal

參數

product_id –（必填）產品編號。

傳回申訴狀態中繼資料。回應可以包括下列申訴欄位：

eligible_for_appeal – 指示是否可對決定提出申訴（如果為 true，則為是，如果為 false，則為否）。
product_id – 產品編號。
review_status – 審查狀態。可為以下值：
approved – 系統已核准產品。
rejected – 系統已拒絕產品。
pending – 系統仍在審查中。
outdated – 商品已獲得批准，但經過編輯，需要重新批准。
"" – 沒有審查狀態。
no_review – 沒有審查狀態。

要求範例

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
    }
  ]
}

輪播廣告

您可以發佈輪播廣告（相簿），其中包含最多總數 10 個標註圖像、影片或兩者的混合。若要這樣做，在執行輪播廣告貼文發佈程序的第 1／3 步驟時，只需為要顯示在相簿輪播廣告中的每個標註圖像或影片建立標註的影音素材容器，然後以正常方式繼續輪播廣告發佈程序。

在輪播廣告中取得子影音素材

若要在相簿輪播廣告中取得 IG 影音素材的編號，請使用 IG 影音素材子端點。