Добавление меток товаров

С помощью API Graph для Instagram можно создавать метки товаров Instagram Shopping для объектов IG Media в Instagram Business и управлять ими.

Примечание. С 10 августа 2023 г. некоторые компании, у которых нет магазинов с оформлением заказов, не смогут создавать метки для своих товаров с помощью API Content Publishing. Это затронет как API, так и нативный интерфейс. Все метки товаров в предыдущих публикациях будут удалены. Клиенты по-прежнему смогут отмечать товары из Магазинов, в которых включено оформление заказа на Facebook и в Instagram. Поле shopping_product_tag_eligibility по-прежнему можно использовать для проверки того, может ли аккаунт Instagram задавать метки товаров с помощью Content Publishing API.

Общая процедура добавления меток товаров:

Проверьте, может ли Instagram Business отмечать товары.
Если да, получите его каталоги товаров.
Найдите в каждом каталоге товары, которые можно отмечать.
Создайте контейнер медиафайла с меткой.
Опубликуйте контейнер медиафайла с меткой.

Ограничения

Все ограничения на публикацию контента действуют и для меток товаров.
В историях и прямых эфирах отмечать товары нельзя.
Кроме того, отметка товаров не поддерживается для аккаунтов авторов.
За каждые 24 часа в аккаунте можно разместить не более 25 публикаций с метками. Альбомы кольцевой галереи считаются одной публикацией.

Требования

Чтобы определить, какие разрешения, функции и маркеры доступа пользователя требуются для каждой операции, см. справку по каждой конечной точке.
Аккаунт Instagram Business (IG User), который владеет IG Media (предназначенным для маркировки), должен иметь утвержденный Instagram Магазин с каталогом, в котором имеются товары. Поддерживаются способы оформления заказа с использованием приложения и внешнего Instagram Магазина.
Пользователь приложения должен иметь роль администратора в том Business Manager, который владеет 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 — создает контейнер медиафайла с меткой (первый шаг процесса публикации).
POST /{ig-user-id}/media_publish — публикует контейнер медиафайла с меткой (второй шаг процесса публикации).
GET /{ig-media-id}/product_tags — получает метки опубликованных объектов IG Media.
DELETE /{ig-media-id}/product_tags — удаляет метки на опубликованных объектах IG Media.
POST /{ig-media-id}/product_tags — создает или обновляет метки на опубликованных объектах IG Media.
GET /{ig-user-id}/product_appeal — получает информацию об обжаловании отклонения товара.
POST /{ig-user-id}/product_appeal — подает обжалование отклонения товара.
GET /{ig-media-id}/children — получает список дочерних объектов IG Media кольцевой галереи.

Проверка пользователя

Запросите поле shopping_product_tag_eligibility на конечной точке IG User, чтобы определить, есть ли у аккаунта Instagram Business настроенный Instagram Магазин. Если у аккаунта нет магазина в Instagram, он не может отмечать товары.

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

Возвращает true, если аккаунт Instagram Business связан с утвержденным Instagram Магазином, который принадлежит Business Manager; в противном случае возвращается значение 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"
}

Получение каталога

Чтобы получить каталог товаров, принадлежащий аккаунту Instagram Business, отправьте запрос к конечной точке доступных каталогов IG User.

GET /{ig-user-id}/available_catalogs

Запрос возвращает массив каталогов и их метаданных. Ответ может содержать эти поля каталога:

catalog_id — ID каталога.
catalog_name — имя каталога.
shop_name — название магазина.
product_count — общее количество товаров в каталоге.

Ограничения

Партнерские каталоги, такие как каталоги партнеров по Instagram Shopping или каталоги авторов партнерского контента, не поддерживаются.

Пример запроса

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 User. Варианты товаров поддерживаются.

При создании публикации, в которой отмечен неутвержденный товар, 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 Магазине, однако это одобрение не означает, что товар доступен (например, его может не быть на складе). В публикациях могут присутствовать метки только тех товаров, поле 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 User Media. Вы также можете создать контейнеры медиафайлов с меткой для Reels или кольцевых галерей.

POST /{ig-user-id}/media

Параметры

image_url — путь к изображению. Обязательный параметр (только для изображений). Изображение должно находиться на общедоступном сервере.
user_tags — массив общедоступных имен пользователей и координат x/y общедоступных пользователей Instagram, которых вы хотите отметить на изображении. Только для изображений. Массив должен быть в формате JSON и содержать свойства usernamex и 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 на каждый слайд галереи).
- Метки и 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..."

