Партнерства в Marketplace

Marketplace Partner Item API

Став партнером Marketplace, вы сможете размещать в Marketplace объявления о продаже товаров в определенных странах.

Для загрузки, обновления или удаления товаров в Facebook Marketplace вы будете использовать интерфейс Graph API.

HTTP
POST /v20.0/{product-catalog-id}/items_batch HTTP/1.1

Об использовании Graph API см. в этом руководстве.

При публикации на этой границе контекста создается товар.

Параметры

Параметр	Описание
item_type	Установите значение PRODUCT_ITEM
requests	Метод и поля для каждого товара в массиве товаров.

В параметре requests вы определяете метод и данные для своего запроса.

Поле	Описание
method	Действие, которое вы хотите выполнить в отношении данного товара. Варианты: CREATE (СОЗДАТЬ) UPDATE (ОБНОВИТЬ) DELETE (УДАЛИТЬ)
data	Информация о товаре, которую вы хотите создать, обновить или удалить.

Пример параметра requests

[
    {
        "method": "CREATE",
        "data": {
            "id": "UniqueProductID",
            "title": "Title",
            "description": "This is the description",
            "price": "100 USD",
            "image_link": "https:\/\/www.facebook.com",
            "brand": "Monster",
            "availability": "in stock",
            "condition": "new",
            "link": "https:\/\/www.facebook.com",
            "return_details": {"return_days": "30", "return_type": "SELLER_PAID_RETURN"},
            "partner_product_checkout_uri": "https:\/\/www.facebook.com",
            "partner_product_location": "San Fransisco, CA",
            "partner_product_expiration_time": "1923181264",
            "partner_delivery_method": ["shipping"],
            "partner_shipping_type": "fixed",
            "partner_shipping_cost": "14.95",
            "partner_shipping_speed": "3:5",
            "partner_attribute_data": {"color": "blue"},
            "partner_seller_id": "MySellerId1",
            "partner_item_country": "US"
        }
    },
    .... {next product}
]

Ограничение числа обращений для API

Чтобы избежать регулирования:

Количество вызовов не должно превышать 30 в минуту. Если оно будет больше, включится механизм регулирования.
Добавляйте несколько объектов (до 300) в один вызов API.

Поля товаров

