Войти

Добро пожаловать в Центр поддержки

Получите помощь с интеграцией и запущенными кампаниями.

Добро пожаловать в Центр поддержки. Получите помощь с интеграцией и запущенными кампаниями.

Руководство по API для Criteo Resellers Program V2.0

 

Журнал изменений руководства

Версия

Дата релиза

Внести изменения

V1.0 Ноябрь 2017 Релиз первой версии.
V1.1 Март 2018 Отчеты об уровне показов добавлены в руководство.
V1.2 Сентябрь 2018 Новые параметры фильтрации добавлены в руководство.
V2.0 Сентябрь 2018

Демо-версия руководства API V2, чтобы наши клиенты успели во всем разобраться.В данном руководстве содержатся подробные сведения о новой опции создания ежедневного бюджета.

 

 

О настоящем документе

Этот документ поможет вам разобраться с интеграцией нашего Criteo REST API.Благодаря нашему новому API V2.0, вы сможете вести кампании Criteo Reseller Program от лица ваших магазинов-партнеров.Данное руководство поможет вам ознакомиться с изменениями, которые вам необходимо произвести для API V2.

Вы сможете ознакомиться с нашими основными функциями, которые позволят вам - от лица ваших партнерев – делать следующее:
  • Создание и обновление бюджетов
  • Создание и обновление ставки за клик (CPC)
  • Приостановить магазины-партнёры
  • Получить статистику для магазинов-партнёров

Начало работы

Для работы с нашим REST API вам понадобится создать нового пользователя API в Management Center.Платформа доступна по ссылке: https://marketing.criteo.com/

После входа выполните следующие действия.

  • Щелкните «Установка > Пользователи».

 

 

  • Кликните на СОЗДАТЬ API ПОЛЬЗОВАТЕЛЯ

 

  • Вам потребуется ввести email адрес пользователя и выбрать одну из следующих ролей: только просмотр, бизнес менеджер, финансовый менеджер.Чтобы использовать наш API, пожалуйста, выберите роль Business Manager.Для ролей только просмотр и финансовый менеджер недоступен обмен данными через наш API.
  • После завершения щелкните Добавить пользователя. Вы получите сообщение с подтверждением, свой Идентификатор клиента и Секретный код клиента. Храните их в надежном месте, поскольку они понадобятся вам, чтобы создавать запросы в нашем API.

валюта

Все суммы, указанные в Criteo REST API, указаны в местной валюте, в том числе:

  • показатели результативности (например, стоимость продажи (COS), расходы и т. д.);
  • бюджеты и ставки,

ПРИМЕЧАНИЕ. Местную валюту можно проверить с помощью вашего интерфейса Criteo Management Center. В меню «Настройка» нажмите пункт «Пользователи» и выберите нужного пользователя.

Часовой пояс

Все даты в Criteo REST API отображаются в соответствии со временем по Гринвичу (UTC).

Обновление данных

Остаток бюджета и статистика не отображаются в реальном времени. Задержка может составлять до нескольких часов.Следовательно, магазин-партнер может быть неактивным, но его оставшийся бюджет может продолжать уменьшаться.Реклама магазина-партнера больше не отображается, но остаток бюджета уменьшится после обновления статистики.

Рекомендации по использованию API

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

Один вызов следует выполнить для ставок, а другой — для бюджетов.Оба вызова будут содержать правильные ставки и бюджеты для одной или нескольких кампаний.

Пример Вам необходимо задать ставки и бюджеты для 10 разных магазинов-партнеров.Мы рекомендуем отправить один вызов API для кампании партнера и один вызов для бюджетов; при этом оба вызова должны содержать требуемые ставки и бюджеты для соответствующих партнеров.

Технические составляющие

Все технические компоненты и точки вызова являются новыми для версии V2 данной документации.Для сравнения вы можете ознакомиться с нашим swagger V1 по ссылке:

https://api.criteo.com/marketing/swagger

В данном Swagger можно найти следующие endpoints.

  • Аутентификация: позволяет вам получить токен.В целях безопасности, токен действителен в течение 5 минут.
  • Портфолио: позволяет получать основную информацию, например ваш AdvertiserID и Advertiser Name.
  • Партнёры
    • GET /v2/crp/sellers: получить основную информацию о магазинах-партнерах
    • POST /v2/crp/statistics: получить основные данные о статистике кампании
  • Бюджет
    • GET /v2/crp/budgets : получить данные о состоянии и оставшемся объёме бюджета
    • POST /v2/crp/budgets: создать бюджет для магазина-партнера
    • PUT /v2/crp/budgets : обновить бюджет для магазина-партнера
  • Кампании партнёров
    • GET/v2/crp/seller-campaign : получить данные о ставках кампании магазина-партнера
    • PUT /v2/crp/seller-campaigns: укажите ставку за клик (CPC) для магазина-партнёра в рамках кампании

