제품 태그

Instagram 그래프 API를 사용하여 Instagram 비즈니스의 IG 미디어에서 Instagram 쇼핑 제품 태그를 만들고 관리할 수 있습니다.

참고: 2023년 8월 10일부터 결제가 활성화된 Shop이 없는 일부 비즈니스는 더 이상 콘텐츠 게시 API를 사용하여 제품을 태그할 수 없게 됩니다. 이 변경 사항은 API와 네이티브 인터페이스에 영향을 미치고, 이전의 게시물에 있는 제품에서 태그가 삭제됩니다. 고객은 여전히 Facebook과 Instagram에서 결제가 활성화된 Shop에서 제품을 태그할 수 있습니다. shopping_product_tag_eligibility 필드를 참조하여 Instagram 계정이 콘텐츠 게시 API를 사용하여 제품을 태그할 수 있는지 여부는 여전히 확인이 가능합니다.

제품을 태그하기 위한 일반 플로는 다음과 같습니다.

Instagram 비즈니스가 제품을 태그할 수 있는지 확인합니다.
Instagram 비즈니스에서 태그가 가능할 경우 제품 카탈로그를 가져옵니다.
태그가 가능한 제품의 각 카탈로그를 검색합니다.
태그된 미디어 컨테이너를 만듭니다.
태그된 미디어 컨테이너를 게시합니다.

제한 사항

모든 콘텐츠 게시 제한 사항이 제품 태그에 적용됩니다.
제품 태그는 스토리와 라이브에서 지원되지 않습니다.
제품 태그는 Instagram 크리에이터 계정에서는 지원되지 않습니다.
계정은 24시간 이내에 태그된 미디어 게시물을 최대 25개까지 게시할 수 있습니다. 슬라이드 사진첩은 하나의 게시물로 간주됩니다.

요구 사항

각 엔드포인트의 참고 문서를 참조하여 각 작업에 어떤 권한, 기능, 사용자 액세스 토큰이 필요한지 확인하세요.
(태그할) IG 미디어를 소유하는 Instagram 비즈니스 계정(IG 사용자)은 제품이 포함된 제품 카탈로그가 있는 승인된 Instagram Shop이 있어야 합니다. 앱 내 및 외부 Instagram Shop 결제 수단이 지원됩니다.
앱 사용자는 미디어를 태그하는 데 사용하는 제품이 있는 Instagram Shop을 소유하는 비즈니스 관리자에 대해 관리자 권한이 있어야 합니다.
여러 제품 태그 엔드포인트에서 필요한 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 Shop을 설정했는지 확인합니다. Instagram Shop을 설정하지 않은 계정은 제품을 태그할 수 없습니다.

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

Instagram 비즈니스 계정이 비즈니스 관리자의 승인된 Instagram Shop과 연결되어 있을 경우 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 — 카탈로그 ID
catalog_name — 카탈로그 이름
shop_name — Shop 이름
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 — (필수) 카탈로그 ID.
q — 각 제품의 이름이나 제품의 SKU 번호에서 검색할 문자열(카탈로그 관리 인터페이스의 콘텐츠 ID 열). 문자열을 지정하지 않는 경우 태그할 수 있는 모든 제품이 반환됩니다.

태그할 수 있는 제품과 해당 메타데이터의 배열을 포함하는 개체를 반환합니다. 커서 기반 페이지 매김을 지원합니다. 응답은 다음의 제품 필드를 포함할 수 있습니다.