Параметр	Тип	Обязательно/необязательно	Описание
`id`	Строка (не длиннее 100 символов)	Обязательно	Уникальный ID контента для товара. Если это возможно, используйте SKU товара. Каждый ID контента должен отображаться в каталоге только один раз. Если есть несколько экземпляров одного и того же ID, все такие экземпляры будут игнорироваться. Если товары доступны в нескольких странах, вы должны использовать один и тот же ID во всех каталогах. Укажите цену в валюте страны (см. поле price).
`title`	Строка (не длиннее 200 символов)	Обязательно	Название товара, которое показывается в объявлении в Marketplace. Этот текст будет показываться в Marketplace. Не добавляйте HTML-теги.
`description`	Строка (не длиннее 9 999 символов)	Обязательно	Описание товара. В это поле помещается 9 999 символов, но в объявлении в Facebook Marketplace будут видны только первые 256. Этот текст будет показываться в Marketplace. Не добавляйте HTML-теги. Пример: "Комфортная женская футболка ярко-синего цвета из органического хлопка. Короткий рукав. Свободная посадка. Идеально подходит для лета".
`condition`	Перечисление enum {new, refurbished, used, used_like_new, used_good, used_fair, cpo, open_box_new}	Обязательно	Состояние товара.
`partner_listing_type`	Перечисление enum {fixed_price, auction, vehicle, rental, real_estate}	Необязательно	Определяет тип объявления. Если ничего не выбрано, по умолчанию указано значение "fixed_price". Если задано значение "auction", "vehicle", "rental" или "real_estate", то покупателям на Marketplace будет предоставлен выбранный тип объявления партнера.
`partner_product_condition`	Перечисление enum {acceptable, brand_new, certified_pre_owned, certified_refurbished, damaged, digital_good, excellent_refurbished, for_parts_or_not_working, good, good_refurbished, graded, like_new, new, new_other, new_other_see_details, new_with_box, new_with_defects, new_with_tags, open_box, others, pre_owned, remanufactured, retread, seller_refurbished, ungraded, used, very_good, very_good_refurbished, new_open_box, open_box_used, new_factory_sealed, unknown}	Необязательно	Дополнительная информация о состоянии товара. Необязательное поле, которое переопределит поле condition. Используется, если нужно уточнить состояние товара.
`brand`	Строка	Обязательно	Бренд товара. Если бренд отсутствует, задайте значение "N/A".
`price`	Строка (не длиннее 9 999 символов)	Обязательно	Укажите цену в виде числа, за которым следует пробел и трехбуквенный код валюты по стандарту ISO 4217. Пример: 10,99 EUR Если тип объявления "auction", указывайте цену как текущую ставку на товар. Укажите цену в виде числа, за которым следует пробел и трехбуквенный код валюты по стандарту ISO 4217.
`availability`	Перечисление enum {in stock, out of stock}	Обязательно	Наличие товара.
`link`	Строка	Обязательно	URL веб-страницы со сведениями о товаре, оптимизированный для мобильных устройств.
`partner_product_checkout_uri`	Строка	Необязательно	URL для оформления заказа, который отправляется пользователю, после того как он нажмет кнопку "Купить" в объявлении. Мы добавим в параметр идентификатор click_id. Если поле не заполнено, используется URL из поля "link".
`partner_product_html_desc_uri`	Строка	Необязательно	URL сайта с полным описанием товара. Используется, если длина описания товара превышает ограничение для поля "description". Marketplace сможет предоставлять ссылку на полное описание.
`image_link`	Строка	Обязательно	URL основного изображения товара. Изображения должны быть в формате JPEG или PNG, иметь разрешение как минимум 500 × 500 пикселей и размер до 8 МБ. Требования к изображению товара см. здесь.
`partner_seller_id`	Строка (не длиннее 100 символов)	Обязательно	Уникальный идентификатор продавца. Должен совпадать со значением поля partner_seller_id из информации о продавце. Пример: "partner_seller_id": "great_seller_inc".
`partner_item_country`	Перечисление enum {AT, BE, BG, CY, CZ, DE, DK, EE, ES, FI, FR, GR, HR, HU, IE, IS, IT, LI, LT, LU, LV, MT, NL, NO, PL, PT, RO, SE, SI, SK}	Обязательно	Страна, в которой товар доступен (если применимо) и в которую может быть отправлен. Страна в каталоге и параметр partner_item_country должны совпадать. Если для товаров доступна международная доставка, требуется создать по одному товару в каталоге для каждой страны, где поддерживается доставка и куда партнер планирует доставлять товары.
`fb_product_category`	Строка	Необязательно	Категория товара на Facebook. Наиболее подходящая категория товара на Facebook из списка в формате электронной таблицы (.csv) или простого текста (.txt).
`status`	Перечисление enum {active, archived}	Необязательно	Текущий статус товара.
`sale_price`	Строка	Необязательно	Укажите цену в виде числа, за которым следует пробел и трехбуквенный код валюты по стандарту ISO 4217. Пример: 10,99 EUR. Это тот же формат, что и в поле price. Используется вместе с полем price для показа скидок.
`sale_price_effective_date`	Строка	Необязательно	Даты начала и окончания распродажи, разделенные косой чертой. Формат даты: ГГГГ-ММ-ДД. После каждой даты добавьте "T" и укажите время. Формат времени: 24-часовой (от 0:00 до 23:59). Пример: 2014-11-01T12:00-0300/2014-12-01T00:00-0300.
`additional_image_link`	Строка (не длиннее 2 000 символов)	Необязательно	URL дополнительных изображений товара (до 20), разделенные запятой (,), точкой с запятой (;), пробелом ( ) или вертикальной чертой (\|). Следуйте тем же требованиям к изображениям, что и для поля image_link.
`return_details`	Объект JSON { “return_days”: 30, “return_type”: enum }, допускающий значение null (например, карта) Перечисление enum: FINAL_SALE NO_RETURNS_WITH_EXCEPTION NO_RETURNS SELLER_PAID_RETURN BUYER_PAID_RETURN Если возврат недоступен: "return_details": null	Необязательно	return_days — количество дней, в течение которых покупатель должен инициировать возврат товара. При наличии NO_RETURNS и FINAL_SALE у параметра return_days должно быть значение -1. return_type — поддерживаемый тип возврата товара. Доступные варианты: FINAL_SALE, NO_RETURNS_WITH_EXCEPTION, NO_RETURNS, SELLER_PAID_RETURN, BUYER_PAID_RETURN Если оставить это поле пустым, сведения о возврате не будут показываться.
`partner_attribute_data`	Объект JSON { “color”: “blue” }, допускающий значение null Доступные ключи: aspect_ratio, band_material, bike_type, brand, break_type, cable_length, capacity, case_size, certification, character, circulated_uncirculated, closure, color, compatible_bike_type, compatible_brand, compatible_model, compatible_operating_system, compatible_product, connectivity, credit_included, denomination, department, display_technology, dress_length, exterior_color, exterior_material, fabric_type, features, film_format, fit, focal_length, focus_type, form_factor, format, frame_color, game_name, game, gauge, golf_club_type, handedness, inseam, internet_connectivity, item_height, item_length, item_weight, item_width, items_included, main_stone, manufacturer_part_number, manufacturer, material, maximum_aperture, maximum_magnification, maximum_resolution, memory_cards_supported, metal_purity, metal, model, mount, mpn, network, number_of_items, occasion, outer_shell_material, package_quantity, part_type, pattern, performance_activity, platform, processor, publication_name, quantity, rack_type, rim_diameter, rim_width, ring_size, screen_size, section_width, series, set_includes, set, size_type, size, skirt_length, sleeve_length, sport_activity, sport, storage_capacity, style, type, unit_quantity, unit_type, upper_material, us_shoe_size, vintage, voltage, volume, waist_size, wheel_diameter, year	Необязательно	Список атрибутов (ключей) со значениями, которые будут показываться в разделе сведений о товаре. Значения приводятся в формате строки. Ключи, применимые для продажи или аренды недвижимости: property_type (required), sale_type, bed_bath, area_size, pet_friendly, ac_type, heating_type, laundry_type, parking_type, parkingSpace, furnishing_type, garden_type, tenure_type, listed_by, property_tax_and_condo_fee, construction_status, lease_duration, energy_rating_eu, co2_emission_rating Ключи, применимые для транспортных средств: vehicle_type, year, make, model, number_of_owners, trim, body_style, exterior_color, interior_color, transmission, fuel_type, mileage, money_still_owed, motorcycle_type, engine_size
`partner_product_creation_time`	Метка времени UNIX в секундах UTC (число)	Необязательно	Метка времени UNIX, когда товар был создан или обновлен. Пример: "partner_product_creation_time": 1713917255
`partner_product_location`	Строка	Необязательно	Местоположение товара в виде строки. Пример: "Париж, Франция". Значение может быть максимально узким или широким.
`partner_product_expiration_time`	Метка времени UNIX в секундах UTC (число)	Необязательно	Время, в которое объявление будет удалено из Marketplace. Это должно быть время в будущем.
`partner_delivery_method`	Массив перечислений enum строки {shipping, in_person}	Необязательно	Определяет, как товар может быть доставлен покупателю. Если поддерживается доставка и самовывоз, включите оба значения. Пример: ["shipping","in_person"] По умолчанию: ["shipping"]
`partner_item_latitude`	Число с плавающей точкой	Необязательно	Географическая широта товара. Обязательный параметр, если способ доставки — "in_person".
`partner_item_longitude`	Число с плавающей точкой	Необязательно	Географическая долгота товара. Обязательный параметр, если способ доставки — "in_person".
`partner_shipping_type`	Перечисление enum {free, fixed, dynamic}	Необязательно	Стратегия стоимости доставки товара. Если доставка бесплатная, используйте значение "free". Если доставка осуществляется по фиксированной цене независимо от местоположения, используйте значение "fixed" и укажите цену в поле partner_shipping_cost. Если стоимость доставки зависит от местоположения покупателя, выбранного варианта и т. д., выберите значение "dynamic". В таком случае мы не будем показывать покупателю стоимость доставки, а сообщим, что информация о стоимости доставки появится во время оформления заказа. По умолчанию: "dynamic".
`partner_shipping_cost`	Число с плавающей точкой	Необязательно	Обязательный параметр, если для partner_shipping_type задано значение "fixed". Пример: "14,95"
`partner_shipping_speed`	Строка MIN_DELIVERY_SPEED_IN_DAYS:MAX_DELIVERY_SPEED_IN_DAYS	Необязательно	Минимальное и максимальное количество рабочих дней, в течение которых ожидается доставка товара. Пример: "3:5"
`partner_auction_bid_close_time`	Метка времени UNIX в секундах UTC (число)	Необязательно	Обязательный параметр, если для partner_listing_type задано значение "auction". Это время окончания приема ставок на товар. Пример: "partner_auction_bid_close_time": 1713917255
`partner_auction_bid_count`	Число	Необязательно	Применимо только в случае, если для partner_listing_type задано значение "auction". Это текущее количество сделанных ставок на товар.
`additional_fields`	Объект JSON, который может иметь значение null Свободная форма (без заданных перечислений или ключей) { "revised_title": "Premium Blue T-Shirt" }	Необязательно	Поле JSON в свободной форме, в котором партнеры могут отправлять дополнительные поля.