Пожалуйста, обратите внимание, что как Sellers, так и Sellers-campaign, создаются автоматически на основе импорта каталога, поэтому для них не предполагаются POST-вызовы.

ПРИМЕР: Данный Swagger привязан к рабочей среде Criteo.Таким образом, любые применяемые тесты будут влиять на реальные кампании.

Обзор API

Ниже вы найдете ключевые инструкции по программе Criteo Reseller Program REST API для управления ставками и бюджетами на уровне магазина-партнера.

Первые шаги

Как аутентифицировать API?

Criteo использует JWT для того, чтобы обеспечить для ваших REST API систему аутентификации, основанную на токенах.Чтобы отправлять вызовы нашему API, необходимо передать токен в любой из этих вызовов.

Для получения токена нужно создать вызов POST для «/oauth2/token», используя client_id и client_secret в качестве параметров (см. раздел «Начало работы»).

Примечание: Каждый токен действителен в течение 5 минут.Если срок действия вашего токена истек, вы получите код статуса ответа 401 HTTP.

Как узнать свой AdvertiserID?

Чтобы получить свой AdvertiserID, необходимо произвести вызов GET для «/portfolio/».

Как получить свой Catalog ID?

Получите свой CatalogID с помощью вызова GET для «/v2/crp/sellers».

Как узнать свой CampaignID?

Получите свой CampaignID при помощи вызова GET для «/v2/crp/seller-campaigns».

Управление партнерами

Как добавить магазин-партнёр в программу Criteo Reseller?

Шаг 1: Чтобы добавить нового партнера (магазин), следует убедиться, что он надлежащим образом отмечен в товарном фиде, который вы ранее предоставили Criteo.

Чтобы убедиться, что ваш магазин-партнер отмечен корректно, необходимо задать в столбце seller name уникальный идентификатор партнёра, который является названием магазина, для каждого товара этого партнёра в вашем фиде.

СОВЕТ:Магазин-партнёр станет активным в программе, как только вы начнете передавать нам доступные товары этого магазина в фиде.

С этого момента начнётся размещение партнеров, для любой из ваших CRP кампаний будут созданы seller-campaigns.

Шаг 2: Вы можете получить доступ к seller ID и seller-campaign ID с помощью вызова GET /v2/crp/seller-campaigns

Шаг 3: Вы сможете предоставить нам бюджет и ставки ваших партнёров при помощи описанных выше вызовов, в частности:

  • POST /v2/crp/budgets отправить нам бюджет партнера - Теперь данный бюджет может быть задействован в нескольких кампаниях данного партнёра
  • PUT /v2/crp/seller-campaigns установить ставку за клик для кампании данного партнёра

Совет: Вы можете получить полный список магазинов-партнёров с указанием их статуса (активен/неактивен), выполнив вызов GET для партнёра, указав свой идентификатор каталога Criteo Reseller Program (catalogId) в качестве параметра.

Как удалить данные магазина-партнера из Criteo Resellers Program?

Если вы хотите удалить магазин-партнер из Criteo Reseller Program, вам нужно остановить бюджет этого партнера, выполнив вызов PUT /v2/crp/budgets со статусом = Остановлен.

В качестве альтернативы, вы можете просто удалить товары этого партнера из вашего фида.Однако, данные изменения вступят в силу только после того, как Criteo обработает фид и список партнёров.Добавление партнера обратно займет больше времени по той же причине: системе необходимо загрузить новый фид и обработать список партнёров.Criteo не рекомендует данный вариант.

Удаление магазина-партнера из фида не повлияет на статистику данного партнера.

Управление рекламными кампаниями

Как запустить кампанию?

Перед запуском кампании Criteo Reseller Program вы должны отправить нам фид, содержащий товары всех магазинов-партнёров, участвующих в программе.Обратите внимание, что каждый из этих товаров должен иметь уникальный идентификатор партнёра в соответствующем параметре.Ваша кампания будет создана автоматически сразу же после обработки вашего фида.

Для активации кампании требуется как минимум один партнер, для которого уже установлены бюджет и ставка.Однако, мы не рекомендуем запуск с таким малым количеством партнеров.Кампании CRP предназначены для работы с сотнями и тысячами партнеров.

Совет: Если вы уже работаете с Criteo, у вас есть следующие опции:

  • Рекомендуется: вы можете обновить свой существующий фид, добавив информацию о магазинах-партнёрах в соответствующий параметр (если вы не используете все 3 категории в настоящее время).
  • Или вы можете дублировать уже отправленный нам фид, добавив в него уникальный идентификатор магазина-партнёра в соответствующем параметре.
    • В данном случае, пожалуйста, обсудите выставление счетов для вашей кампании.Идеальным будет вариант, если мы сможем интегрировать эту новую кампанию CRP в ваш текущий биллинг.

