REST API Маркетгид для рекламодателей (русскоязычная версия)

REST API Маркетгид для рекламодателей (русскоязычная версия)

Содержание

Основные положения REST API

REST API Маркетгид  позволяет  интегрировать внешние приложения с системой  интернет-рекламы Маркетгид.

API дает возможность извлекать, добавлять и изменять данные. Практически   каждым объектом в Маркетгид (будь то клиент, рекламная компания, тизер и т.д.) можно  управлять с помощью API.

Запрос  Маркетгид REST API – это   HTTP запрос, в котором, с помощью  путей  в URL  задается объект для выполнения действия, а с помощью параметров передаются необходимые данные. Маркетгид API является "RESTful Web API".

Параметры запросов являются регистрозависимыми.

API использует  следующие команды REST:

  • GET
  • PUT
  • PATCH
  • POST
  • DELETE

Эти команды соответствуют определенным действия внутри системы Маркетгид.

Команда Действие Описание
POST Создать Создание новый элемента (например, тизера)
GET Получить (чтение) Получить элемент или коллекцию  элементов (например, список рекламных кампаний)
PUT Обновить Пересоздать существующий элемент или коллекцию элементов
PATCH Изменить Изменить определенные свойства элемента
DELETE Удалять Удалить элемент или коллекцию элементов (например, переместить тизер в корзину)

Важно! POST и PUT не являются взаимозаменяемыми.

Каждая из команд выполняет свою определенную функцию.

API Маркетгид URL

REST API Маркетгид для клиента доступен по адресу:

http://api.marketgid.com/v1

В общем виде запрос выглядит как

Идентификация

Для идентификации в REST API Маркетгид используется уникальный токен, состоящий из 32 символов и передаваемый в запросе клиента.

Для получения действующего токена  клиент должен воспользоваться специальной функцией API

Каждый запрос, отправленный к REST API Маркетгид обязательно  должен содержать токен API.

Ответ REST API Маркетгид

В ответ на запрос к REST API сервер  всегда  возвращает HTTP ответ с кодом состояния, зависящего от результата запроса.

Код ответа Описание
200 OK Запрос был успешно обработан.

Формат возвращаемых данных

Возвращаемые данные могут быть  в формате  JSON, либо — XML.

По умолчанию используется формат  JSON.

Для задания формата, в котором будут возвращаться данные, используется заголовок запроса. Клиент отсылает заголовок Accept, в котором указывает желаемый формат ответа:

или

Описание формата ответа отправляется в ответе в заголовке Content-Type.