Пример строки полезной нагрузки POST, раскодированный для HTML:

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

Создание контейнера с меткой для видео Reels

Чтобы создать контейнер медиафайла для видео Reels, отправьте запрос к конечной точке IG User Media. Вы также можете создать контейнеры медиафайлов с меткой для публикаций или кольцевых галерей.

POST /{ig-user-id}/media

Параметры

media_type — необходимо указать тип медиафайла REELS.
video_url — путь к видео Reels. Видео должно находиться на общедоступном сервере. Видео должно отвечать требованиям к видео Reels.
thumb_offset — кадр (в миллисекундах) видео, который должен использоваться в качестве миниатюры для него. Значение по умолчанию — 0, то есть первый кадр видео.
caption — подпись к контейнеру видео Reels.
product_tags — массив объектов, определяющих метки товаров, которые добавляются в видео Reels. Обязательный параметр. Можно указать до 30 меток. Метки и ID товаров должны быть уникальными. Метки товаров, которых нет на складе, также поддерживаются. Для каждого объекта должна быть указана следующая информация:
- product_id — ID товара. Обязательный параметр.
location_id — ID Страницы, связанной с местом, которое вы хотите отметить в видео. Подробнее см. в документации по параметрам строк запросов к IG User Media.
share_to_feed: если задано значение true, видео появится на вкладках "Лента" и Reels. Если задано значение false, видео появится только на вкладке Reels.
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..."

Пример строки полезной нагрузки POST, раскодированный для HTML:

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 User Media Publish. В течение каждых 24 часов от имени пользователя приложения можно публиковать до 25 таких контейнеров. Если вы публикуете кольцевую галерею, обратитесь к разделу Кольцевые галереи. В публикациях появятся метки только тех товаров, у которых поле review_status содержит значение approved. Если каких-либо из этих товаров нет в наличии, их метки всё равно появятся в размещенной публикации.

POST /{ig-user-id}/media_publish

Параметры

creation_id — ID контейнера кольцевой галереи. Обязательный параметр.

Если операция выполнена успешно, API вернет ID IG Media.

Пример запроса

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

Пример ответа

{
  "id": "90010778325754"
}

Получение меток в медиафайлах

Чтобы получить метки в опубликованных медиафайлах, отправьте запрос к конечной точке IG Media Product Tags.

GET /{ig-media-id}/product_tags

Возвращает массив меток товаров и их метаданных для объекта IG Media. Ответ может содержать эти поля меток товара:

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 вместо 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 Media Product Tags, чтобы создать или обновить метки к опубликованным объектам IG Media.

POST /{ig-media-id}/product_tags

Параметры

updated_tags — массив объектов, указывающий, какие метки товаров нужно добавить к изображению или видео (не более пяти меток; метки и идентификаторы товаров должны быть уникальными). Обязательный параметр. Каждый объект должен включать в себя следующее:
product_id — ID товара. Обязательный параметр. Если объект IG Media не отмечен этим 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..."

Пример строки полезной нагрузки POST, раскодированный для HTML:

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 Media, в том числе видео Reels, отправьте запрос к конечной точке IG Media Product Tags.

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

Пример строки полезной нагрузки POST, раскодированный для HTML:

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

Пример ответа

{
  "success": true
}

Обжалование отклонения товара

Отправьте запрос к конечной точке IG User Product Appeal, если вы хотите предоставить пользователям вашего приложения способ обжаловать отклонения товаров (метки отклоненных товаров не появятся в размещенных публикациях). Хотя это не является обязательным, мы настоятельно рекомендуем вам обеспечить своим пользователям инструмент для обжалования отклонения товаров или предложить им обжаловать отклонения с использованием Business Manager.

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 User Product Appeal, чтобы получить статус обжалования определенного отклоненного товара:

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 изображений, видео или сочетания изображений и видео с метками. Чтобы сделать это, на шаге 1 из 3 процесса размещения публикаций с кольцевыми галереями просто создайте контейнеры медиафайлов с метками для каждого отмеченного меткой изображения или видео, которое должно появиться в альбоме кольцевой галереи, а затем продолжите процесс публикации кольцевой галереи в обычном режиме.

Получение дочерних объектов кольцевой галереи

Чтобы получить ID объекта IG Media в альбоме кольцевой галереи, отправьте запрос к конечной точке IG Media Children.