Ваша кампания будет создана автоматически после обработки вашего фида.Для активации кампании требуется как минимум один партнер, для которого уже установлены бюджет и ставка.Однако, мы не рекомендуем запуск с таким малым количеством партнеров.Кампании CRP предназначены для работы с сотнями и тысячами партнеров.

Вы можете отправить их через вызовы POST /v2/crp/budgets и PUT /v2/crp/seller-campaigns.

Как остановить кампанию?

Чтобы остановить кампанию Criteo Reseller Program целиком (для всех магазинов-партнеров), свяжитесь с вашим аккаунт-стратегом.

Как остановить размещение рекламы для магазина-партнёра?

Чтобы остановить размещение рекламы для одного или нескольких партнёров в рамках вашей кампании, установите статус «Остановлен» для их бюджетов.

Как только вы деактивируете их бюджеты, система сразу же остановит показ рекламы товаров данных партнеров.

Чтобы установить для бюджета значение “Остановлен”, выполните вызов PUT для /sellers/budgets как PUT /v2/crp/budgets со статусом status = Остановлен.

Примечание:пазмещение партнера, бюджет которого имеет статус «Остановлен», невозможно возобновить.Если вы хотите заново запустить показ рекламы для партнера, бюджет которого имеет статус «Остановлен», вам необходимо будет создать для него новый бюджет (см. раздел «Как создать новый бюджет»).

После того, как вы остановите бюджет, вы можете увидеть, что он продолжает тратиться. Так происходит потому, что обновление статистики может занимать несколько часов.Например, если бюджет был приостановлен на сумме $10, размещение рекламы прекратиться, но могут быть некоторые остаточные расходы.Таким образом, конечная сумма остатка бюджета составит, например, 9,50$.

Что делать с партнером, бюджет которого практически израсходован?

Вам не нужно предпринимать какие-либо действия. Мы отслеживаем расходование бюджета по всем магазинам-партнерам и приостанавливаем их размещение, если их бюджет заканчивается.

Как задавать бюджеты и CPC?

Чтобы задать бюджет и ставки для конкретного партнера, необходимо использовать следующие вызовы:

  • Бюджеты:
    • Для инициализации: выполните вызов POST для /v2/crp/budget
    • Для обновления: выполните вызов PUT для /v2/crp/budget
  • Ставки за клик: для инициализации и обновления выполните вызов PUT для /v2/crp/seller-campaign

Как увеличить бюджет или CPC?

Чтобы увеличить бюджет или CPC для конкретного партнера, необходимо произвести вызов PUT для /v2/crp/budget и для v2/crp/seller-campaign.

Как снизить CPC?

Если ваш магазин-партнёр хочет снизить цену за клик (CPC), необходимо выполнить вызов POST для v2/crp/seller-campaign.

Как сократить бюджет?

Если ваш партнёр хочет сократить бюджет, следует задать для него статус «Остановлен» — это остановит показы на текущем бюджете в день (D), когда вы выполните данное действие.Далее вы можете создать новый бюджет, меньшего объема (см. раздел «Как создать новый бюджет»). Новый бюджет активируется на следующий день (D+1), время по UTC.

Пример.

День 0 : магазин-партнёр А изначально установил бюджет в $1000.

День 2. У партнера A остался бюджет в размере $800, но он принимает решение сократить бюджет до $500.

В этом случае необходимо создать следующие вызовы:

  • Вызов PUT для /v2/crp/budgets
    • Установка статуса «Остановлен»
    • (Необязательно точно указывать сумму бюджета, budgetStatusимеет приоритетное значение);
  • Вызов POST для конечной точки /v2/crp/budgets
    • Задайте для параметра amount } значение 500
    • (Необязательно точно указывать значение status в этом случае; если оставить поле пустым, считается, что выбрано значение Активен)

ВАЖНО! Обратите внимание, что любое сокращение бюджета учитывается немедленно со следующим эффектом:

  • Размещение магазина-партнера будет мгновенно приостановлено до конца дня по всем кампаниям, которые для него запущены.
  • Партнёр перезапустится на следующий день в 00:00 по времени UTC с новым значением бюджета для всех кампаний, которые для него запущены.

Как создать новый бюджет?

Вы можете создать новый бюджет, если выполняется одно из двух условий:

  • У вас нет действующего бюджета для данного магазина-партнера на текущий день.Наша система не допускает пересечения бюджетов.
  • У вас есть бюджет в статусе DEPLETED для данного магазина-партнёра.

Чтобы создать новый бюджет для магазина-партнера, вам необходимо:

  • Выполнить вызов POST для /v2/crp/budgets

Изменения бюджета вступят в силу:

  • Сегодня, если бюджет ещё не был определён для магазинов-партнёров.
  • Завтра, если бюджет уже существует.