Возвращаемые  в ответе данные, представляют собой JSON строку (http://json.org/json-ru.html), которая в общем виде,  выглядит  следующим образом:

Если в ходе выполнения запроса произошла ошибка — возвращается описание соответствующей ошибки, например:

Работа с клиентами

Получение действующего токена клиента

Метод POST
URL api.marketgid.com/v1/auth/token

Передаваемые параметры:

Обязательные параметры выделены красным

Параметр Значение
email Адрес электронной почты клиента, указанный при регистрации в системе Маркетгид
password Пароль клиента, полученный при регистрации

Возвращаемый ответ:

_текущий_токен_  используется для идентификации  клиента;

_токен_для_обновления_ - будет использован в последующих версиях для обновления просроченного текущего токена.

Получение информации о текущем финансовом состоянии клиента

Метод GET
URL api.marketgid.com/v1/clients/_идентификатор_учетной_записи_клиента_?token=_токен_клиента_

Возвращаемый ответ:

Все суммы возвращаются в валюте клиента(доллар/руб/грн).

balance может иметь как положительное, так и отрицательное значение.

Доступные клиенту средства определяются как:   balance + credit.

Сумма потраченных клиентом средств на рекламу:   income balance.

Работа с  рекламными кампаниями  клиента

Получение коллекции рекламных кампаний клиента

Метод GET
URL api.marketgid.com/v1/goodhits/clients/_идентификатор_учетной_записи_клиента_/campaigns/_идентификатор_рекламной_кампании_?token=_токен_клиента_

Если не передан  _идентификатор_рекламной_кампании_  то метод возвращает  коллекцию рекламных кампаний клиента. Если идентификатор был передан, то возвращается информация только о той рекламной кампании, чей идентификатор был передан.  

Передаваемые параметры:

Обязательные параметры выделены красным

Параметр Значение
token _токен_клиента_
fields массив свойств клиента, информацию о которых необходимо получить ( например: fields=['name','ipsFilter','domainsFilter']). Если параметр не передан, то возвращаются все свойства.

Список может включать следующие свойства:

id   -   идентификатор рекламной кампании;

name – название рекламной кампании;

status  -  текущий  статус рекламной кампании;

ipsFilter — настройки фильтра по IP — адресам;

domainsFilter — настройки фильтра по доменам;

widgetsFilterUid — настройки фильтра по ID площадок;

limitsFilter — настройки лимитов по бюджету и кликам;

limit включает пагинацию, ограничивая количество кампаний отображаемых на странице. 
start позволяет перемещаться по страницам пагинации. По-умолчанию - 0. 

Возвращаемый ответ:

Возможные ошибки:

  • [ERROR_TOO_MANY_CAMPAIGNS_USE_PARAMS_LIMIT_AND_START] - если пользователь имеет более 500 кампаний и при запросе не указан дополнительный параметр limit
  • [ERROR_MAX_LIMIT_PER_PAGE_500] - если указан дополнительный параметр limit и он более 500 

Свойство  status  отображает текущий статус кампании и ее состояние

Возвращаемые значения свойства status  и их описание

id Описание
1 Кампания остановлена в связи с достижением даты окончания
2 Кампания достигла общего лимита по бюджету
3 Кампания достигла общего лимита по кликам
4 Кампания заблокирована клиентом или менеджером
5 Кампания заблокирована по причине отрицательного остатка на счету
6 Кампания не имеет лимитов и активна
7 Кампания не достигла своего дневного лимита
8 Вчера кампания достигла своего суточного лимита по кликам или бюджету и активна
9 Кампания достигла суточного лимита по бюджету
10 Кампания достигла суточного лимита по кликам
11 Кампания на паузе в связи с временными настройками
12 Кампаний остановлена т.к. клиент отложен
13 Кампания остановлена менеджером
14 Кампания удалена
15 Кампания остановлена т.к. клиент отклонён
17 Кампания остановлена по лимиту конверсий
19 Кампания остановлена за нарушение правил креатива


Свойство  ipsFilter - отображает настройки фильтра рекламной кампании по IP-адресам (для посетителей с какими IP-адресами  не должны показываться тизеры данной рекламной кампании).

_тип_фильтра_по_IP_  может принимать следующие значения:

    • off  -  фильтр отключен
    • except - фильтр «кроме» (тизеры РК отображаются всем посетителям, кроме тех, чей IP присутствует в списке для блокировки)
    • ips - список IP-адресов для фильтрации в виде массива.

_потрачено_клиентом_за_текущие_сутки_ в  валюте клиента

Получение статистики в разрезе площадок

Метод GET
URL api.marketgid.com/v1/goodhits/campaigns/ид_кампании/quality-analysis/uid?token=_токен_клиента_

Передаваемые параметры:

Обязательные параметры выделены красным

Параметр Значение
token токен авторизации клиента.
campaignId идентификатор товарной кампании.
dateInterval интервал, за который нужно получить статистику. Если интервал не задан, возвращается статистика за 90 дней. Допустимые значения:

  • interval - при выборе ожидается передача еще параметров двух дат startDate/endDate в формате гггг-мм-дд
  • all - за все время
  • thisWeek - текущая неделя
  • lastWeek - прошлая неделя
  • thisMonth - текущий месяц
  • lastMonth - прошлый месяц
  • lastSeven - последние 7 дней
  • today - сегодня
  • yesterday - вчера
  • last30Days - последние 30 дней
uid uid площадки. Если задан - отображаются данные только для этой площадки.

Возвращаемый ответ:

Детальная статистика рекламных кампаний клиента за день

Метод GET
URL api.marketgid.com/v1/goodhits/campaigns/_идентификатор_рекламной_кампании_/statistics?token=_токен_клиента_

Передаваемые параметры:

Обязательные параметры отмечены красным

Параметр Значение
type Тип статистики.Возможные значение: byClicksDetailed
date Дата в формате:YYYY-MM-DD

Возвращаемые значения

Если запрос выполнен корректно, то возвращается массив данных в следующем формате:

_потрачено_клиентом_  , _стоимость_клика_ -  в валюте клиента(доллар/руб/грн).

Подневная статистика рекламных кампаний клиента

Метод GET
URL api.marketgid.com/v1/goodhits/clients/{clientId}/campaigns-stat?token={accessToken}

Передаваемые параметры:

Параметр Значение
token Токен клиента
dateInterval интервал, за который нужно получить статистику. Если интервал не задан, возвращается статистика за 90 дней. Допустимые значения:

interval - при выборе ожидается передача еще параметров двух дат startDate/endDate в формате гггг-мм-дд
all - за все время
thisWeek - текущая неделя
lastWeek - прошлая неделя
thisMonth - текущий месяц
lastMonth - прошлый месяц
lastSeven - последние 7 дней
today - сегодня
yesterday - вчера
last30Days - последние 30 дней

Возвращаемый ответ:

Если у клиента настроены конверсии, то дополнительно передаются:

  • buy - количество конверсий на этапе покупка
  • buyCost - цена конверсии на этапе покупка
  • decision - количество конверсий на этапе желание
  • decisionCost - цена конверсии на этапе покупка
  • interest - количество конверсий на этапе интерес
  • interestCost - цена конверсии на этапе покупка
  • convertionCost - прибыль по конверсиям
  • revenue - заработано
  • epc - заработок за клик
  • profit - revenue - spent

Если в ходе выполнения запроса произошла ошибка — возвращается описание соответствующей ошибки, например:

[THERE_NO_DATA_IN_CHOSEN_PERIOD] - если в заданном периоде нет данных

[INVALID_VALUE_FOR_INTERVAL] - если некорректно задан интервал или дата старта интервала больше текущей

Создание новой рекламной кампании клиента (со всеми настройками)

Метод POST
URL api.marketgid.com/v1/goodhits/clients/_идентификатор_учетной_записи_клиента_/campaigns?token=_токен_клиента_

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

 

Передаваемые параметры (красным обязательные параметры, синим обязательные, если родительский параметр передан (включен)):

Блок 1

Параметр Значение
name Название рекламной кампании. Должно быть уникальным. 128 символов максимум.
enabledGeoTargetingFlag Флаг включения/выключения (1/ 0) гео-таргетинга.
geoTargets Список стран и городов (регионов) для таргетирования. Пример параметра {'method':'set','cities':['2'],'countries':['ru']}
language язык рекламной кампании
startDate дата старта кампании YYYY-MM-DD
campaignType product/content. Если campaign_type не передан создается тип product

Возможные ошибки для этого блока параметров:

 

Блок 2
Если хотябы один из utm_source, utm_campaign, utm_medium передан, то все три обязательные

Параметр Значение
utm_source 0, 9, A Z, a z, _ + & = (до 200 символов)
utm_campaign 0, 9, A Z, a z, _ + & = (до 200 символов)
utm_medium 0, 9, A Z, a z, _ + & = (до 200 символов)
utm_custom макросы: {widget_id}/{teaser_id}/{campaign_id}/{category_id} etc

Возможные ошибки для этого блока параметров:

 

Блок 3
Если задан параметр limitType, то обязательно должен быть указан тип лимита, и как минимум какой-то из разновидностей лимита (или дневной или overall)

Параметр Значение
limitType или clicks_limits или budget_limits
dailyLimit если limitType = clicks_limits, то целое значение, если limitType = budget_limits — значение с 2 знаками после запятой (до сотых).
overallLimit если clicks_limits, то целое значение. Минимальное значение должно быть больше dailyLimit, если он задан. Если budget_limits — значение с 2 знаками после запятой (до сотых). Должно быть больше dailyLimit, если он задан.
splitDailyLimitEvenly Опция равномерного распределения трафика. 0 – откл, 1 – вкл

Возможные ошибки для этого блока параметров:

 

Блок 4

Параметр Значение
browserTargets _browser1_, _browser2_, _browser3_
osTargets _os1_,_os2_,_os3_

Возможные ошибки для этого блока параметров:

Возвращаемый ответ:

Создание новой рекламной кампании клиента

Метод POST
URL api.marketgid.com/v1/goodhits/clients/_идентификатор_учетной_записи_клиента_/campaigns?token=_токен_клиента_

Передаваемые параметры:

Параметр Значение
name Название рекламной кампании. Должно быть уникальным.
enabledGeoTargetingFlag Флаг включения/выключения (1/ 0) гео-таргетинга.
geoTargets

(параметр обязателен, если enabledGeoTargetingFlag=1)

Список стран и городов (регионов) для таргетирования:

{'method':'set','cities':['2'],'countries':['ru']}

language язык рекламной кампании
startDate дата старта кампании YYYY-MM-DD
campaignType product | content. Если campaign_type не передан создается тип product

Возвращаемый ответ:

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

Получение даты создания рекламной кампании

Метод GET
URL api.marketgid.com/v1/goodhits/clients/_идентификатор_учетной_записи_клиента_/campaigns/_идентификатор_рекламной_кампании_?token=_токен_клиента_&fields=['whenAdd']

Передаваемые параметры:

Параметр Значение
fields whenAdd

Возвращаемые значения:

Настройки UTM меток кампании

Метод PUT
URL api.marketgid.com/v1/goodhits/campaigns/_campaign_ID_/utmtracking/? token=_client's_token

Передаваемые параметры:

Параметр Значение
utm_source Стандартная настройка Google Analytics для отслеживания источника трафика
utm_campaign Стандартная настройка Google Analytics для отслеживания кампании
utm_medium Стандартная настройка Google Analytics для отслеживания канала
utm_custom Пользовательская разметка. Которая может быть добавлена в пользовательскую ссылку

Значения для  Google Analytics (utm_source, utm_campaign, utm_medium) должны быть установлены в одном запросе. При использовании одного из этих параметров, другие необходимы. Ошибка если одно из значений пустое: [UTM_TAGGING_FIELDS_MUST_NOT_BE_EMPTY]  

Когда вы включаете настройки по умолчанию для Google Analytics система автоматически добавляет utm_content  и utm_term . В Тег utm_content  автоматически добавляется ID тизера.  utm_term=_site_ID_

UTM-хвосты не должны превышать кол-во более 200 символов, в противном случае система вернет ошибку: [UTM_CUSTOM_TOO_LONG_STR]  


Приемлемые значения: 0 9, A Z, a z,   _ + & = . И макросы: {widget_id},  {teaser_id}, {campaign_id}, {category_id}.  


Или система вернет ошибку:  [WRONG_UTM_CUSTOM_FORMAT]

Если поле пустое, то поле будет отключено. Если все настроено корректно, система вернет ID кампании:

Установка лимитов рекламной кампании

Метод PATCH
URL api.marketgid.com/v1/goodhits/clients/_идентификатор_учетной_записи_клиента_/campaigns/_идентификатор_рекламной_кампании_

Передаваемые параметры:

Обязательные параметры отмечены красным

Параметр Значение
token _токен_
limitType clicks_limits — установка лимита по кликам

budget_limits — установка лимита по бюджету

dailyLimit Установка лимита в сутки.

Для clicks_limits должно  быть целое значение. Если значение пустое — лимит отсутствует (кампания не имеет ограничения).

Для budget_limits — значение с 2 знаками после запятой (до сотых). Если значение пустое — лимит отсутствует (кампания не имеет ограничения).

overallLimit Установка лимита на кампанию в целом.

Для clicks_limits должно  быть целое значение. Минимальное значение должно быть больше dailyLimit, если он задан. Если значение пустое — лимит отсутствует (кампания не имеет ограничения).

Для budget_limits — значение с 2 знаками после запятой (до сотых). Должно быть больше dailyLimit, если он задан. Если значение пустое — лимит отсутствует (кампания не имеет ограничения).

splitDailyLimitEvenly Опция равномерного распределения трафика. 0 - откл, 1 - вкл
  • При выборе лимита по бюджету в зависимости от валюты клиента значение вводится в валюте, указанной для этого клиента.
  • Суточный лимит не может быть меньше 10$. Общий лимит не может быть меньше чем суточный лимит
  • Минимальные лимиты в рублях и гривнах равняются лимитам в долларах, умноженным на курс 50 для рублей и 25 для гривен
  • При установке лимита в рублях и гривнах шаг изменения - 5 копеек, а для долларов - 1 цент. При вводе числа, не кратного шагу - оно округляется в большую сторону.

При успешном сохранении настроек возвращается идентификатор редактируемой РК:

Блокировка/разблокировка рекламной кампании

Метод PATCH
URL api.marketgid.com/v1/goodhits/clients/_идентификатор_учетной_записи_клиента_/campaigns/_идентификатор_рекламной_кампании_

Передаваемые параметры

Обязательные параметры отмечены красным

Параметр Значение
token _токен_
whetherToBlockByClient 0 – разблокировать РК

1 — блокировать РК

blockByClientReason

(если whetherToBlockByClient=1, то параметр обязателен)

_причина _блокировки_РК_

Установка коэффициента селективного аукциона рекламной кампании

Метод PATCH
URL api.marketgid.com/v1/goodhits/clients/_идентификатор_клиента_/campaigns/_идентификатор_рекламной_кампании_?token=_токен_клиента_&qualityFactor={"_widgetUid1_s_sourceId1_":_qf1_,"_widgetUid2_s_sourceId2_":_qf2_,…}

Передаваемые параметры (обязательные параметры выделены красным):

Параметр Значение
token токен авторизации клиента.
clientId идентификатор клиента
campaignId идентификатор товарной кампании.
qualityFactor содержит widgetUID и новый коэффициент качества на площадку. Передается в json формате. Может быть несколько пар: {"_widgetUid1_":_qf1_,"_widgetUid2_":_qf2_,"_widgetUid3_":_qf3_}. 
sourceId коэффициент подисточника. Можно задать через параметр s. Например: {"_widgetUid1_s_sourceId1_":_qf1_}

Возвращаемый ответ:

Если новый коэффициент для какой-то площадки не попадает в допустимый диапазон, возвращается:

Если какой-то площадки из списка нет, то возвращается ошибка:

Настройки геотаргетинга рекламных кампаний

Получение  настроек геотаргетинга рекламных кампаний клиента

Метод GET
URL api.marketgid.com/v1/goodhits/campaigns/_идентификатор_рекламной_кампании_/targetings/geo?token=_токен_клиента_

Возвращаемый ответ:

Секция   "actual"  -  содержит текущие настройки геотаргетинга.

Секция   "requested"  -  обновленные  настройки геотаргетинга, которые будут применены (или в ближайшее время или со следующих суток).
Если настройки геотаргетинга не используются, то возвращается ответ вида:

Получение списка доступных стран для настройки геотаргетинга

Метод GET
URL api.marketgid.com/v1/dictionaries/geo?token=_токен_клиента_

Передаваемые параметры:

Обязательные параметры выделены красным

Параметр Значение
type countries

Возвращает массив  стран, которые могут использоваться для настроек геотаргетинга:

Получение списка доступных регионов (городов) для настройки геотаргетинга

Метод GET
URL api.marketgid.com/v1/dictionaries/geo?token=_токен_клиента_

Передаваемые параметры:

Обязательные параметры выделены красным

Параметр Значение Комментарий
type cities
countries ['_двухсимвольный_код_страны_', ….] Массив кодов стран, для которых необходимо получить список городов(регионов)

Возвращает массив регионов (городов), которые могут использоваться для настроек геотаргетинга:

Редактирование настроек геотаргетинга для рекламной кампании

Метод PUT
URL api.marketgid.com/v1/goodhits/campaigns/_идентификатор_рекламной_кампании_/targetings/geo?token=_токен_клиента_  

Передаваемые параметры:

Обязательные параметры выделены красным

Параметр Значение
targets Список стран и городов (регионов) для таргетирования:

{ 'method':'set',  'cities': [  _идентификатор_города_,  . . . .   ],

    'countries':     [   _двухсимвольный_код_страны_,  . . . .   ]}

Если в параметрах переданы заполненными cities и countries - то в приоритете будет countries.

Список городов можно получить с помощью запроса.

Список стран можно получить с помощью запроса.

enabledFlag Флаг включения/выключения геотаргетинга (1/0)

Если запрос составлен корректно, будет возвращен id редактируемой РК:

Если не указаны какие-либо параметры или указаны не верно, то изменения настроек не сохранятся и  будет возвращено сообщение об ошибке:

Редактирование настроек таргетинга по браузерам для рекламной кампании

Метод PUT
URL api.marketgid.com/v1/goodhits/campaigns/_идентификатор_рекламной_кампании_/targetings/browsers?token=_токен_

Передаваемые параметры:

Обязательные параметры выделены красным

Параметр Значение
targets _метод_редактирования_ , _браузер_,_браузер_.....
enabledFlag 0 – таргетинг выключен

1 — таргетинг включен

Возможные значений  для _метод_редактирования_ :

include   -  включение браузера в список для таргетинга

Возможные значения для _браузер_ :

Название Значение
Google Chrome chrome
Safari safari
Opera Mini operamini
Opera Mobile operamoblie
Opera opera
Firefox firefox
Internet Explorer msie
Others others

При успешном сохранении настроек возвращается идентификатор редактируемой РК:

Редактирование настроек фильтра по IP-адресам для рекламной кампании

Метод PATCH
URL api.marketgid.com/v1/goodhits/clients/_идентификатор_клиента_/campaigns/_идентификатор_рекламной_кампании_?token=_токен_

Передаваемые параметры:

Обязательные параметры выделены красным

Параметр Значение
ipsFilter _метод_редактирования_ ,  _тип_фильтра_, IP1,IP2….

Поддерживаются такие настройки :

  • Методы редактирования :
    • include    -  включить адрес в список
    • exclude   - удалить адрес из списка
  • Типы фильтра :
    • except   -  кроме
    • only   -  только
    • off  -   отключен

IP можно указывать как единичные, так и в виде подсетей (192.168.0.1/24)

При успешном сохранении настроек возвращается идентификатор редактируемой РК:

Редактирование настроек фильтра по ОС для рекламной кампании

Метод PUT
URL api.marketgid.com/v1/goodhits/campaigns/_идентификатор_рекламной_кампании_/targetings/operatingsystems?token=_токен_

Передаваемые параметры:

Параметр Значение
enabledFlag вкл/выкл ОС таргетинг,

вкл=1

выкл=0

targets _метод_редактирования_,_OS1_,_OS2_,_OS3_

Операционные системы:

Название Версия Параметр
Android 9.xx android90mobile
Android 8.xx android80mobile
Android 7.xx android70mobile
Android 6.xx android60mobile
Android 5.xx android50mobile
Android 4.4 android44mobile
Android 4.3 android43mobile
Android 4.2 android42mobile
Android 4.1 android41mobile
Android 4.0 android40mobile
Android 3.хх android3mobile
Android 2.3 android23mobile
Android 2.2 и ниже android22mobile
iOS 9.хх ios9mobile
iOS 8.хх ios8mobile
iOS 7.хх ios7mobile
iOS 6.хх ios6mobile
iOS 5.хх ios5mobile
iOS 4.хх и ниже ios4mobile
iOS 11.xx ios11mobile
iOS 10.хх ios10mobile
Other Mobile OS othermobile
Android 9.xx android90tablet
Android 8.xx android80tablet
Android 7.xx android70tablet
Android 6.xx android60tablet
Android 5.xx android50tablet
Android 4.4 android44tablet
Android 4.3 android43tablet
Android 4.2 android42tablet
Android 4.1 android41tablet
Android 4.0 android40tablet
Android 3.хх android3tablet
Android 2.3 android23tablet
Android 2.2 и ниже android22tablet
iOS 9.хх ios9tablet
iOS 8.хх ios8tablet
iOS 7.хх ios7tablet
iOS 6.хх ios6tablet
iOS 5.хх ios5tablet
iOS 4.хх и ниже ios4tablet
iOS 11.xx ios11tablet
iOS 10.хх ios70tablet
Other Tablet OS othertablet
Mac OS macos
Other Desktop OS otherdesctop
Windows OS windowsos
  • Методы редактирования :
    • include - включить адрес в список
    • exclude - удалить адрес из списка

При успешном сохранении настроек возвращается идентификатор редактируемой РК:

Редактирование настроек фильтра по площадкам для ТРК с помощью UID

Метод PATCH
URL api.marketgid.com/v1/goodhits/clients/_идентификатор_клиента_/campaigns/_идентификатор_рекламной_кампании_?token=_токен_

Передаваемые параметры:

Параметр Значение
widgetsFilterUid метод_редактирования, тип_фильтра, uid1,uid2…

можно передавать параметры подисточника в скобках через пробел

тип_фильтра, uid1(subid subid subid),uid2… или через "s"

тип_фильтра, UID1sSUBID1

block-widget-priority Для метода редактирования include при получении запроса на добавление sub_id, проверяется добавлен ли в фильтр источник, если добавлен, то запись подисточника игнорируется. Таким образом, используя этот параметр, можно немного изменить логику обработки запросов.

Методы редактирования :

  • include - включить адрес в список
  • exclude - удалить адрес из списка

Типы фильтра:

  • only - только
  • except - кроме
  • off - фильтр отключен


При успешном сохранении настроек возвращается идентификатор редактируемой РК:

Пример ответа с ошибками в данных - не переданы площадки:

Пример ответа с ошибками в данных - переданы не существующие id площадок:

Пример ответа с ошибками в данных - не переданы параметры фильтров(include|exclude,off|only|except) или переданы неправильно:

Если передали валидные и не валидные ID одновременно ("widgetsFilter": "include, only, 1000000, 111111, 109") - в этом случае валидные запишутся в базу, а не валидные выдаст в ответ:

Ситуация, когда не передаются площадки - является НЕ валидной.

При смене типа фильтра с 1 на 2 или наоборот возвращается ошибка:

Работа с тизерами клиента

Используемые константы и идентификаторы

Код валюты для отображения цены товара

ID в системе МГ Соответствующий международный трехсимвольный код
1 RUB
4 UAH
5 USD
6 EUR
23 ILS
35 GEL
38 KZT

Статусы тизера

Обозначение  статуса Описание
onModeration Тизер находится на модерации
rejected Тизер отклонен
active Тизер активен
new Новый тизер, еще не заработал собственный CTR
goodPerformance Тизер находится в показах во всех
badPerformance Тизер не показывается в одном или нескольких регионах из-за низкого рейтинга. Необходимо установить более высокую цену за клик  или заменить тизер на другой, который мог бы обеспечить более высокий CTR
blocked Тизер заблокирован
campaignBlocked Заблокирована рекламная кампания

Получение коллекции тизеров клиента

Метод GET
URL api.marketgid.com/v1/goodhits/clients/_идентификатор_учетной_записи_клиента_/teasers[/_идентификатор_тизера_]

Если _идентификатор_тизера_ не передан,  то метод возвращает  коллекцию тизеров клиента. Если идентификатор  передан, то возвращается информация только о том тизере, идентификатор которого был передан в запросе.  

Передаваемые параметры

Обязательные параметры отмечены красным

Параметр Значение
token _токен_клиента_
fields

(используется если в запросе передан _идентификатор_тизера_)

Массив  свойств тизера, информацию о которых необходимо получить ( например: fields=['title','url','statistics']). Если параметр не передан, то возвращаются все свойства.
status Принимает значения из таблицы "Статусы тизера"; можно указать несколько статусов одновременно (например: status=['active','onModeration']) для получения всех тизеров с данными статусами.
campaign получение товарных тизеров клиента по ID кампании
limit включает пагинацию, ограничивая количество тизеров отображаемых на странице. Если лимит не указан - отображаются все тизеры. Возможные ошибки при использовании опции limit: ["[ERROR_MAX_LIMIT_PER_PAGE_{max_allowed_limit}]"]
start позволяет перемещаться по страницам пагинации. По-умолчанию - 0

Возвращаемый ответ:

Синим цветом шрифта выделен ответ, возвращаемый, если в запросе был передан идентификатор  тизера. Если в запросе был передан идентификатор  несуществующего тизера или тизера, принадлежащего  другому клиенту будет возвращено сообщение об ошибке:

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

Метод POST
URL api.marketgid.com/v1/goodhits/clients/_идентификатор_учетной_записи_клиента_/teasers?token=_токен_клиента_

Передаваемые параметры (необходимо передавать в body POST-метода)

Обязательные параметры отмечены красным.

Параметр Значение
url URL рекламной ссылки. При передаче параметров рекомендовано использовать %26 вместо &
campaignId Идентификатор рекламной кампании
title Заголовок тизера (до 65 символов)
advertText Рекламный текст (до 75 символов)
imageLink Ссылка на изображение для тизера (минимум 492x328 пикселей)
category Идентификатор категории тизера
priceOfClick Цена за клик, в центах, с десятыми долями.

В качестве разделителя целой и дробной части может использоваться запятая или точка.

cropWidth Размер стороны прямоугольника, в пикселях, который будет вырезаться из загружаемого изображения (imageLink). cropWidth не может быть меньше чем 492px. Если заполнено cropLeft - то cropWidth не может быть меньше, чем cropWidth+cropLeft и не может быть больше ширины изображения imageLink
cropTop Смещение от верхнего края, в пикселях, прямоугольника который будет вырезаться из загружаемого изображения (imageLink). Может быть пустым, но не может быть меньше, чем высота изображения imageLink минус 328px
cropLeft Смещение  от левого края, в пикселях, прямоугольника который будет вырезаться из загружаемого изображения (imageLink). Может быть пустым. cropWidth+cropLeft не может быть больше ширины изображения imageLink
cropWidthQuadratic Размер стороны квадрата, в пикселях, который будет вырезаться из загружаемого изображения (imageLink). Если заполнено cropLeftQuadratic - то cropWidthQuadratic не может быть меньше, чем cropWidthQuadratic+cropLeftQuadratic и не может быть больше ширины изображения imageLink
cropTopQuadratic Смещение от верхнего края, в пикселях, квадрата который будет вырезаться из загружаемого изображения (imageLink). Может быть пустым, но не может быть меньше, чем высота изображения imageLink минус 328px
cropLeftQuadratic Смещение  от левого края, в пикселях, квадрата который будет вырезаться из загружаемого изображения (imageLink). Может быть пустым. cropWidthQuadratic+cropLeftQuadratic не может быть больше ширины изображения imageLink
whetherShowGoodPrice Флаг отображения цены товара (1/0)

При whetherShowGoodPrice = 1 параметры currency, goodPrice, goodOldPrice обязательны.
При whetherShowGoodPrice = 0  параметры будут проигнорированы.

currency Идентификатор валюты для  отображения  цены товара
goodPrice Цена товара, в отображаемой валюте
goodOldPrice Старая цена товара

Возвращаемый ответ:

При успешном создании тизера возвращается ответ:

Если при попытке создания тизера произошла ошибка, то  возвращается название название ошибки:

Список возможных ошибок, возвращаемых при создании  и  редактировании  тизера рекламной кампании.

_НАЗВАНИЕ_ОШИБКИ_ Описание
ERROR_PARAMETER_WHETHERSHOWGOODPRICE_CAN_NOT_BE_EMPTY Не передан обязательный параметр  whetherShowGoodPrice
ERROR_PARAMETER_PRICEOFCLICK_CAN_NOT_BE_EMPTY Не передан обязательный параметр  priceOfClick
ERROR_PARAMETER_CATEGORY_CAN_NOT_BE_EMPTY Не передан обязательный параметр
category
ERROR_ADVERT_TEXT_TOO_LONG Рекламный текст (параметр advertText)превышает максимально допустимую длину (не более 75 символов)
ERROR_PARAMETER_TITLE_CAN_NOT_BE_EMPTY Не передан заголовок тизера (обязательный параметр title)
ERROR_TITLE_TOO_LONG Заголовок тизера (параметр  title) превышает максимально допустимую длину (не более 65 символов)
ERROR_PARAMETER_IMAGELINK_CAN_NOT_BE_EMPTY Не передана ссылка на изображение для тизера (обязательный параметр  imageLink)
ERROR_PARAMETER_CAMPAIGNID_CAN_NOT_BE_EMPTY Не передан идентификатор рекламной кампании, для которой создается тизер  (обязательный параметр  campaignId)
ERROR_PARAMETER_URL_CAN_NOT_BE_EMPTY Не передана  рекламная ссылка для тизера   (обязательный параметр url)
[ERROR_PARAMETER_CATEGORY_INCORRECT_FOR_THIS_CAMPAIGN_TYPE] Неправильно выбран параметр category для текущего типа кампании

Изменение настроек тизера рекламной кампании

Метод PATCH
URL api.marketgid.com/v1/goodhits/clients/_идентификатор_учетной_записи_клиента_/teasers/_идентификатор_тизера_?token=_токен_клиента_

Передаваемые параметры:

Обязательные параметры отмечены красным.

Параметр Значение
url URL рекламной ссылки
campaignId Идентификатор кампании
title Заголовок тизера (до 65 символов)
advertText Рекламный текст (до 75 символов)
imageLink Ссылка на изображение для тизера (минимум 492x328 пикселей)
priceOfClick Цена за клик в центах, с десятыми долями. В качестве разделителя между целым числом и дробью можно использовать запятую или точку.
cropWidth Размер стороны прямоугольника, в пикселях, который будет вырезаться из загружаемого изображения (imageLink). Может быть пустым.
cropTop Смещение от верхнего края, в пикселях, прямоугольника который будет вырезаться из загружаемого изображения (imageLink). Может быть пустым.
cropLeft Смещение  от левого края, в пикселях, прямоугольника который будет вырезаться из загружаемого изображения (imageLink). Может быть пустым
cropWidthQuadratic Размер стороны квадрата, в пикселях, который будет вырезаться из загружаемого изображения (imageLink). Может быть пустым.
cropTopQuadratic Смещение от верхнего края, в пикселях, квадрата который будет вырезаться из загружаемого изображения (imageLink). Может быть пустым.
cropLeftQuadratic Смещение  от левого края, в пикселях, квадрата который будет вырезаться из загружаемого изображения (imageLink). Может быть пустым
whetherShowGoodPrice Флаг отображения цены товара (1/0)

При whetherShowGoodPrice = 1 параметры currency, goodPrice, goodOldPrice обязательны.
При whetherShowGoodPrice = 0  параметры будут проигнорированы.

currency Идентификатор валюты для отображения цены товара
goodPrice Цена товара в указанной валюте
goodOldPrice Старая цена товара

Если какой-либо из обязательных параметров не передан, то  возвращается соответствующая ошибка, например, если не передается campaignId:

Если редактируемый тизер находится на модерации, то возвращает ошибку:

Изменение цены за клик для тизера рекламной кампании

Метод PATCH
URL api.marketgid.com/v1/goodhits/clients/_идентификатор_учетной_записи_клиента_/teasers/_идентификатор_тизера_?token=_токен_клиента_

Передаваемые параметры:

Параметр Значение
priceOfClickByLocation Устанавливаемая цена за клик по всем гео группам в валюте клиента. В качестве разделителя можно использовать точку или запятую.
priceOfClickByLocation_{geo_zones_groups_id} Устанавливаемая цена за клик по конкретной гео группе в валюте клиента. В качестве разделителя можно использовать точку или запятую.
geo_zones_groups_id Страна, регион, город geo_zones_ids
32 Россия  
33   Дальневосточный ФО   168,124,278,258,183,137,93,127,274,111,188,300
34   Уральский ФО   155,123,121,115,104,169,301
35   Сибирский ФО   122,153,185,259,131,132,100,257,113,92,277,147,177,275,171,276,279,280,302
36   Приволжский ФО   152,180,118,165,138,136,154,107,114,256,130,98,120,149,110,148,303
37   Южный ФО   164,187,96,184,129,135,304
38   Северо-Западный ФО   140,119,101,166,141,142,167,145,159,305
39   Центральный ФО   181,161,146,106,125,109,163,174,143,134,162,95,126,144,139,103,306
40   Северо-Кавказский ФО   170,255,186,194,151,117,254,307
41   Москва   94,251,308
42   Санкт-Петербург   102,252,309
43   Прочие регионы   3
44 Украина  
45   Северная Украина    
175     Житомир 128,310
176     Сумы 175
177     Чернигов 176
46   Центральная Украина  
178     Винница 190,311
179     Днепропетровск 150
180     Кировоград 160
181     Полтава 189
182     Черкассы 178
47   Южная Украина    
183     Запорожье 173
184     Николаев 182
185     Одесса 97
186     Херсон 99
48   Западная Украина    
167     Волынь 157
168     Закарпатье 158
169     Ивано-Франковск 192,312
170     Львов 193
171     Ровно 191
172     Тернополь 133
173     Хмельницкий 179
174     Черновцы 156
49   Восточная Украина    
164     Донецк 116
165     Луганск 172
166     Харьков 105
50     Киев 112,253,313
51     Прочие регионы 2
53 Страны СНГ      
54   Азербайджан   16
55   Армения   27
56   Белоруссия   8
57   Казахстан   6
58   Киргизия   36
59   Республика Молдова   10
60   Таджикистан   43
61   Туркменистан   85
62   Узбекистан   21
52   Крым   108,281,314
63 Прибалтика      
64   Латвия   9
65   Литва   12
66   Эстония   11
67   Скандинавия    
68   Дания   38
69   Норвегия   30
70   Швеция   26
71 Европа      
72   Австрия   33
74   Бельгия   28
75   Германия   5
76   Греция   25
78   Ирландия   23
80   Испания   17
81   Италия   20
85   Нидерланды   29
86   Португалия   32
87   Сербия   81
89   Финляндия   22
90   Франция   18
93   Швейцария   34
155   Польша   260
156   Румыния   261
157   Чехия   262
158   Болгария   263
159   Венгрия   264
160   Словакия   265
94   Прочие страны   268,273,62,83,74,72,66,46,53,75
95 Азия      
99   Индия   47
101   Китай   24
105   Республик Корея   35
111   Япония   37
112   Прочие страны   270,73,79,49,86,90,52,48,69,63,89,45,54
113 Западная Азия      
114   Грузия   15
115   Израиль   7
118   Иран   65
122   ОАЭ   39
125   Турция   19
126   Прочие страны   283,284,290,291,294,84,82,71,70,80,64,67
127 Австралия     31
128 Великобритания     14,282
129 Канада     13
130 Новая Зеландия     50
131 США     4,195,196,197,198,199,200,201,202,203,204,205,206,207,208,209,210,211,212,213,214,215,216,217,218,219,220,221,222,223,224,225,226,227,228,229,230,231,232,233,234,235,236,237,238,239,240,241,242,243,244,245,246,247,248,249,250,315,316,317,318
163 Бразилия     41
154 Прочие страны     0,1,88,87,78,77,76,68,61,60,59,58,57,56,55,51,44,42,40,272,285,286,287,288,289,292,293,266,269

Возвращаемый ответ:

При успешном изменении цены за клик  возвращается ответ:

Ошибки выводятся в следующих случаях:

  • если параметр цены за клик не указан или указан не верно

  • если цена не указана или указано не валидное значение

  • если цена указана ниже минимальной

  • если цена указана выше максимальной
  • если тизер на модерации

Блокировка / разблокировка тизера для рекламной кампании

Метод PATCH
URL api.marketgid.com/v1/goodhits/clients/_идентификатор_учетной_записи_клиента_/teasers/_идентификатор_тизера_?token=_токен_клиента_

Передаваемые параметры:

Параметр Значение
whetherToBlockByClient 1 —  блокирует  тизер

0 —  разблокирует тизер

Возвращаемый ответ

Если операция выполнена успешна, то возвращается идентификатор тизера, для которого была изменено состояние:

Удаление тизера (перемещение в корзину) для рекламной кампании

Метод DELETE
URL api.marketgid.com/v1/goodhits/clients/_идентификатор_учетной_записи_клиента_/teasers/_идентификатор_тизера_?token=_токен_клиента_

Передаваемые параметры:

Параметр Значение
reason Причина удаления тизера. До 255 символов.

Возвращаемый ответ:

Если операция выполнена успешно, то возвращается идентификатор тизера,  который  был  перемещен в корзину:

Если тизер с указанным идентификатором отсутствует в системе или уже был перемещен в корзину, то будет возвращено сообщение:

Похожие статьи

Типы лендингов

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

Read More