image_url — 제품 이미지 URL.
is_checkout_flow — true인 경우 Instagram 앱에서 직접 제품을 구매할 수 있습니다. false인 경우 앱 사용자의 앱/웹사이트에서 제품을 구매해야 합니다.
merchant_id — 판매자 ID.
product_id — 제품 ID.
product_name — 제품 이름.
retailer_id — 판매점 ID.
review_status — 검토 상태. 값은 approved, outdated, pending, rejected일 수 있습니다. 승인된 제품은 앱 사용자의 Instagram Shop에 표시될 수 있지만 승인된 상태라고 하더라도 제품을 사용할 수 있다는 의미는 아닙니다(예: 제품이 품절될 수 있음). review_status가 approved인 제품과 연결된 태그만 게시된 게시물에 표시할 수 있습니다.
product_variants — 제품 에디션의 제품 ID(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개까지 지정할 수 있고 슬라이드 게시물 1개에 태그를 20개(슬라이드 1개당 최대 5개)까지 지정할 수 있습니다.
- 태그와 제품 ID는 고유해야 합니다.
- 품절 제품의 태그가 지원됩니다.
- 각 개체는 다음 정보를 포함해야 합니다.
  - product_id — (필수) 제품 ID.
  - x — (이미지 전용) 게시된 미디어 이미지의 왼쪽 가장자리에서부터의 비율 거리를 나타내는 부동 소수점. 값은 0.0~1.0 범위 이내여야 합니다.
- y — (이미지 전용) 게시된 미디어 이미지의 위쪽 가장자리에서부터의 비율 거리를 나타내는 부동 소수점. 값은 0.0~1.0 범위 이내여야 합니다.

작업이 성공할 경우 API는 컨테이너를 게시하는 데 사용할 수 있는 컨테이너 ID를 반환합니다.

요청 샘플

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개의 태그를 지정할 수 있으며 태그와 제품 ID는 고유해야 합니다. 품절 제품의 태그가 지원됩니다. 각 개체는 다음 정보를 포함해야 합니다.
- product_id — (필수) 제품 ID.
location_id — 동영상에 태그하고자 하는 위치와 관련된 페이지의 ID. 자세한 내용은 IG 사용자 미디어 쿼리 문자열 매개변수를 참조하세요.
share_to_feed — 피드 및 릴스 탭에 동영상이 모두 표시되도록 요청하려면 true로 설정합니다. 릴스 탭에만 동영상이 표시되도록 요청하려면 false로 설정합니다.
access_token — 사용자 액세스 토큰.

작업이 성공할 경우 API는 컨테이너를 게시하는 데 사용할 수 있는 컨테이너 ID를 반환합니다.

요청 샘플

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 — (필수) 슬라이드 컨테이너 ID.

작업이 성공할 경우 API는 IG 미디어 ID를 반환합니다.

요청 샘플

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 — 제품 ID.
merchant_id — 판매자 ID.
name — 제품 이름.
price_string — 제품 가격.
image_url — 제품 이미지 URL.
review_status — 제품 태그 가능 상태를 나타냅니다. 다음과 같은 값을 사용할 수 있습니다.
approved — 제품이 승인되었습니다.
rejected — 제품이 거부되었습니다.
pending — 아직 검토 중입니다.
outdated — 제품이 승인되었지만 수정되었으므로 재승인이 필요합니다.
"" — 검토 상태가 없습니다.
no_review — 검토 상태가 없습니다.
is_checkout — true인 경우 Instagram 앱에서 직접 제품을 구매할 수 있습니다. false인 경우 판매자의 웹사이트에서만 제품을 구매할 수 있습니다.
stripped_price_string — 축약된 제품 가격 문자열(가격이 제한된 공간에 표시됨(예: 100 USD 대신 $100)).
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개, 태그 및 제품 ID는 고유해야 함). 각 개체는 다음 정보를 포함해야 합니다.
product_id — (필수) 제품 ID. IG 미디어가 이 ID로 태그되지 않은 경우 해당 태그가 IG 미디어에 추가됩니다. 미디어가 이미 이 ID로 태그된 경우 태그의 표시 좌표가 업데이트됩니다.
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 — (필수) 판매자 ID.
product_id — (필수) 제품 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 — (필수) 제품 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 — (필수) 제품 ID.

재고 요청 상태 메타데이터를 반환합니다. 응답은 다음의 재고 요청 필드를 포함할 수 있습니다.

eligible_for_appeal — 결정 사항에 대해 재고 요청을 할 수 있는지 여부를 나타냅니다(true이면 가능, false이면 불가능).
product_id — 제품 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개까지 포함하는 슬라이드(사진첩)를 게시할 수 있습니다. 이를 위해서는 슬라이드 게시물 게시 절차의 3단계 중 1단계를 수행할 때 사진첩 슬라이드에 표시할 각각의 태그된 이미지 또는 동영상에 대해 태그된 미디어 컨테이너를 만들고 평소와 같이 슬라이드 게시 절차를 계속 진행하면 됩니다.

슬라이드에서 하위 미디어 가져오기

사진첩 슬라이드에서 IG 미디어의 ID를 가져오려면 IG 하위 미디어 엔드포인트를 사용합니다.