Один из моих магазинов-партнеров по ошибке установил неверный бюджет.Как это исправить?

Для начала необходимо, чтобы ваш партнер предоставил вам обновленный бюджет. Затем есть три основных сценария, которые приводят к различным действиям:

  • У вас уже имеется новый бюджет, и он меньше изначально установленного бюджета:
    • Выполните действия, указанные в разделе «Как уменьшить бюджет или CPC?».
  • У вас уже имеется новый бюджет, и он больше изначально установленного бюджета:
    • Выполните действия, указанные в разделе «Как увеличить бюджет или CPC?».
  • У вас нет нового или правильного бюджета:
    • Выполните действия, описанные в разделе «Как остановить размещение магазина-партнера?».

Один из моих магазинов-партнеров по ошибке установил неверную ставку за клик.Как я могу это исправить?

Для начала необходимо, чтобы ваш партнёр предоставил вам обновленную ставку за клик (CPC).Затем следует произвести вызов PUT для v2/crp/seller-campaigns, чтобы задать обновленную ставку.

Что делать, если один из моих магазинов-партнёров изменил название на моей платформе?

Поскольку наш API фактически использует sellerName – имя партнера – в ходе управления ставками и бюджетами, любое изменение имени продавца или партнера автоматически приведет к созданию новой записи в нашей системе, не привязанной к предыдущему имени партнера. По сути, если продавец или партнер изменит свое имя на вашей платформе, вам потребуется:

  • обновить свой фид, указав новое значение sellerName;
  • Произвести инициализацию ставки за клик и бюджета партнёра с помощью отправки нам вызова PUT для /v2/crp/seller-campaigns и вызова POST для /v2/crp/budgets

ПРИМЕЧАНИЕ: вы сможете получить статистику по предыдущему значению sellerName посредством вызова «statistics».

Как я могу увидеть бюджет, израсходованный партнером?

Чтобы просмотреть израсходованный бюджет для конкретного партнера из кампании Criteo Reseller Program, выполните вызов GET для /v2/crp/budgets.Информация будет доступна в виде параметра spentAmount.

Как я могу увидеть остаток бюджета для моих партнёров?

Чтобы просмотреть израсходованный бюджет для конкретного партнера по кампании Criteo Reseller Program, выполните вызов GET для /v2/crp/budgets.

Информация будет доступна в виде параметра remainingamount.

Что означают различные статусы моего бюджета?

  • Running: текущий
  • Depleted : бюджет был израсходован и нам пришлось приостановить размещение рекламы данного партнера
  • Остановлен: вы остановили размещение рекламы данного партнера вручную
  • Ended : вы установили дату окончания действия для данного бюджета - Дата окончания действия уже наступила
  • Scheduled : вы установили дату начала действия для данного бюджета и она еще не наступила

Могу ли я запланировать начало действия бюджета на более позднюю дату?

Да, вы можете создать бюджет, который будет активирован в будущем, указав дату начала его действия.Действие бюджета начнется в полночь, время по GMT.

Могу ли я выбрать дату окончания действия для своего бюджета?

Да, вы можете определить дату окончания действия вашего бюджета.Действие бюджета прекратится в 23:59 по GMT.На следующий день для данного бюджета автоматически установится статус DEPLETED.

Могу ли я установить ежедневный бюджет?

К сожалению, пока такой опции нет.Тем не менее, вы сможете настроить тип бюджета = DAILY и указывать его размер в будущем.Мы работаем над запуском данной функции. Функция будет доступна в первом квартале 2019 года.Срок действия бюджета не определяется в договоре.

Могу ли я отфильтровать свои вызовы, касающиеся бюджетов партнеров?

Да, можете! Ниже представлены доступные фильтры:

  • /v2/crp/sellers
    • Для вызова «sellers» - Вы можете установить фильтр по статусу вызова (Available/NotAvailable) и seller id
  • /v2/crp/seller-campaigns
    • Для вызова «seller-campaigns» - Вы можете отфильтровать вызовы по campaign id и seller id
  • /v2/crp/budgets
    • Для бюджетов - По статусу

Отчеты

Вы можете выполнить вызов POST для /v2/crp/statistics.Анализировать число показов, кликов и затраты можно только на уровне партнёра с детализацией по дням.

Помимо двух основных параметров seller id и campaign id вы можете также использовать один дополнительный параметр.

Параметры:

  • идентификатор рекламодателя;
  • CampaignID - Обязательный
  • Seller ID - Обязательный
  • неделя
  • день

Доступные показатели:

  • Показы
  • Клики
  • Стоимость для рекламодателя

Дисплей: Поскольку на баннере может быть несколько магазинов-партнеров, система использует того партнера, чей товар был просмотрен последним.

Была ли эта статья полезной?
Пользователи, считающие этот материал полезным: 0 из 0
На базе технологии Zendesk