Проверка статуса загрузки

После отправки запроса на создание, обновление или удаление вам будет возвращен дескриптор. После этого вы сможете проверить результат отправки с помощью нового запроса.

По завершении операции в поле data > status будет установлено значение "finished", а также будут показаны ошибки и предупреждения.

HTTP
GET /v20.0/{product-catalog-id}/check_batch_request_status?handle={your handle}

Пример возвращаемой строки

{
  "data": [
    {
      "handle": "Acy3FUJwzE10XnWrYr4ttrjOAfs-h6BUg-Wtg6sWGeV7qZZaErX15XPfqT_KWeyC6T4-nTbng9r1BJuScb6hgO1B",
      "status": "finished",
      "errors_total_count": 0,
      "errors": [
      ],
      "warnings": [
        {
          "line": 1,
          "id": "YourItemID",
          "message": "These attributes are invalid and need to be updated in the feed file: The product_tags information under  is invalid. Review for more details"
        }
      ],
      "ids_of_invalid_requests": [
      ]
    }
  ],
  "__www_request_id__": "Az3ghYsDh-101IH2t6DXKuP"
}

Просмотр товаров и управление ими

Просмотреть загруженные товары и управлять ими можно в Commerce Manager. Здесь вы сможете увидеть и решить проблемы со своими товарами.