Difference between revisions of "API setting"

From Service Manual Kadam.net
Jump to: navigation, search
(Statistics on sites in the advertiser's office)
Line 330: Line 330:
 
api.kadam.net?attr=string&date_from=01.05.2016&date_to=01.07.2016
 
api.kadam.net?attr=string&date_from=01.05.2016&date_to=01.07.2016
 
</pre> </code>
 
</pre> </code>
 +
 +
==Изменение множителя для статистики по площадкам в кабинете рекламодателя==
 +
Для изменения множителя для статистики по площадкам используется метод <b>ads.campaigns.statblock</b> (PUT запрос)
 +
 +
Параметры (все являются обязательными):
 +
<ul>
 +
<li>app_id - id пользователя, числовое значение (int)</li>
 +
<li>signature - подпись, строка (string)</li>
 +
<li>campaign_id - id кампании, числовое значение (int)</li>
 +
<li>block - числовое значение (int)</li>
 +
<li>domain - числовое значение (int)</li>
 +
<li>multiplier - новое значение множителя, числовое значение (float)</li>
 +
<li>multiplierOld - старое значение множителя, числовое значение (float)</li>
 +
<li>macros - id площадки, числовое значение (int)</li>
 +
</ul>
 +
 +
Параметры block и macros в кабинете не выводятся, их можно получить через метод, описанный в пункте "Статистика по площадкам в кабинете рекламодателя".
 +
 +
==Статистика по всем материалам кампании==
 +
Для получения статистики по всем материалам кампании используется метод <b>ads.analytic.materials.get</b><br/>
 +
 +
<table>
 +
  <tr bgcolor = #DCDCDC>
 +
      <th width = 130 align = left>Параметры</th>
 +
      <th width = 300 align = left>Значение</th>
 +
      <th width = 350 align = left>Дополнительные атрибуты</th>
 +
  </tr>
 +
  <tr bgcolor = #F5F5F5>
 +
      <td>campaign_id</td>
 +
      <td>id кампании</td>
 +
      <td>int (числовое значение), обязательный параметр</td>
 +
  </tr>
 +
  <tr bgcolor = #F5F5F5>
 +
      <td>period</td>
 +
      <td>Способ группировки данных по датам:
 +
          <p>1. day — статистика по дням;</p>
 +
          <p>2. month — статистика по месяцам;</p>
 +
          <p>Временные ограничения задаются параметрами date_from и date_to</p>
 +
      </td>
 +
      <td>обязательный параметр, строка</td>
 +
  </tr>
 +
  <tr bgcolor = #F5F5F5>
 +
      <td>date_from</td>
 +
      <td>Начальная дата выводимой статистики. Используется разный формат дат для разного значения параметра period:
 +
          <p>1. day: YYYY-MM-DD, пример: 2011-09-27</p>
 +
          <p>2. month: YYYY-MM, пример: 2011-09</p>
 +
      </td>
 +
      <td>обязательный параметр, строка</td>
 +
  </tr>
 +
  <tr bgcolor = #F5F5F5>
 +
      <td>date_to</td>
 +
      <td>Конечная дата выводимой статистики. Используется разный формат дат для разного значения параметра period:
 +
          <p>1. day: YYYY-MM-DD, пример: 2011-09-27</p>
 +
          <p>2. month: YYYY-MM, пример: 2011-09</p>
 +
      </td>
 +
      <td>обязательный параметр, строка</td>
 +
  </tr>
 +
</table>
 +
<b>Результат:</b><br/>
 +
Возвращает объект с данными
 +
<code>
 +
<pre>
 +
{
 +
response: {
 +
count: %total items%
 +
items: {
 +
teaser_id
 +
date
 +
shows
 +
clicks
 +
ctr
 +
cpm
 +
money
 +
                      }
 +
                  }
 +
}
 +
</pre>
 +
</code>
 +
==Статистика по материалу==
 +
Для получения статистики по материалу используется метод <b>ads.analytic.material.get</b><br/>
 +
<table>
 +
  <tr bgcolor = #DCDCDC>
 +
      <th width = 130 align = left>Параметры</th>
 +
      <th width = 300 align = left>Значение</th>
 +
      <th width = 350 align = left>Дополнительные атрибуты</th>
 +
  </tr>
 +
  <tr bgcolor = #F5F5F5>
 +
      <td>material_id</td>
 +
      <td>id материала</td>
 +
      <td>int (числовое значение), обязательный параметр</td>
 +
  </tr>
 +
  <tr bgcolor = #F5F5F5>
 +
      <td>period</td>
 +
      <td>Способ группировки данных по датам:
 +
          <p>1. day — статистика по дням;</p>
 +
          <p>2. month — статистика по месяцам;</p>
 +
          <p>Временные ограничения задаются параметрами date_from и date_to</p>
 +
      </td>
 +
      <td>обязательный параметр, строка</td>
 +
  </tr>
 +
  <tr bgcolor = #F5F5F5>
 +
      <td>date_from</td>
 +
      <td>Начальная дата выводимой статистики. Используется разный формат дат для разного значения параметра period:
 +
          <p>1. day: YYYY-MM-DD, пример: 2011-09-27</p>
 +
          <p>2. month: YYYY-MM, пример: 2011-09</p>
 +
      </td>
 +
      <td>обязательный параметр, строка</td>
 +
  </tr>
 +
  <tr bgcolor = #F5F5F5>
 +
      <td>date_to</td>
 +
      <td>Конечная дата выводимой статистики. Используется разный формат дат для разного значения параметра period:
 +
          <p>1. day: YYYY-MM-DD, пример: 2011-09-27</p>
 +
          <p>2. month: YYYY-MM, пример: 2011-09</p>
 +
      </td>
 +
      <td>обязательный параметр, строка</td>
 +
  </tr>
 +
</table>
 +
<b>Результат:</b><br/>
 +
Возвращает объект с данными
 +
<code>
 +
<pre>
 +
{
 +
response: {
 +
count: %total items%
 +
items: {
 +
date
 +
shows
 +
clicks
 +
ctr
 +
cpm
 +
money
 +
                      }
 +
                  }
 +
}
 +
</pre>
 +
</code>
 +
==Создание рекламной кампании==
 +
Для для создания новой рекламной кампании используется метод <b>ads.campaigns.put</b><br>
 +
Допустимое количество кампаний, создаваемых с помощью одного запроса — 50.<br/>
 +
<table>
 +
  <tr bgcolor = #DCDCDC>
 +
      <th width = 130 align = left>Параметры</th>
 +
      <th width = 300 align = left>Значение</th>
 +
      <th width = 350 align = left>Дополнительные атрибуты</th>
 +
  </tr>
 +
  <tr bgcolor = #F5F5F5>
 +
      <td>data</td>
 +
      <td>сериализованный JSON-массив объектов, описывающих создаваемые кампании. Описание объектов client_specification см. ниже.</td>
 +
      <td>обязательный параметр, строка</td>
 +
  </tr>
 +
  <tr bgcolor = #F5F5F5>
 +
      <td>client_specification</td>
 +
  </tr>
 +
  <tr bgcolor = #F5F5F5>
 +
      <td>app_id</td>
 +
      <td>id пользователя</td>
 +
      <td>обязательный параметр, int (числовое значение)</td>
 +
  </tr>
 +
  <tr bgcolor = #F5F5F5>
 +
      <td>client_id</td>
 +
      <td>id клиента, в рекламном кабинете которого будет создаваться кампания. Так же может принимать значение app_id (самого себя)
 +
      </td>
 +
      <td>обязательный параметр, int (числовое значение)</td>
 +
  </tr>
 +
  <tr bgcolor = #F5F5F5>
 +
      <td>ad_format</td>
 +
      <td>Формат объявления:
 +
          <p>10 - Тизерная;</p>
 +
          <p>20 - Баннерная;</p>
 +
          <p>30 - Push-уведомления;</p>
 +
          <p>40 - Clickunder;</p>
 +
          <p>60 - Контекстная</p>
 +
      </td>
 +
      <td>обязательный параметр, int (числовое значение)</td>
 +
  </tr>
 +
  <tr bgcolor = #F5F5F5>
 +
      <td>cost_type</td>
 +
      <td>Способ оплаты:
 +
          <p>0 - СРС;</p>
 +
          <p>1 - СРА;</p>
 +
          <p>2 - СРМ</p>
 +
      </td>
 +
      <td>обязательный параметр, int (числовое значение)</td>
 +
  </tr>
 +
  <tr bgcolor = #F5F5F5>
 +
      <td>name</td>
 +
      <td>название кампании
 +
      </td>
 +
      <td>обязательный параметр, строка</td>
 +
  </tr>
 +
  <tr bgcolor = #F5F5F5>
 +
      <td>Link_url</td>
 +
      <td>ссылка на рекламируемый объект в формате: http://yoursite.cоm
 +
      </td>
 +
      <td>обязательный параметр, строка</td>
 +
  </tr>
 +
  <tr bgcolor = #F5F5F5>
 +
      <td>real_url</td>
 +
      <td>ссылка на реальный домен рекламируемого объекта в формате: http://yoursite.cоm
 +
      </td>
 +
      <td>обязательный параметр, строка</td>
 +
  </tr>
 +
  <tr bgcolor = #F5F5F5>
 +
      <td>sex</td>
 +
      <td>Пол:
 +
          <p>3 - любой;</p>
 +
          <p>2 - мужской;</p>
 +
          <p>1 - женский</p>
 +
      </td>
 +
      <td>обязательный параметр, int (числовое значение)</td>
 +
  </tr>
 +
  <tr bgcolor = #F5F5F5>
 +
      <td>age</td>
 +
      <td>Возраст целевой аудитории. Номер возрастной категории от 1 до 6 (до 17, 18-25, 26-34, 35-49, 50-60, старше 61)</td>
 +
      <td>обязательный параметр, последовательность чисел, разделенных запятой</td>
 +
  </tr>
 +
  <tr bgcolor = #F5F5F5>
 +
      <td>regions</td>
 +
      <td>Регионы, от 1 до 10 (1 - Россия, 2 - Украина и т.д.)</td>
 +
      <td>обязательный параметр, последовательность чисел, разделенных запятой</td>
 +
  </tr>
 +
  <tr bgcolor = #F5F5F5>
 +
      <td>cpa_mode</td>
 +
      <td>Тип уведомлений о конверсий для CPA: /ads.targeting.modes.get</td>
 +
      <td>int (числовое значение), обязательное для CPA кампании</td>
 +
  </tr>
 +
  <tr bgcolor = #F5F5F5>
 +
      <td>categories</td>
 +
      <td><p>идентификаторы категорий:</p>
 +
          <p>/data.categories.get?ad_format=%</p>
 +
         
 +
      </td>
 +
      <td><p>масив [category_id => cost]</p></td>
 +
  </tr>
 +
  <tr bgcolor = #F5F5F5>
 +
      <td>tags</td>
 +
      <td>таргетинг по ключевым словам</td>
 +
      <td><p>обязательный параметр, последовательность ключевых слов, разделенных запятой: [“key1”, “key2”, .., “keyN”]</p>
 +
          <p>Ключевые слова с ценой. Только для оплаты - за клики или за показы: {“key1”: “cost”, “key2”: “cost”, .., “keyN”: “cost”}</p>
 +
          <p>cost - float</p>
 +
          <p>пример: "data[tags][qwerty]: 1" - ключевое слово qwerty со ставкой 1руб.</p>
 +
      </td>
 +
  </tr>
 +
  <tr bgcolor = #F5F5F5>
 +
      <td>day_limit</td>
 +
      <td>Дневной лимит в рублях. Для всех типов кроме clickunder</td>
 +
      <td>положительное число</td>
 +
  </tr>
 +
  <tr bgcolor = #F5F5F5>
 +
      <td>all_limit</td>
 +
      <td>Общий лимит в рублях. Для всех типов кроме clickunder</td>
 +
      <td>положительное число</td>
 +
  </tr>
 +
  <tr bgcolor = #F5F5F5>
 +
      <td>click_limit</td>
 +
      <td>Максимальное кол. переходов в день. Для всех типов кроме clickunder. За показы и за клики.</td>
 +
      <td>положительное число</td>
 +
  </tr>
 +
  <tr bgcolor = #F5F5F5>
 +
      <td>conversion_limit</td>
 +
      <td>Максимальное кол. конверсий в день. Для всех типов кроме clickunder. Только для CPA</td>
 +
      <td>положительное число</td>
 +
  </tr>
 +
  <tr bgcolor = #F5F5F5>
 +
      <td>adult_content</td>
 +
      <td>присутсвие контента для взрослых в рекламной кампании:
 +
          <p>0 - Нет;</p>
 +
          <p>1 - Да</p>
 +
      </td>
 +
      <td>необязательный параметр, int (числовое значение), по умолчанию 0</td>
 +
  </tr>
 +
  <tr bgcolor = #F5F5F5>
 +
      <td>adult_site</td>
 +
      <td>Отображать объявления кампании на сайтах с контентом для взрослых:
 +
          <p>0 - Нет;</p>
 +
          <p>1 - Да</p>
 +
      </td>
 +
      <td>необязательный параметр, int (числовое значение), по умолчанию 0</td>
 +
  </tr>
 +
  <tr bgcolor = #F5F5F5>
 +
      <td>time_show</td>
 +
      <td>Временной таргетинг:
 +
          <p>&nbsp;&nbsp; * - отображение в любые часы и дни недели</p>
 +
          <p>&nbsp;&nbsp; {} - массив, где ключ имя дня недели ["Sn","Mn","Tu","Wd","Th","Fr","Sa"]:</p>
 +
          <p>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; {} - ‘mn’: ‘*’ - все часы понендельника</p>
 +
          <p>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; {} - ‘mn’: [0, .., 23] - часы через запятую</p>
 +
      </td>
 +
      <td>необязательный параметр, * по умолчанию</td>
 +
  </tr>
 +
  <tr bgcolor = #F5F5F5>
 +
      <td>platforms</td>
 +
      <td>таргетинг по платформам:  /data.platforms</td>
 +
      <td>последовательность чисел, разделенных запятой</td>
 +
  </tr>
 +
  <tr bgcolor = #F5F5F5>
 +
      <td>browsers</td>
 +
      <td>таргетинг по браузерам:  /data.browsers</td>
 +
      <td>последовательность чисел, разделенных запятой</td>
 +
  </tr>
 +
  <tr bgcolor = #F5F5F5>
 +
      <td>black_list</td>
 +
      <td>черный список площадок на которых не будет показана реклама</td>
 +
      <td>последовательность чисел ID площадок, разделенных запятой</td>
 +
  </tr>
 +
  <tr bgcolor = #F5F5F5>
 +
      <td>white_list</td>
 +
      <td>белый список площадок на которых не будет показана реклама</td>
 +
      <td>последовательность чисел ID площадок, разделенных запятой</td>
 +
  </tr>
 +
  <tr bgcolor = #F5F5F5>
 +
      <td>black_list_ip</td>
 +
      <td>блокировка по ip</td>
 +
      <td>последовательность ip адресов, разделенных запятой или массивом</td>
 +
  </tr>
 +
  <tr bgcolor = #F5F5F5>
 +
      <td>unique_day_count</td>
 +
      <td>частота показов материала одному пользователю (разы)</td>
 +
      <td>положительное число</td>
 +
  </tr>
 +
  <tr bgcolor = #F5F5F5>
 +
      <td>unique_days</td>
 +
      <td>частота показов рекламного материала одному пользователю (дни)</td>
 +
      <td>положительное число</td>
 +
  </tr>
 +
</table>
 +
<b>Результат:</b><br/>
 +
Возвращает массив ответов на запросы в массиве data. Соответствующий объект в выходном массиве содержит id созданной кампании, и поля error_code и error_desc в случае возникновения ошибки.
 +
<p>Errors:</p>
 +
<pre>  102 - unknown client
 +
  103 - overlimit campaigns</pre>
 +
 +
==Редактирование рекламных кампаний==
 +
Для редактирования рекламных кампаний используется метод <b>ads.campaigns.update</b><br>
 +
Максимальное допустимое количество кампаний, редактируемых с помощью одного запроса — 50.<br>
 +
Version log: 1.0.1 - добавлен параметр status
 +
<table>
 +
  <tr bgcolor = #DCDCDC>
 +
      <th width = 130 align = left>Параметры</th>
 +
      <th width = 300 align = left>Значение</th>
 +
      <th width = 350 align = left>Дополнительные атрибуты</th>
 +
  </tr>
 +
  <tr bgcolor = #F5F5F5>
 +
      <td>data</td>
 +
      <td>сериализованный JSON-массив объектов, описывающих изменения в кампаниях. Описание объектов client_mod_specification см. ниже.</td>
 +
      <td>обязательный параметр, строка</td>
 +
  </tr>
 +
  <tr bgcolor = #F5F5F5>
 +
      <td>client_specification</td>
 +
  </tr>
 +
  <tr bgcolor = #F5F5F5>
 +
      <td>campaign_id</td>
 +
      <td>id редактируемой кампании
 +
      </td>
 +
      <td>обязательный параметр, положительное число</td>
 +
  </tr>
 +
  <tr bgcolor = #F5F5F5>
 +
      <td>name</td>
 +
      <td>название кампании</td>
 +
      <td>необязательный параметр, строка длиной от 3 до 60 символов</td>
 +
  </tr>
 +
  <tr bgcolor = #F5F5F5>
 +
      <td>link_url</td>
 +
      <td>ссылка на рекламируемый объект в формате http://yoursite.cоm</td>
 +
      <td>необязательный параметр, строка</td>
 +
  </tr>
 +
  <tr bgcolor = #F5F5F5>
 +
      <td>real_url</td>
 +
      <td>ссылка на реальный домен рекламируемого объекта в формате: http://yoursite.cоm
 +
      </td>
 +
      <td>необязательный параметр, строка</td>
 +
  </tr>
 +
  <tr bgcolor = #F5F5F5>
 +
      <td>sex</td>
 +
      <td>Пол:
 +
          <p>3 - любой;</p>
 +
          <p>2 - мужской;</p>
 +
          <p>1 - женский</p>
 +
      </td>
 +
      <td>необязательный параметр, int (числовое значение)</td>
 +
  </tr>
 +
  <tr bgcolor = #F5F5F5>
 +
      <td>age</td>
 +
      <td>возраст: /data.ages</td>
 +
      <td>необязательный параметр, int (числовое значение)</td>
 +
  </tr>
 +
  <tr bgcolor = #F5F5F5>
 +
      <td>categories</td>
 +
      <td>идентификаторы категорий:
 +
          <p>/data.categories.get?ad_format=%</p>
 +
          <p>category_id: {region_id: cost}</p>
 +
      </td>
 +
      <td>необязательный параметр</td>
 +
  </tr>
 +
  <tr bgcolor = #F5F5F5>
 +
      <td>tags</td>
 +
      <td>таргетинг по ключевым словам</td>
 +
      <td>необязательный параметр, последовательность ключевых слов, разделенных запятой</td>
 +
  </tr>
 +
  <tr bgcolor = #F5F5F5>
 +
      <td>day_limit</td>
 +
      <td>дневной лимит в рублях. для всех типов кроме clickunder</td>
 +
      <td>необязательный параметр, положительное число</td>
 +
  </tr>
 +
  <tr bgcolor = #F5F5F5>
 +
      <td>adult_content</td>
 +
      <td>присутсвие контента для взрослых в рекламной кампании:
 +
          <p>0 - Нет;</p>
 +
          <p>1 - Да</p>
 +
      </td>
 +
      <td>необязательный параметр, int (числовое значение), по умолчанию 0</td>
 +
  </tr>
 +
  <tr bgcolor = #F5F5F5>
 +
      <td>adult_site</td>
 +
      <td>отображать объявления кампании на сайтах с контентом для взрослых:
 +
          <p>0 - Нет;</p>
 +
          <p>1 - Да</p>
 +
      </td>
 +
      <td>необязательный параметр, int (числовое значение), по умолчанию 0</td>
 +
  </tr>
 +
  <tr bgcolor = #F5F5F5>
 +
      <td>time_show</td>
 +
      <td>Временной таргетинг:
 +
          <p>&nbsp;&nbsp; * - отображение в любые часы и дни недели</p>
 +
          <p>&nbsp;&nbsp; {} - массив, где ключ имя дня недели ["Sn","Mn","Tu","Wd","Th","Fr","Sa"]:</p>
 +
          <p>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; {} - ‘mn’: ‘*’ - все часы понендельника</p>
 +
          <p>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; {} - ‘mn’: [0, .., 23] - часы через запятую</p>
 +
      </td>
 +
      <td>необязательный параметр, * по умолчанию</td>
 +
  </tr>
 +
  <tr bgcolor = #F5F5F5>
 +
      <td>platforms</td>
 +
      <td>таргетинг по платформам:  /data.platforms</td>
 +
      <td>последовательность чисел, разделенных запятой</td>
 +
  </tr>
 +
  <tr bgcolor = #F5F5F5>
 +
      <td>browsers</td>
 +
      <td>таргетинг по браузерам:  /data.browsers</td>
 +
      <td>последовательность чисел, разделенных запятой</td>
 +
  </tr>
 +
  <tr bgcolor = #F5F5F5>
 +
      <td>black_list</td>
 +
      <td>черный список площадок на которых не будет показана реклама</td>
 +
      <td>последовательность чисел ID площадок, разделенных запятой</td>
 +
  </tr>
 +
  <tr bgcolor = #F5F5F5>
 +
      <td>white_list</td>
 +
      <td>белый список площадок на которых не будет показана реклама</td>
 +
      <td>последовательность чисел ID площадок, разделенных запятой</td>
 +
  </tr>
 +
  <tr bgcolor = #F5F5F5>
 +
      <td>black_list_ip</td>
 +
      <td>блокировка по ip</td>
 +
      <td>последовательность ip адресов, разделенных запятой или массивом</td>
 +
  </tr>
 +
  <tr bgcolor = #F5F5F5>
 +
      <td>status</td>
 +
      <td>запуск/приостановка кампании:
 +
          <p>0 - приостановлена;</p>
 +
          <p>1 - запущена</p>
 +
      </td>
 +
      <td>необязательный параметр, int (числовое значение), по умолчанию 1</td>
 +
  </tr>
 +
</table>
 +
<b>Результат:</b><br/>
 +
Возвращает массив ответов на каждый запрос в массиве data. Соответствующий объект в выходном массиве содержит id изменяемого клиента и, в случае возникновения ошибки, поля error_code и error_desc.
 +
<p>Errors:</p>
 +
<pre>  100 - unknown campaign
 +
  102 - unknown client</pre>
 +
 +
==Список кампаний рекламного кабинета==
 +
Для получения списка кампаний рекламного кабинета используется метод <b>ads.campaigns.get</b>
 +
 +
<table>
 +
  <tr bgcolor = #DCDCDC>
 +
      <th width = 130 align = left>Параметры</th>
 +
      <th width = 300 align = left>Значение</th>
 +
      <th width = 350 align = left>Дополнительные атрибуты</th>
 +
  </tr>
 +
  <tr bgcolor = #F5F5F5>
 +
      <td>client_id</td>
 +
      <td>Идентификатор клиента, у которого запрашиваются рекламные кампании</td>
 +
      <td>int (числовое значение)</td>
 +
  </tr>
 +
  <tr bgcolor = #F5F5F5>
 +
      <td>include_archive</td>
 +
      <td>Флаг, задающий необходимость вывода архивных объявлений:
 +
          <p>0 - выводить только активные кампании;</p>
 +
          <p>1 - выводить все кампании</p>
 +
      </td>
 +
      <td>Флаг, может принимать значения 1 или 0</td>
 +
  </tr>
 +
  <tr bgcolor = #F5F5F5>
 +
      <td>campaign_ids</td>
 +
      <td>Фильтр выводимых рекламных кампаний.
 +
          <p>Сериализованный JSON-массив, содержащий id кампаний. Выводиться будут только кампании, присутствующие в campaign_ids и являющиеся кампаниями указанного рекламного кабинета. Если параметр равен null, то выводиться будут все кампании.</p>
 +
      </td>
 +
      <td>Строка</td>
 +
  </tr>
 +
  <tr bgcolor = #F5F5F5>
 +
      <td>with_bwlist</td>
 +
      <td>Флаг передачи блек- и вайт-листов</td>
 +
      <td>любое значение (например 1)</td>
 +
  </tr>
 +
  <tr bgcolor = #F5F5F5>
 +
      <td>with_tags</td>
 +
      <td>Флаг передачи ключевых слов</td>
 +
      <td>любое значение (например 1)</td>
 +
  </tr>
 +
  <tr bgcolor = #F5F5F5>
 +
      <td>limit</td>
 +
      <td>ограничение на количество возвращаемых кампаний. Используется, только если параметр campaign_ids равен null</td>
 +
      <td>int (числовое значение)</td>
 +
  </tr>
 +
  <tr bgcolor = #F5F5F5>
 +
      <td>offset</td>
 +
      <td>смещение. Используется в тех же случаях, что и параметр limit</td>
 +
      <td>int (числовое значение)</td>
 +
  </tr>
 +
</table>
 +
<b>Результат:</b><br/>
 +
Возвращает массив объектов campaign, каждый из которых содержит следующие поля:
 +
<code>
 +
<pre>
 +
response: {
 +
      count: %total%,
 +
      items: [{
 +
  id — идентификатор кампании
 +
  name — название кампании
 +
  status — статус кампании (0 — кампания остановлена, 1 — кампания запущена, 2 — кампания удалена)
 +
  day_limit — дневной лимит кампании в рублях (0 — лимит не задан)
 +
  all_limit — общий лимит кампании в рублях (0 — лимит не задан)
 +
  ad_format — формат объявления
 +
  cost_type — тип оплаты
 +
  link_url - ссылка на рекламируемый объект
 +
  sex - пол
 +
  age - возраст
 +
  regions - идентификаторы регионов
 +
  categories - идентификаторы категорий.
 +
  adult_content - присутсвие контент для взрослых
 +
  adult_site - отображение объявлений кампании на сайтах с контентом для взрослых
 +
          tags - ключевые слова
 +
          bw_list - блек- и вайт-лист
 +
      },..]
 +
}
 +
</pre>
 +
</code>
 +
<p>Errors:</p>
 +
<pre>  102 - unknown client</pre>
 +
 +
==Архивирование рекламной кампании==
 +
Для архивирования рекламной кампании используется метод <b>ads.campaigns.delete</b><br>
 +
Максимальное допустимое количество клиентов, редактируемых с помощью одного запроса — 10.<br/>
 +
 +
<table>
 +
  <tr bgcolor = #DCDCDC>
 +
      <th width = 130 align = left>Параметры</th>
 +
      <th width = 300 align = left>Значение</th>
 +
      <th width = 350 align = left>Дополнительные атрибуты</th>
 +
  </tr>
 +
  <tr bgcolor = #F5F5F5>
 +
      <td>ids</td>
 +
      <td>Список id кампаний через запятую или массив с id кампаниями.
 +
          <p>Например:</p>
 +
          <p>“id1, id2, …, idn“ или [id1, id2, …, idn]</p>
 +
      </td>
 +
      <td>обязательный параметр, строка</td>
 +
  </tr>
 +
</table>
 +
<b>Результат:</b><br/>
 +
Возвращает массив ответов на каждый запрос. Каждый ответ является либо 0, что означает успешное удаление, либо массив error.
 +
<p>Errors:</p>
 +
<pre>  100 - unknown campaign
 +
  101 - campaign already archive
 +
  102 - unknown client</pre>
 +
 +
==Получение кодов для СРА кампаний==
 +
Для получения кодов по СРА кампаниям используется метод <b>ads.campaigns.cpa.mode.get</b><br/>
 +
 +
<table>
 +
  <tr bgcolor = #DCDCDC>
 +
      <th width = 130 align = left>Параметры</th>
 +
      <th width = 300 align = left>Значение</th>
 +
      <th width = 350 align = left>Дополнительные атрибуты</th>
 +
  </tr>
 +
  <tr bgcolor = #F5F5F5>
 +
      <td>campaign_id</td>
 +
      <td>id кампании</td>
 +
      <td>int (числовое значение), обязательный параметр</td>
 +
  </tr>
 +
</table>
 +
<b>Результат:</b><br/>
 +
Возвращает объект с данными.
 +
<code>
 +
<pre>
 +
{
 +
response: {
 +
url: %url%
 +
                  }
 +
}
 +
</pre>
 +
</code>
 +
 +
==Получение списка категорий по заданому фильтру==
 +
Для возврата списка категорий по заданому фильтру используется метод <b>ads.campaigns.categories.get</b><br/>
 +
 +
<table>
 +
  <tr bgcolor = #DCDCDC>
 +
      <th width = 130 align = left>Параметры</th>
 +
      <th width = 300 align = left>Значение</th>
 +
      <th width = 350 align = left>Дополнительные атрибуты</th>
 +
  </tr>
 +
  <tr bgcolor = #F5F5F5>
 +
      <td>ad_format</td>
 +
      <td>формат объявления:
 +
            <p>ads.campaigns.foarmats.get</p>
 +
      </td>
 +
      <td>обязательный параметр, int (числовое значение)</td>
 +
  </tr>
 +
  <tr bgcolor = #F5F5F5>
 +
      <td>category_id</td>
 +
      <td>id категории. ограничивает отображение только по id категории</td>
 +
      <td>необязательный параметр,  int (числовое значение)</td>
 +
  </tr>
 +
</table>
 +
<b>Результат:</b><br/>
 +
Возвращает массив ответов на запросы в массиве response.
 +
<code>
 +
<pre>
 +
response: {
 +
            count: %total%,
 +
            items: [{
 +
                      %category_id%: {
 +
                            %region_id%: {
 +
                        min: %min_cost%,
 +
                        max: %max_cost%
 +
                            }
 +
                      }
 +
                  },..]
 +
}
 +
</pre>
 +
</code>
 +
 +
==Получение списка форматов объявлений==
 +
Для получения списка форматов объявлений используется метод <b>ads.campaigns.formats.get</b><br/>
 +
 +
<b>Результат:</b><br/>
 +
Возвращает массив ответов на запросы в массиве response.
 +
<code>
 +
<pre>
 +
response: {
 +
      count: %total%,
 +
      items: [{
 +
            id: %format_id%,
 +
            title: ‘%format title%’
 +
      },..]
 +
}
 +
</pre>
 +
</code>
 +
 +
==Получение списка платформ==
 +
Для получения списка платформ используется метод <b>ads.targeting.platforms.get</b><br/>
 +
 +
<b>Результат:</b><br/>
 +
Возвращает массив ответов на запросы в массиве response. 
 +
<code>
 +
<pre>
 +
response: {
 +
      count: %,
 +
      items: [{
 +
          id: %platform_id%,
 +
          title: %platform_name%,
 +
          mobile: %is mobile%
 +
      },..]
 +
}
 +
</pre>
 +
</code>
 +
 +
==Получение списка браузеров==
 +
Для получения списка браузеров используется метод <b>ads.targeting.browsers.get</b><br/>
 +
 +
<b>Результат:</b><br/>
 +
Возвращает массив ответов на запросы в массиве response. 
 +
<code>
 +
<pre>
 +
response: {
 +
      count: %,
 +
      items: [{
 +
          id: %browser_id%,
 +
          title: %browser_name%,
 +
      },..]
 +
}
 +
</pre>
 +
</code>
 +
 +
==Получение списка уведомлений о конверсиях для СРА==
 +
Для получения списка уведомлений о конверсиях для СРА используется метод <b>ads.targeting.cpa.modes.get</b><br/>
 +
 +
<b>Результат:</b><br/>
 +
Возвращает массив ответов на запросы в массиве response. 
 +
<code>
 +
<pre>
 +
response: {
 +
      count: %total%,
 +
      items: [{
 +
          id: %mode_id%,
 +
          title: ‘%mode title%’
 +
      },..]
 +
}
 +
</pre>
 +
</code>
 +
 +
==Получение списка возрастов==
 +
Для получения списка возврастов используется метод <b>ads.targeting.ages.get</b><br/>
 +
 +
<b>Результат:</b><br/>
 +
Возвращает массив ответов на запросы в массиве response. 
 +
<code>
 +
<pre>
 +
response: {
 +
      count: %,
 +
      items: [{
 +
          id: %age_id%,
 +
          title: %age_name%
 +
      },..]
 +
}
 +
</pre>
 +
</code>
 +
 +
==Создание клиентов рекламного агенства==
 +
Для создания клиентов рекламного агенства используется метод <b>ads.clients.put</b><br/>
 +
Допустимое количество создаваемых клиентов с помощью одного запроса — 50.
 +
 +
<table>
 +
  <tr bgcolor = #DCDCDC>
 +
      <th width = 130 align = left>Параметры</th>
 +
      <th width = 300 align = left>Значение</th>
 +
      <th width = 350 align = left>Дополнительные атрибуты</th>
 +
  </tr>
 +
  <tr bgcolor = #F5F5F5>
 +
      <td>data</td>
 +
      <td>сериализованный JSON-массив объектов, описывающих создаваемые кампании. Описание объектов client_specification см. ниже.</td>
 +
      <td>обязательный параметр, строка</td>
 +
  </tr>
 +
  <tr bgcolor = #F5F5F5>
 +
      <td>client_specification</td>
 +
  </tr>
 +
  <tr bgcolor = #F5F5F5>
 +
      <td>name</td>
 +
      <td>название клиента</td>
 +
      <td>строка от 3 до 60 символов, обязательный параметр</td>
 +
  </tr>
 +
  <tr bgcolor = #F5F5F5>
 +
      <td>day_limit</td>
 +
      <td>дневной лимит в рублях</td>
 +
      <td>int (числовое значение)</td>
 +
  </tr>
 +
</table>
 +
 +
<b>Результат:</b><br/>
 +
Возвращает массив ответов на запросы в массиве data. Соответствующий объект в выходном массиве содержит информацию клиента или массив error  в случае возникновения ошибки (для каждого клиента отдельно).
 +
<code>
 +
<pre>
 +
{
 +
    client_id — идентификатор клиента;
 +
    name — название клиента;
 +
    day_limit — дневной лимит клиента в рублях;
 +
}
 +
</pre>
 +
</code>
 +
 +
==Редактирование клиентов рекламного агенства==
 +
Для редактирования клиентов рекламного агенства используется метод <b>ads.clients.update</b><br/>
 +
Максимальное допустимое количество клиентов, редактируемых с помощью одного запроса — 50.
 +
 +
<table>
 +
  <tr bgcolor = #DCDCDC>
 +
      <th width = 130 align = left>Параметры</th>
 +
      <th width = 300 align = left>Значение</th>
 +
      <th width = 350 align = left>Дополнительные атрибуты</th>
 +
  </tr>
 +
  <tr bgcolor = #F5F5F5>
 +
      <td>data</td>
 +
      <td>сериализованный JSON-массив объектов, описывающих изменения в клиентах. Описание объектов client_mod_specification см. ниже.          </td>
 +
      <td>обязательный параметр, строка</td>
 +
  </tr>
 +
  <tr bgcolor = #F5F5F5>
 +
      <td>client_mod_specification</td>
 +
  </tr>
 +
  <tr bgcolor = #F5F5F5>
 +
      <td>client_id</td>
 +
      <td>идентификатор редактируемого клиента</td>
 +
      <td>обязательный параметр, положительное число</td>
 +
  </tr>
 +
  <tr bgcolor = #F5F5F5>
 +
      <td>name</td>
 +
      <td>название клиента</td>
 +
      <td>строка длиной от 3 до 60 символов</td>
 +
  </tr>
 +
  <tr bgcolor = #F5F5F5>
 +
      <td>day_limit</td>
 +
      <td>дневной лимит в рублях</td>
 +
      <td>положительное число</td>
 +
  </tr>
 +
</table>
 +
 +
<b>Результат:</b><br/>
 +
Возвращает массив ответов на каждый запрос в массиве data. Соответствующий объект в выходном массиве содержит id изменяемого клиента и, в случае возникновения ошибки, поля error_code иerror_desc.
 +
 +
==Получение списка клиентов рекламного агенства==
 +
Для возврата списка клиентов рекламного агенства используется метод <b>ads.clients.get</b><br/>
 +
 +
<table>
 +
  <tr bgcolor = #DCDCDC>
 +
      <th width = 130 align = left>Параметры</th>
 +
      <th width = 300 align = left>Значение</th>
 +
      <th width = 350 align = left>Дополнительные атрибуты</th>
 +
  </tr>
 +
  <tr bgcolor = #F5F5F5>
 +
      <td>client_ids</td>
 +
      <td>Список id клиентов через запятую. Например: “id1, id2, …, idn“</td>
 +
      <td>необязательный параметр, строка</td>
 +
  </tr>
 +
 +
</table>
 +
 +
<b>Результат:</b><br/>
 +
Возвращает массив объектов client — клиентов агентства, каждый из которых содержит следующие поля:
 +
<code>
 +
<pre>
 +
response: {
 +
      count: %total%,
 +
      items: [{
 +
          client_id — идентификатор клиента;
 +
          name — название клиента;
 +
          day_limit — дневной лимит клиента в рублях;
 +
          balance - баланс клиента
 +
      },..]
 +
}
 +
</pre>
 +
</code>
 +
 +
==Архивирование клиентов рекламного агенства==
 +
Для архивирования клиентов рекламного агенства используется метод <b>ads.clients.delete</b><br/>
 +
 +
<table>
 +
  <tr bgcolor = #DCDCDC>
 +
      <th width = 130 align = left>Параметры</th>
 +
      <th width = 300 align = left>Значение</th>
 +
      <th width = 350 align = left>Дополнительные атрибуты</th>
 +
  </tr>
 +
  <tr bgcolor = #F5F5F5>
 +
      <td>ids</td>
 +
      <td>Список id клиентов через запятую или массив с id клиентами.
 +
            <p>Например: “id1, id2, …, idn“ или [id1, id2, …, idn]</p>
 +
      </td>
 +
      <td>обязательный параметр, строка</td>
 +
  </tr>
 +
 +
</table>
 +
 +
<b>Результат:</b><br/>
 +
Возвращает массив ответов на каждый запрос. Каждый ответ является либо 0, что означает успешное удаление, либо массив error.
 +
 +
==Подвязывание клиента к рекламному агенству==
 +
Для подвязывания клиента к рекламному агенству используется метод <b>ads.clients.bind.put</b><br/>
 +
 +
<table>
 +
  <tr bgcolor = #DCDCDC>
 +
      <th width = 130 align = left>Параметры</th>
 +
      <th width = 300 align = left>Значение</th>
 +
      <th width = 350 align = left>Дополнительные атрибуты</th>
 +
  </tr>
 +
  <tr bgcolor = #F5F5F5>
 +
      <td>email</td>
 +
      <td>email адрес клиента</td>
 +
      <td>строка от 3 до 60 символов, обязательный параметр</td>
 +
  </tr>
 +
  <tr bgcolor = #F5F5F5>
 +
      <td>password</td>
 +
      <td>пароль клиента (от кабинета)</td>
 +
      <td>строка от 3 до 60 символов, обязательный параметр</td>
 +
  </tr>
 +
</table>
 +
 +
<b>Результат:</b><br/>
 +
Возвращает:
 +
<code>
 +
<pre>
 +
{
 +
“bind”: true
 +
}
 +
</pre>
 +
</code>
 +
в случае успеха. Или error в случае возникновения ошибки.
 +
 +
==Открепление клиента от рекламного агенства==
 +
Для открепления клиента от рекламного агенства используется метод <b>ads.clients.unbind.put</b><br/>
 +
 +
<table>
 +
  <tr bgcolor = #DCDCDC>
 +
      <th width = 130 align = left>Параметры</th>
 +
      <th width = 300 align = left>Значение</th>
 +
      <th width = 350 align = left>Дополнительные атрибуты</th>
 +
  </tr>
 +
  <tr bgcolor = #F5F5F5>
 +
      <td>client_id</td>
 +
      <td>id клиента</td>
 +
      <td>int (числовое значение)</td>
 +
  </tr>
 +
</table>
 +
 +
<b>Результат:</b><br/>
 +
Возвращает:
 +
<code>
 +
<pre>
 +
{
 +
“unbind”: true
 +
}
 +
</pre>
 +
</code>
 +
в случае успеха. Или error в случае возникновения ошибки.
 +
 +
==Пополнение счета клиента==
 +
Для пополнения счета клиента используется метод <b>ads.clients.balance.put</b><br/>
 +
 +
<table>
 +
  <tr bgcolor = #DCDCDC>
 +
      <th width = 130 align = left>Параметры</th>
 +
      <th width = 300 align = left>Значение</th>
 +
      <th width = 350 align = left>Дополнительные атрибуты</th>
 +
  </tr>
 +
  <tr bgcolor = #F5F5F5>
 +
      <td>client_id</td>
 +
      <td>id клиента для пополнения</td>
 +
      <td>int (числовое значение), обязательный параметр</td>
 +
  </tr>
 +
  <tr bgcolor = #F5F5F5>
 +
      <td>sum</td>
 +
      <td>сума в рублях</td>
 +
      <td>int (числовое значение)</td>
 +
  </tr>
 +
  <tr bgcolor = #F5F5F5>
 +
      <td>back_url</td>
 +
      <td>url куда переадресует клиента система пополнения</td>
 +
      <td>string (строка)</td>
 +
  </tr>
 +
  <tr bgcolor = #F5F5F5>
 +
      <td>system_id</td>
 +
      <td>id системы пополнения:
 +
            <p>data.balance.systems.get</p>
 +
      </td>
 +
      <td>int (числовое значение), обязательный параметр</td>
 +
  </tr>
 +
</table>
 +
 +
<b>Результат:</b><br/>
 +
Возвращает url для оплаты:
 +
<code>
 +
<pre>
 +
{
 +
response: {
 +
url: %url%
 +
                  }
 +
}
 +
 +
</pre>
 +
</code>
 +
 +
==Создание рекламных объявлений==
 +
Для создания рекламных объявлений используется метод <b>ads.materials.put</b><br/>
 +
Максимальное допустимое количество объявлений, создаваемых с помощью одного запроса — 20.
 +
 +
<table>
 +
  <tr bgcolor = #DCDCDC>
 +
      <th width = 130 align = left>Параметры</th>
 +
      <th width = 300 align = left>Значение</th>
 +
      <th width = 350 align = left>Дополнительные атрибуты</th>
 +
  </tr>
 +
  <tr bgcolor = #F5F5F5>
 +
      <td>data</td>
 +
      <td>сериализованный JSON-массив объектов, описывающих создаваемые объявления. Описание объектов ad_specification см. ниже. </td>
 +
      <td>обязательный параметр, строка</td>
 +
  </tr>
 +
  <tr bgcolor = #F5F5F5>
 +
      <td>ad_specification</td>
 +
  </tr>
 +
  <tr bgcolor = #F5F5F5>
 +
      <td>campaign_id</td>
 +
      <td>id кампании, в которой будет создаваться объявление</td>
 +
      <td>обязательный параметр, int (числовое значение)</td>
 +
  </tr>
 +
  <tr bgcolor = #F5F5F5>
 +
      <td>title</td>
 +
      <td>заголовок объявления</td>
 +
      <td>обязательный параметр</td>
 +
  </tr>
 +
  <tr bgcolor = #F5F5F5>
 +
      <td>text</td>
 +
      <td>описание объявления</td>
 +
      <td>обязательно</td>
 +
  </tr>
 +
  <tr bgcolor = #F5F5F5>
 +
      <td>link_url</td>
 +
      <td>ссылка рекламируемого объекта в формате: http://yoursite.cоm</td>
 +
  </tr>
 +
  <tr bgcolor = #F5F5F5>
 +
      <td>link_media</td>
 +
      <td>загруженный ранее медиа объект (jpg, gif):
 +
              <p>data.upload.media</p>
 +
      </td>
 +
  </tr>
 +
  <tr bgcolor = #F5F5F5>
 +
      <td>pause_after_moderate</td>
 +
      <td>установка объявления на паузу после модерации</td>
 +
  </tr>
 +
  <tr bgcolor = #F5F5F5>
 +
      <td>size</td>
 +
      <td>только для банеров:
 +
              <p>ads.materials.banner.sizes</p>
 +
      </td>
 +
  </tr>
 +
  <tr bgcolor = #F5F5F5>
 +
      <td>categories</td>
 +
      <td>Стаки по категориям, аналогично как и для кампаний:
 +
        <p>массив [category_id => cost]</p>
 +
      </td>
 +
<td>Не обязательно, если не задавать будут использоваться ставки из категорий кампании</td>
 +
  </tr>
 +
</table>
 +
 +
==Обновление данных рекламных объявлений==
 +
Для обновления данных рекламных объявлений используется метод <b>ads.materials.update</b><br/>
 +
Максимальное допустимое количество объявлений, создаваемых с помощью одного запроса — 20.
 +
 +
<table>
 +
  <tr bgcolor = #DCDCDC>
 +
      <th width = 130 align = left>Параметры</th>
 +
      <th width = 300 align = left>Значение</th>
 +
      <th width = 350 align = left>Дополнительные атрибуты</th>
 +
  </tr>
 +
  <tr bgcolor = #F5F5F5>
 +
      <td>data</td>
 +
      <td>сериализованный JSON-массив объектов, описывающих создаваемые объявления. Описание объектов ad_specification см. ниже</td>
 +
      <td>обязательный параметр, строка</td>
 +
  </tr>
 +
  <tr bgcolor = #F5F5F5>
 +
      <td>ad_specification</td>
 +
  </tr>
 +
  <tr bgcolor = #F5F5F5>
 +
      <td>material_id</td>
 +
      <td>id объявления</td>
 +
      <td>обязательный параметр, int (числовое значение)</td>
 +
  </tr>
 +
  <tr bgcolor = #F5F5F5>
 +
      <td>status</td>
 +
      <td>запуск/приостановка материала:
 +
          <p>0 - приостановлена;</p>
 +
          <p>1 - запущена</p>
 +
      </td>
 +
      <td>необязательный параметр, int (числовое значение), по умолчанию 1</td>
 +
  </tr>
 +
</table>
 +
 +
==Архивирование рекламных объявлений==
 +
Для архивирования рекламных объявлений используется метод <b>ads.materials.delete</b><br/>
 +
Максимальное допустимое количество клиентов, редактируемых с помощью одного запроса — 50.
 +
 +
<table>
 +
  <tr bgcolor = #DCDCDC>
 +
      <th width = 130 align = left>Параметры</th>
 +
      <th width = 300 align = left>Значение</th>
 +
      <th width = 350 align = left>Дополнительные атрибуты</th>
 +
  </tr>
 +
  <tr bgcolor = #F5F5F5>
 +
      <td>account_id</td>
 +
      <td>идентификатор рекламного кабинета</td>
 +
      <td>обязательный параметр, int (числовое значение)</td>
 +
  </tr>
 +
  <tr bgcolor = #F5F5F5>
 +
      <td>ids</td>
 +
      <td>сериализованный JSON-массив, содержащий идентификаторы объявлений</td>
 +
      <td>обязательный параметр, строка</td>
 +
  </tr>
 +
</table>
 +
 +
<b>Результат:</b><br/>
 +
Возвращает массив ответов на каждый запрос. Каждый ответ является либо 0, что означает успешное удаление, либо массив error.
 +
 +
==Получение списка рекламных объявлений==
 +
Для получения списка рекламных объявлений используется метод <b>ads.materials.get</b>
 +
<table>
 +
  <tr bgcolor = #DCDCDC>
 +
      <th width = 130 align = left>Параметры</th>
 +
      <th width = 300 align = left>Значение</th>
 +
      <th width = 350 align = left>Дополнительные атрибуты</th>
 +
  </tr>
 +
  <tr bgcolor = #F5F5F5>
 +
      <td>account_id</td>
 +
      <td>идентификатор рекламного кабинета</td>
 +
      <td>обязательный параметр, int (числовое значение)</td>
 +
  </tr>
 +
  <tr bgcolor = #F5F5F5>
 +
      <td>client_id</td>
 +
      <td>Для рекламных агентств. Идентификатор клиента, у которого запрашиваются рекламные объявления.</td>
 +
      <td>int (числовое значение)</td>
 +
  </tr>
 +
  <tr bgcolor = #F5F5F5>
 +
      <td>archive</td>
 +
      <td>Флаг, задающий необходимость вывода архивных объявлений:
 +
          <p>0 - выводить только активные объявления;</p>
 +
          <p>1 - выводить все объявления</p>
 +
      </td>
 +
      <td>Флаг, может принимать значения 1 или 0</td>
 +
  </tr>
 +
  <tr bgcolor = #F5F5F5>
 +
      <td>campaign_ids</td>
 +
      <td>фильтр по рекламным кампаниям.
 +
            <p>Сериализованный JSON-массив, содержащий id кампаний. Если параметр равен null, то будут выводиться рекламные объявления всех кампаний.</p>
 +
      </td>
 +
      <td>строка</td>
 +
  </tr>
 +
  <tr bgcolor = #F5F5F5>
 +
      <td>material_ids</td>
 +
      <td>фильтр по рекламным кампаниям.
 +
            <p>Сериализованный JSON-массив, содержащий id объявлений. Если параметр равен null, то будут выводиться все рекламные объявления.</p>
 +
      </td>
 +
      <td>строка</td>
 +
  </tr>
 +
  <tr bgcolor = #F5F5F5>
 +
      <td>limit</td>
 +
      <td>ограничение на количество возвращаемых объявлений. Используется, только если параметр ad_ids равен null, а параметр campaign_ids содержит id только одной кампании.
 +
      </td>
 +
      <td>int (числовое значение)</td>
 +
  </tr>
 +
  <tr bgcolor = #F5F5F5>
 +
      <td>offset</td>
 +
      <td>смещение. Используется в тех же случаях, что и параметр limit</td>
 +
      <td>int (числовое значение)</td>
 +
  </tr>
 +
  <tr bgcolor = #F5F5F5>
 +
      <td>ad_format</td>
 +
      <td>формат объявления: ads.campaigns.formats.get</td>
 +
      <td>обязательный параметр, int (числовое значение)</td>
 +
  </tr>
 +
</table>
 +
 +
<b>Результат:</b><br/>
 +
Возвращает массив объектов ad, каждый из которых содержит следующие поля:
 +
  <ul type="disc">
 +
      <li><b>id</b> — идентификатор объявления</li>
 +
      <li><b>name</b> — название объявления</li>
 +
      <li><b>campaign_id</b> — идентификатор кампании</li>
 +
      <li><b>link_url</b></li>
 +
      <li><b>arhive</b></li>
 +
      <li><b>ad_format</b> — формат объявления</li>
 +
      <li><b>cost_type</b> — тип оплаты</li>
 +
      <li><b>all_limit</b> — общий лимит объявления в рублях</li>
 +
            <ul type="circle">
 +
                      <li>0 — лимит не задан</li>
 +
            </ul>
 +
      <li><b>status </b> — статус объявления:</li>
 +
            <ul type="circle">
 +
                      <li>0 — объявление остановлено;</li>
 +
                      <li>1 — объявление запущено;</li>
 +
                      <li>2 — объявление удалено</li>
 +
            </ul>
 +
      <li><b>approved </b> — статус модерации объявления:</li>
 +
            <ul type="circle">
 +
                      <li>0 — объявление ожидает модерации;</li>
 +
                      <li>10 — объявление одобрено;</li>
 +
                      <li>20 — объявление отклонено</li>
 +
            </ul>
 +
  </ul>
 +
 +
==Получение списка размеров баннеров==
 +
Для получение списка размеров баннеров используется метод <b>ads.materials.banner.sizes.get</b><br/>
 +
 +
<b>Результат:</b><br/>
 +
Возвращает массив ответов на запросы в массиве response:
 +
<code>
 +
<pre>
 +
response: {
 +
      count: %total%,
 +
      items: [{
 +
            id: %banner_id%,
 +
            title: ‘%banner title%’
 +
      },..]
 +
}
 +
</pre>
 +
</code>
 +
 +
==Получение списка стран==
 +
Для получение списка стран используется метод <b>data.geo.countries.get</b><br/>
 +
 +
<b>Результат:</b><br/>
 +
Возвращает массив ответов на запросы в массиве response:
 +
<code>
 +
<pre>
 +
response: {
 +
  count: %,
 +
  items: [{
 +
      id: %country_id%,
 +
      title: %country_name%
 +
  },..]
 +
}
 +
</pre>
 +
</code>
 +
 +
==Получение списка регионов по заданому фильтру==
 +
Для получения списка регионов по заданому фильтру используется метод <b>data.geo.regions.get</b><br/>
 +
 +
<table>
 +
  <tr bgcolor = #DCDCDC>
 +
      <th width = 130 align = left>Параметры</th>
 +
      <th width = 300 align = left>Значение</th>
 +
      <th width = 350 align = left>Дополнительные атрибуты</th>
 +
  </tr>
 +
  <tr bgcolor = #F5F5F5>
 +
      <td>country_id</td>
 +
      <td>идентификатор страны, полученный в методе ads.geo.countries</td>
 +
      <td>положительное число, обязательный параметр</td>
 +
  </tr>
 +
</table>
 +
 +
<b>Результат:</b><br/>
 +
Возвращает массив ответов на запросы в массиве response:
 +
<code>
 +
<pre>
 +
response: {
 +
        count: %,
 +
        items: [{
 +
              id: %region_id%,
 +
              title: %region_name%
 +
        },..]
 +
}
 +
</pre>
 +
</code>
 +
 +
==Получение списка доступных платежных систем==
 +
Для получения списка доступных платежных систем используется метод <b>data.balance.systems.get</b><br/>
 +
 +
<b>Результат:</b><br/>
 +
Возвращает массив ответов на запросы в массиве response:
 +
<code>
 +
<pre>
 +
response: {
 +
        count: %total%,
 +
        items: [{
 +
              id: %pay_system_id%,
 +
              title: ‘%pay system title%’
 +
        },..]
 +
}
 +
</pre>
 +
</code>
 +
 +
==Загрузка медиа файлов==
 +
Для загрузки медиа файлов (jpg, png, gif) используется метод <b>data.upload.media.update</b><br/>
 +
 +
<table>
 +
  <tr bgcolor = #DCDCDC>
 +
      <th width = 130 align = left>Параметры</th>
 +
      <th width = 300 align = left>Значение</th>
 +
      <th width = 350 align = left>Дополнительные атрибуты</th>
 +
  </tr>
 +
  <tr bgcolor = #F5F5F5>
 +
      <td>ad_format</td>
 +
      <td>формат объявления: /ads.formats.get</td>
 +
      <td>int (числовое значение)</td>
 +
  </tr>
 +
  <tr bgcolor = #F5F5F5>
 +
      <td>file</td>
 +
      <td>CURLFile object</td>
 +
  </tr>
 +
</table>
 +
 +
<b>Результат:</b><br/>
 +
Возвращает массив с ссылкой на конечный объект или error в случае ошибки
 +
<code>
 +
<pre>
 +
response: {
 +
        image: “%link%”
 +
}
 +
</pre>
 +
</code>
 +
Пример отправки файла с использование curl в php:
 +
<code>
 +
<pre>
 +
      $token = ‘полученный токен’;
 +
      $ad_format = ‘формат объявления’;
 +
      $app_id = ‘ваш app id’;
 +
      $file = '@/полный путь к файлу';
 +
</pre>
 +
<pre>
 +
      $finfo = finfo_open(FILEINFO_MIME_TYPE);
 +
      $finfo = finfo_file($finfo, $link);
 +
      $cFile = new \CURLFile($link, $finfo, basename($link));
 +
</pre>
 +
 +
<pre>
 +
      $post = array('file'=>$cFile, 'ad_format' => $ad_format, 'app_id' => $app_id);
 +
      $ignoreParams = array('file'); //поле file не участвует в построении подписи
 +
</pre>
 +
<pre>
 +
      ksort( $post );
 +
</pre>
 +
<pre>
 +
      $result = array ();
 +
      foreach( $post as $key => $value ) {
 +
        if(false == in_array($key, $ignoreParams)) {
 +
      $result[] = $key . '=' . urlencode( $value );
 +
        }
 +
      }
 +
</pre>
 +
<pre>
 +
      $result = implode( '&', $result );
 +
      $signature = md5( $result . $token );
 +
</pre>
 +
<pre>
 +
      $target_url = 'http://api.kadam.net/data.upload.media?signature=' . $signature;
 +
</pre>
 +
<pre>
 +
      $ch = curl_init();
 +
      curl_setopt($ch, CURLOPT_URL,$target_url);
 +
      curl_setopt($ch, CURLOPT_POST, true);
 +
      curl_setopt($ch, CURLOPT_POSTFIELDS, $post);
 +
      curl_setopt($ch, CURLOPT_RETURNTRANSFER,1);
 +
</pre>
 +
<pre>
 +
      $result = curl_exec ($ch); //ответ сервера
 +
</pre>
 +
</code>
 +
 +
==Получение текущего времени сервера==
 +
Для получения текущего времени сервера в формате ISO 8601 используется метод <b>server.time.get</b><br/>
 +
 +
<b>Результат:</b><br/>
 +
Возвращает массив ответов на запросы в массиве response:
 +
<code>
 +
<pre>
 +
      {
 +
          iso8601: %time%
 +
      }
 +
</pre>
 +
</code>
 +
 +
==Статистика для Вебмастера==
 +
Для получения статистики по вебмастерам используется метод <b>webmaster.reports.report.get</b><br/>
 +
 +
<table>
 +
  <tr bgcolor = #DCDCDC>
 +
      <th width = 130 align = left>Параметры</th>
 +
      <th width = 300 align = left>Значение</th>
 +
      <th width = 350 align = left>Дополнительные атрибуты</th>
 +
  </tr>
 +
  <tr bgcolor = #F5F5F5>
 +
      <td>secret</td>
 +
      <td>Ключ доступа для вебмастера(обязательный)</td>
 +
      <td>Можно получить по требованию</td>
 +
  </tr>
 +
  <tr bgcolor = #F5F5F5>
 +
      <td>date_from</td>
 +
      <td>Начало периода</td>
 +
      <td>строка вида "YYYY-MM-DD", не обязательный параметр, в случае отсутствия будет взята текущая дата</td>
 +
  </tr>
 +
  <tr bgcolor = #F5F5F5>
 +
      <td>date_to</td>
 +
      <td>Окончание периода</td>
 +
      <td>строка вида "YYYY-MM-DD", не обязательный параметр, в случае отсутствия будет взята текущая дата</td>
 +
  </tr>       
 +
</table>
 +
<b>Максимальный период выгрузки 1 месяц</b><br/>
 +
<b>Результат:</b><br/>
 +
  <ul type="disc">
 +
      <li><b>blockviews</b> — К-во просмотров блоков</li>
 +
      <li><b>moneyin</b> — Заработано денег</li>
 +
</ul>
 +
Возвращает данные в виде
 +
<code>
 +
<pre>
 +
Array
 +
(
 +
    [responce] => Array
 +
        (
 +
            [2017-11-10] => Array
 +
                (
 +
                    [blockviews] => 300
 +
                    [moneyin] => 100.00
 +
                )
 +
 +
        )
 +
 +
)
 +
</pre>
 +
</code>
 +
 +
==Перевода денег для дочерних аккаунтов агенства==
 +
Для перевода денег используется метод <b>ads.clients.balance.update</b><br/>
 +
 +
<table>
 +
  <tr bgcolor = #DCDCDC>
 +
      <th width = 130 align = left>Параметры</th>
 +
      <th width = 300 align = left>Значение</th>
 +
      <th width = 350 align = left>Дополнительные атрибуты</th>
 +
  </tr>
 +
  <tr bgcolor = #F5F5F5>
 +
      <td>client_id</td>
 +
      <td>Идентификатор клиента, ему будут перечислены деньги.</td>
 +
      <td>Обязательное</td>
 +
  </tr>
 +
  <tr bgcolor = #F5F5F5>
 +
      <td>sum</td>
 +
      <td>сумма перевода</td>
 +
      <td>Обязательное</td>
 +
  </tr>
 +
  <tr bgcolor = #F5F5F5>
 +
      <td>type</td>
 +
      <td>Тип операции</td>
 +
      <td>Обязательное - всегда type = "transfer"</td>
 +
  </tr>       
 +
<tr bgcolor = #F5F5F5>
 +
      <td>comment</td>
 +
      <td>Комментарий</td>
 +
      <td>Обязательное - допускается пустое значение</td>
 +
  </tr>       
 +
</table>
 +
<b>Операцию можно совершать только при наличии достаточного кол-ва средств на аккаунте</b><br/>
 +
<b>Деньни будут сняты у поьзователя указанного в app_id </b><br/>
 +
<b>Результат:</b><br/>
 +
Результатом операции будет списание средств с основного пользователя - транзакция вывода. И перевод денег на аккаунт агенства - транзакция ввода.
 +
 +
Возвращает данные в виде
 +
<code>
 +
<pre>
 +
Array
 +
(
 +
    [status] => "success"
 +
 +
)
 +
</pre>
 +
В случае ошибки - код ошибки
 +
</code>

Revision as of 13:28, 21 January 2019

Contents

API authorization

To access the API, you will need a user ID (app_id) and a signature (signature). Calling different methods is carried out using queries on this template:

        api.kadam.net?%action%.%method%?%params%
        % action% - what are we turning to
        % method% - type of treatment
get - get
put - write
post - update
delete - delete
        % params% - request parameters

        required parameters% params%

        app_id - user id
        signature - signature

Example:

       [GET] http://api.kadam.net/campaigns.get?app_id=%app_id%&signature=%signature%

or

       [GET] http://api.kadam.net/campaigns?app_id=%app_id%&signature=%signature%
       [GET] - http access method

Signature (signature) is created using a temporary token (access_token), which can be obtained using the app_id and secret key parameters.
Parameters app_id (user ID) and the key "secret key" are available on request to support.
Getting a token:

       [GET] http://api.kadam.net/auth.token?app_id=%app_id%&secret_key=%key%
       -> {“access_token”: “...”}

Generating signature for the [GET] method:

       md5 ( %sort_params% . %access_token% )
       %sort_params% - all parameters passed (except signature) are sorted by name

Example:

       app_id=1&campaign_id=3…
       [PUT] http://api.kadam.net/campaigns?signature=%signature%
       +post fields -> %params%

Example for php. Getting a list of campaigns:

       <?
        $your_secret_key = "jqhwekq8734quo37o498q3p498qp34";
       $your_app_id = 1;
       $auth_url = "http://api.kadam.net/auth.token?app_id={$your_app_id}&secret_key={$your_secret_key}";
       $auth = file_get_contents($auth_url);
       $auth = json_decode($auth, true);

       if ( !is_array( $auth ) || !isset( $auth['access_token'] ) ) {
           die( 'something wrong! ' . print_r( $res, true ) );
       }

       $token    = $auth['access_token'];
       $params = array(
	    'client_id' => $your_app_id,
        'app_id' => $your_app_id,
       );

       ksort( $params );

       $result = array ();
       foreach( $params as $key => $value ) {
           $result[] = $key . '=' . urlencode( $value );
       }
       $params = implode( '&', $result );
       $signature = md5( $params . $token );

       $campaign_url = 'http://api.kadam.net/ads.campaigns.get?' . $params . '&signature=' . $signature;

       $campaigns = file_get_contents($campaign_url);
       $campaigns = json_decode($campaigns, true);

       if ( !is_array( $campaigns ) || !isset( $campaigns['response'] ) ) {
           die( 'something wrong! ' . print_r( $campaigns, true ) );
       }
       
       print_r($campaigns);
       

Campaign Statistics

To get campaign statistics, use the method ads.analytic.campaign.get

Parameters Values Optional attributes
campaign_id campaign's id int (numeric value), required parameter
region_id region's id: data.geo.regions.get int (numeric value), required parameter
period The way data is grouped by date:

day — daily statistics;

month - monthly statistics

Temporary restrictions are set by parameters date_from and date_to

required parameter, string
date_from The starting date of the statistics to display. Different date format is used for different parameter period values:

day: YYYY-MM-DD, example: 2011-09-27;

month: YYYY-MM, example: 2011-09

required parameter, string
date_to The final date of the displayed statistics. Different date format is used for different parameter period values:

day: YYYY-MM-DD, example: 2011-09-27;

month: YYYY-MM, example: 2011-09

required parameter, string

Result:
Returns an object with data

{
	response: {
		count: %total items%
		items: {
			shows
			clicks
			ctr
			cpm
			money
                       }
                  }
}

Statistics on sites in the advertiser's office

Under the statistics on the sites in the office of the advertiser means statistics on impressions and clicks on the site in the context of each campaign.
To get statistics on sites, use the ads.campaigns.statblock.get method (GET request)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               
Parameters Value Additional attributes
date_from Start date of the statistics output. string, format YYYY-MM-DD (example: 2017-05-15), filter parameter
date_to The end date of the statistics output. string, format YYYY-MM-DD (example: 2017-05-15), filter parameter
campaign_id campaign id required parameter, int (numeric value), filter parameter
signature Signature (generated using a time token, see above) required parameter, string
app_id user id required parameter, int (numeric value)
macros site id int (numeric value), write parameter, filter option
leads Lida int (numeric value), write parameter, filter option
views Impressions int (numeric value), write parameter, filter option
clicks Clicks int (numeric value), write parameter, filter option
conversions Confirmed Conversions int (numeric value), write parameter, filter option
rejections Failed Conversions int (numeric value), write parameter, filter option
ctr CTR int (numeric value), write parameter, filter option
cpm CPM int (numeric value), write parameter, filter option
cpc CPC int (numeric value), write parameter, filter option
prelandvisit Prelend Visits int (numeric value), write parameter, filter option
prelanduseful Useful visits Prelend int (numeric value), write parameter, filter option
prelandscroll Prelend Scroll int (numeric value), write parameter, filter option

Result:
Returns an object with data, example:

{
  "response": {
    "count": 1,
    "items": [
      {
        "macros": "12345678901234",
        "block": "1234",
        "domain": "123456789",
        "leads": "0",
        "views": "123",
        "clicks": "0",
        "conversions": "0",
        "rejections": "0",
        "ctr": "0.0000",
        "cpm": "0.00",
        "cpc": null,
        "moneyOut": "0.000000",
        "moneyIn": null,
        "prelandvisit": "0",
        "prelanduseful": "0",
        "prelandscroll": "0",
        "landvisit": "0",
        "landuseful": "0",
        "landscroll": "0",
        "multiplier": null,
        "blackList": "0"
      }
    ],
    "request": {
      "campaignId": 123456,
      "limit": 10,
      "offset": 0
    }
  }
}

Sorting

Sort Ascending

sort = {parameter}
Example: api.kadam.net?sort=views

Sort descending

sort = - {parameter}
Example: api.kadam.net?sort=-views

Sort by several parameters

sort = {parameter1}, - {parameter2}, {parameter3}
Example: api.kadam.net?sort=views,-clicks,leads

Filtration

{parameter} = {value}
Examples:
api.kadam.net?attr=10
api.kadam.net?attr=string
api.kadam.net?attr=string&date_from=01.05.2016&date_to=01.07.2016

Изменение множителя для статистики по площадкам в кабинете рекламодателя

Для изменения множителя для статистики по площадкам используется метод ads.campaigns.statblock (PUT запрос)

Параметры (все являются обязательными):

  • app_id - id пользователя, числовое значение (int)
  • signature - подпись, строка (string)
  • campaign_id - id кампании, числовое значение (int)
  • block - числовое значение (int)
  • domain - числовое значение (int)
  • multiplier - новое значение множителя, числовое значение (float)
  • multiplierOld - старое значение множителя, числовое значение (float)
  • macros - id площадки, числовое значение (int)

Параметры block и macros в кабинете не выводятся, их можно получить через метод, описанный в пункте "Статистика по площадкам в кабинете рекламодателя".

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

Для получения статистики по всем материалам кампании используется метод ads.analytic.materials.get

Параметры Значение Дополнительные атрибуты
campaign_id id кампании int (числовое значение), обязательный параметр
period Способ группировки данных по датам:

1. day — статистика по дням;

2. month — статистика по месяцам;

Временные ограничения задаются параметрами date_from и date_to

обязательный параметр, строка
date_from Начальная дата выводимой статистики. Используется разный формат дат для разного значения параметра period:

1. day: YYYY-MM-DD, пример: 2011-09-27

2. month: YYYY-MM, пример: 2011-09

обязательный параметр, строка
date_to Конечная дата выводимой статистики. Используется разный формат дат для разного значения параметра period:

1. day: YYYY-MM-DD, пример: 2011-09-27

2. month: YYYY-MM, пример: 2011-09

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

Результат:
Возвращает объект с данными

{
	response: {
		count: %total items%
		items: {
			teaser_id
			date
			shows
			clicks
			ctr
			cpm
			money
                       }
                  }
}

Статистика по материалу

Для получения статистики по материалу используется метод ads.analytic.material.get

Параметры Значение Дополнительные атрибуты
material_id id материала int (числовое значение), обязательный параметр
period Способ группировки данных по датам:

1. day — статистика по дням;

2. month — статистика по месяцам;

Временные ограничения задаются параметрами date_from и date_to

обязательный параметр, строка
date_from Начальная дата выводимой статистики. Используется разный формат дат для разного значения параметра period:

1. day: YYYY-MM-DD, пример: 2011-09-27

2. month: YYYY-MM, пример: 2011-09

обязательный параметр, строка
date_to Конечная дата выводимой статистики. Используется разный формат дат для разного значения параметра period:

1. day: YYYY-MM-DD, пример: 2011-09-27

2. month: YYYY-MM, пример: 2011-09

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

Результат:
Возвращает объект с данными

{
	response: {
		count: %total items%
		items: {
			date
			shows
			clicks
			ctr
			cpm
			money
                       }
                  }
}

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

Для для создания новой рекламной кампании используется метод ads.campaigns.put
Допустимое количество кампаний, создаваемых с помощью одного запроса — 50.

Параметры Значение Дополнительные атрибуты
data сериализованный JSON-массив объектов, описывающих создаваемые кампании. Описание объектов client_specification см. ниже. обязательный параметр, строка
client_specification
app_id id пользователя обязательный параметр, int (числовое значение)
client_id id клиента, в рекламном кабинете которого будет создаваться кампания. Так же может принимать значение app_id (самого себя) обязательный параметр, int (числовое значение)
ad_format Формат объявления:

10 - Тизерная;

20 - Баннерная;

30 - Push-уведомления;

40 - Clickunder;

60 - Контекстная

обязательный параметр, int (числовое значение)
cost_type Способ оплаты:

0 - СРС;

1 - СРА;

2 - СРМ

обязательный параметр, int (числовое значение)
name название кампании обязательный параметр, строка
Link_url ссылка на рекламируемый объект в формате: http://yoursite.cоm обязательный параметр, строка
real_url ссылка на реальный домен рекламируемого объекта в формате: http://yoursite.cоm обязательный параметр, строка
sex Пол:

3 - любой;

2 - мужской;

1 - женский

обязательный параметр, int (числовое значение)
age Возраст целевой аудитории. Номер возрастной категории от 1 до 6 (до 17, 18-25, 26-34, 35-49, 50-60, старше 61) обязательный параметр, последовательность чисел, разделенных запятой
regions Регионы, от 1 до 10 (1 - Россия, 2 - Украина и т.д.) обязательный параметр, последовательность чисел, разделенных запятой
cpa_mode Тип уведомлений о конверсий для CPA: /ads.targeting.modes.get int (числовое значение), обязательное для CPA кампании
categories

идентификаторы категорий:

/data.categories.get?ad_format=%

масив [category_id => cost]

tags таргетинг по ключевым словам

обязательный параметр, последовательность ключевых слов, разделенных запятой: [“key1”, “key2”, .., “keyN”]

Ключевые слова с ценой. Только для оплаты - за клики или за показы: {“key1”: “cost”, “key2”: “cost”, .., “keyN”: “cost”}

cost - float

пример: "data[tags][qwerty]: 1" - ключевое слово qwerty со ставкой 1руб.

day_limit Дневной лимит в рублях. Для всех типов кроме clickunder положительное число
all_limit Общий лимит в рублях. Для всех типов кроме clickunder положительное число
click_limit Максимальное кол. переходов в день. Для всех типов кроме clickunder. За показы и за клики. положительное число
conversion_limit Максимальное кол. конверсий в день. Для всех типов кроме clickunder. Только для CPA положительное число
adult_content присутсвие контента для взрослых в рекламной кампании:

0 - Нет;

1 - Да

необязательный параметр, int (числовое значение), по умолчанию 0
adult_site Отображать объявления кампании на сайтах с контентом для взрослых:

0 - Нет;

1 - Да

необязательный параметр, int (числовое значение), по умолчанию 0
time_show Временной таргетинг:

   * - отображение в любые часы и дни недели

   {} - массив, где ключ имя дня недели ["Sn","Mn","Tu","Wd","Th","Fr","Sa"]:

             {} - ‘mn’: ‘*’ - все часы понендельника

             {} - ‘mn’: [0, .., 23] - часы через запятую

необязательный параметр, * по умолчанию
platforms таргетинг по платформам: /data.platforms последовательность чисел, разделенных запятой
browsers таргетинг по браузерам: /data.browsers последовательность чисел, разделенных запятой
black_list черный список площадок на которых не будет показана реклама последовательность чисел ID площадок, разделенных запятой
white_list белый список площадок на которых не будет показана реклама последовательность чисел ID площадок, разделенных запятой
black_list_ip блокировка по ip последовательность ip адресов, разделенных запятой или массивом
unique_day_count частота показов материала одному пользователю (разы) положительное число
unique_days частота показов рекламного материала одному пользователю (дни) положительное число

Результат:
Возвращает массив ответов на запросы в массиве data. Соответствующий объект в выходном массиве содержит id созданной кампании, и поля error_code и error_desc в случае возникновения ошибки.

Errors:

   102 - unknown client
   103 - overlimit campaigns

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

Для редактирования рекламных кампаний используется метод ads.campaigns.update
Максимальное допустимое количество кампаний, редактируемых с помощью одного запроса — 50.
Version log: 1.0.1 - добавлен параметр status

Параметры Значение Дополнительные атрибуты
data сериализованный JSON-массив объектов, описывающих изменения в кампаниях. Описание объектов client_mod_specification см. ниже. обязательный параметр, строка
client_specification
campaign_id id редактируемой кампании обязательный параметр, положительное число
name название кампании необязательный параметр, строка длиной от 3 до 60 символов
link_url ссылка на рекламируемый объект в формате http://yoursite.cоm необязательный параметр, строка
real_url ссылка на реальный домен рекламируемого объекта в формате: http://yoursite.cоm необязательный параметр, строка
sex Пол:

3 - любой;

2 - мужской;

1 - женский

необязательный параметр, int (числовое значение)
age возраст: /data.ages необязательный параметр, int (числовое значение)
categories идентификаторы категорий:

/data.categories.get?ad_format=%

category_id: {region_id: cost}

необязательный параметр
tags таргетинг по ключевым словам необязательный параметр, последовательность ключевых слов, разделенных запятой
day_limit дневной лимит в рублях. для всех типов кроме clickunder необязательный параметр, положительное число
adult_content присутсвие контента для взрослых в рекламной кампании:

0 - Нет;

1 - Да

необязательный параметр, int (числовое значение), по умолчанию 0
adult_site отображать объявления кампании на сайтах с контентом для взрослых:

0 - Нет;

1 - Да

необязательный параметр, int (числовое значение), по умолчанию 0
time_show Временной таргетинг:

   * - отображение в любые часы и дни недели

   {} - массив, где ключ имя дня недели ["Sn","Mn","Tu","Wd","Th","Fr","Sa"]:

           {} - ‘mn’: ‘*’ - все часы понендельника

           {} - ‘mn’: [0, .., 23] - часы через запятую

необязательный параметр, * по умолчанию
platforms таргетинг по платформам: /data.platforms последовательность чисел, разделенных запятой
browsers таргетинг по браузерам: /data.browsers последовательность чисел, разделенных запятой
black_list черный список площадок на которых не будет показана реклама последовательность чисел ID площадок, разделенных запятой
white_list белый список площадок на которых не будет показана реклама последовательность чисел ID площадок, разделенных запятой
black_list_ip блокировка по ip последовательность ip адресов, разделенных запятой или массивом
status запуск/приостановка кампании:

0 - приостановлена;

1 - запущена

необязательный параметр, int (числовое значение), по умолчанию 1

Результат:
Возвращает массив ответов на каждый запрос в массиве data. Соответствующий объект в выходном массиве содержит id изменяемого клиента и, в случае возникновения ошибки, поля error_code и error_desc.

Errors:

   100 - unknown campaign
   102 - unknown client

Список кампаний рекламного кабинета

Для получения списка кампаний рекламного кабинета используется метод ads.campaigns.get

Параметры Значение Дополнительные атрибуты
client_id Идентификатор клиента, у которого запрашиваются рекламные кампании int (числовое значение)
include_archive Флаг, задающий необходимость вывода архивных объявлений:

0 - выводить только активные кампании;

1 - выводить все кампании

Флаг, может принимать значения 1 или 0
campaign_ids Фильтр выводимых рекламных кампаний.

Сериализованный JSON-массив, содержащий id кампаний. Выводиться будут только кампании, присутствующие в campaign_ids и являющиеся кампаниями указанного рекламного кабинета. Если параметр равен null, то выводиться будут все кампании.

Строка
with_bwlist Флаг передачи блек- и вайт-листов любое значение (например 1)
with_tags Флаг передачи ключевых слов любое значение (например 1)
limit ограничение на количество возвращаемых кампаний. Используется, только если параметр campaign_ids равен null int (числовое значение)
offset смещение. Используется в тех же случаях, что и параметр limit int (числовое значение)

Результат:
Возвращает массив объектов campaign, каждый из которых содержит следующие поля:

response: {
       count: %total%,
       items: [{
	   id — идентификатор кампании
	   name — название кампании
	   status — статус кампании (0 — кампания остановлена, 1 — кампания запущена, 2 — кампания удалена)
	   day_limit — дневной лимит кампании в рублях (0 — лимит не задан)
	   all_limit — общий лимит кампании в рублях (0 — лимит не задан)
	   ad_format — формат объявления
	   cost_type — тип оплаты
	   link_url - ссылка на рекламируемый объект
	   sex - пол
	   age - возраст
	   regions - идентификаторы регионов
	   categories - идентификаторы категорий.
	   adult_content - присутсвие контент для взрослых
	   adult_site - отображение объявлений кампании на сайтах с контентом для взрослых
           tags - ключевые слова
           bw_list - блек- и вайт-лист 
      },..]
}

Errors:

   102 - unknown client

Архивирование рекламной кампании

Для архивирования рекламной кампании используется метод ads.campaigns.delete
Максимальное допустимое количество клиентов, редактируемых с помощью одного запроса — 10.

Параметры Значение Дополнительные атрибуты
ids Список id кампаний через запятую или массив с id кампаниями.

Например:

“id1, id2, …, idn“ или [id1, id2, …, idn]

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

Результат:
Возвращает массив ответов на каждый запрос. Каждый ответ является либо 0, что означает успешное удаление, либо массив error.

Errors:

   100 - unknown campaign
   101 - campaign already archive
   102 - unknown client

Получение кодов для СРА кампаний

Для получения кодов по СРА кампаниям используется метод ads.campaigns.cpa.mode.get

Параметры Значение Дополнительные атрибуты
campaign_id id кампании int (числовое значение), обязательный параметр

Результат:
Возвращает объект с данными.

{
	response: {
		url: %url%
                  }
}

Получение списка категорий по заданому фильтру

Для возврата списка категорий по заданому фильтру используется метод ads.campaigns.categories.get

Параметры Значение Дополнительные атрибуты
ad_format формат объявления:

ads.campaigns.foarmats.get

обязательный параметр, int (числовое значение)
category_id id категории. ограничивает отображение только по id категории необязательный параметр, int (числовое значение)

Результат:
Возвращает массив ответов на запросы в массиве response.

response: {
            count: %total%,
            items: [{
                       %category_id%: {
                            %region_id%: {
	                         min: %min_cost%,
	                         max: %max_cost%
                             }
                       }
                  },..]
}

Получение списка форматов объявлений

Для получения списка форматов объявлений используется метод ads.campaigns.formats.get

Результат:
Возвращает массив ответов на запросы в массиве response.

response: {
       count: %total%,
       items: [{
             id: %format_id%,
             title: ‘%format title%’
       },..]
}

Получение списка платформ

Для получения списка платформ используется метод ads.targeting.platforms.get

Результат:
Возвращает массив ответов на запросы в массиве response.

response: {
       count: %,
       items: [{
           id: %platform_id%,
           title: %platform_name%,
           mobile: %is mobile%
       },..]
}

Получение списка браузеров

Для получения списка браузеров используется метод ads.targeting.browsers.get

Результат:
Возвращает массив ответов на запросы в массиве response.

response: {
       count: %,
       items: [{
           id: %browser_id%,
           title: %browser_name%,
       },..]
}

Получение списка уведомлений о конверсиях для СРА

Для получения списка уведомлений о конверсиях для СРА используется метод ads.targeting.cpa.modes.get

Результат:
Возвращает массив ответов на запросы в массиве response.

response: {
       count: %total%,
       items: [{
           id: %mode_id%,
           title: ‘%mode title%’
       },..]
}

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

Для получения списка возврастов используется метод ads.targeting.ages.get

Результат:
Возвращает массив ответов на запросы в массиве response.

response: {
       count: %,
       items: [{
           id: %age_id%,
           title: %age_name%
       },..]
}

Создание клиентов рекламного агенства

Для создания клиентов рекламного агенства используется метод ads.clients.put
Допустимое количество создаваемых клиентов с помощью одного запроса — 50.

Параметры Значение Дополнительные атрибуты
data сериализованный JSON-массив объектов, описывающих создаваемые кампании. Описание объектов client_specification см. ниже. обязательный параметр, строка
client_specification
name название клиента строка от 3 до 60 символов, обязательный параметр
day_limit дневной лимит в рублях int (числовое значение)

Результат:
Возвращает массив ответов на запросы в массиве data. Соответствующий объект в выходном массиве содержит информацию клиента или массив error в случае возникновения ошибки (для каждого клиента отдельно).

{
    client_id — идентификатор клиента;
    name — название клиента;
    day_limit — дневной лимит клиента в рублях;
}

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

Для редактирования клиентов рекламного агенства используется метод ads.clients.update
Максимальное допустимое количество клиентов, редактируемых с помощью одного запроса — 50.

Параметры Значение Дополнительные атрибуты
data сериализованный JSON-массив объектов, описывающих изменения в клиентах. Описание объектов client_mod_specification см. ниже. обязательный параметр, строка
client_mod_specification
client_id идентификатор редактируемого клиента обязательный параметр, положительное число
name название клиента строка длиной от 3 до 60 символов
day_limit дневной лимит в рублях положительное число

Результат:
Возвращает массив ответов на каждый запрос в массиве data. Соответствующий объект в выходном массиве содержит id изменяемого клиента и, в случае возникновения ошибки, поля error_code иerror_desc.

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

Для возврата списка клиентов рекламного агенства используется метод ads.clients.get

Параметры Значение Дополнительные атрибуты
client_ids Список id клиентов через запятую. Например: “id1, id2, …, idn“ необязательный параметр, строка

Результат:
Возвращает массив объектов client — клиентов агентства, каждый из которых содержит следующие поля:

response: {
      count: %total%,
      items: [{
           client_id — идентификатор клиента;
           name — название клиента;
           day_limit — дневной лимит клиента в рублях;
           balance - баланс клиента
      },..]
}

Архивирование клиентов рекламного агенства

Для архивирования клиентов рекламного агенства используется метод ads.clients.delete

Параметры Значение Дополнительные атрибуты
ids Список id клиентов через запятую или массив с id клиентами.

Например: “id1, id2, …, idn“ или [id1, id2, …, idn]

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

Результат:
Возвращает массив ответов на каждый запрос. Каждый ответ является либо 0, что означает успешное удаление, либо массив error.

Подвязывание клиента к рекламному агенству

Для подвязывания клиента к рекламному агенству используется метод ads.clients.bind.put

Параметры Значение Дополнительные атрибуты
email email адрес клиента строка от 3 до 60 символов, обязательный параметр
password пароль клиента (от кабинета) строка от 3 до 60 символов, обязательный параметр

Результат:
Возвращает:

{
	“bind”: true
}

в случае успеха. Или error в случае возникновения ошибки.

Открепление клиента от рекламного агенства

Для открепления клиента от рекламного агенства используется метод ads.clients.unbind.put

Параметры Значение Дополнительные атрибуты
client_id id клиента int (числовое значение)

Результат:
Возвращает:

{
	“unbind”: true
}

в случае успеха. Или error в случае возникновения ошибки.

Пополнение счета клиента

Для пополнения счета клиента используется метод ads.clients.balance.put

Параметры Значение Дополнительные атрибуты
client_id id клиента для пополнения int (числовое значение), обязательный параметр
sum сума в рублях int (числовое значение)
back_url url куда переадресует клиента система пополнения string (строка)
system_id id системы пополнения:

data.balance.systems.get

int (числовое значение), обязательный параметр

Результат:
Возвращает url для оплаты:

{
	response: {
		url: %url%
                  }
}

Создание рекламных объявлений

Для создания рекламных объявлений используется метод ads.materials.put
Максимальное допустимое количество объявлений, создаваемых с помощью одного запроса — 20.

Параметры Значение Дополнительные атрибуты
data сериализованный JSON-массив объектов, описывающих создаваемые объявления. Описание объектов ad_specification см. ниже. обязательный параметр, строка
ad_specification
campaign_id id кампании, в которой будет создаваться объявление обязательный параметр, int (числовое значение)
title заголовок объявления обязательный параметр
text описание объявления обязательно
link_url ссылка рекламируемого объекта в формате: http://yoursite.cоm
link_media загруженный ранее медиа объект (jpg, gif):

data.upload.media

pause_after_moderate установка объявления на паузу после модерации
size только для банеров:

ads.materials.banner.sizes

categories Стаки по категориям, аналогично как и для кампаний:

массив [category_id => cost]

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

Обновление данных рекламных объявлений

Для обновления данных рекламных объявлений используется метод ads.materials.update
Максимальное допустимое количество объявлений, создаваемых с помощью одного запроса — 20.

Параметры Значение Дополнительные атрибуты
data сериализованный JSON-массив объектов, описывающих создаваемые объявления. Описание объектов ad_specification см. ниже обязательный параметр, строка
ad_specification
material_id id объявления обязательный параметр, int (числовое значение)
status запуск/приостановка материала:

0 - приостановлена;

1 - запущена

необязательный параметр, int (числовое значение), по умолчанию 1

Архивирование рекламных объявлений

Для архивирования рекламных объявлений используется метод ads.materials.delete
Максимальное допустимое количество клиентов, редактируемых с помощью одного запроса — 50.

Параметры Значение Дополнительные атрибуты
account_id идентификатор рекламного кабинета обязательный параметр, int (числовое значение)
ids сериализованный JSON-массив, содержащий идентификаторы объявлений обязательный параметр, строка

Результат:
Возвращает массив ответов на каждый запрос. Каждый ответ является либо 0, что означает успешное удаление, либо массив error.

Получение списка рекламных объявлений

Для получения списка рекламных объявлений используется метод ads.materials.get

Параметры Значение Дополнительные атрибуты
account_id идентификатор рекламного кабинета обязательный параметр, int (числовое значение)
client_id Для рекламных агентств. Идентификатор клиента, у которого запрашиваются рекламные объявления. int (числовое значение)
archive Флаг, задающий необходимость вывода архивных объявлений:

0 - выводить только активные объявления;

1 - выводить все объявления

Флаг, может принимать значения 1 или 0
campaign_ids фильтр по рекламным кампаниям.

Сериализованный JSON-массив, содержащий id кампаний. Если параметр равен null, то будут выводиться рекламные объявления всех кампаний.

строка
material_ids фильтр по рекламным кампаниям.

Сериализованный JSON-массив, содержащий id объявлений. Если параметр равен null, то будут выводиться все рекламные объявления.

строка
limit ограничение на количество возвращаемых объявлений. Используется, только если параметр ad_ids равен null, а параметр campaign_ids содержит id только одной кампании. int (числовое значение)
offset смещение. Используется в тех же случаях, что и параметр limit int (числовое значение)
ad_format формат объявления: ads.campaigns.formats.get обязательный параметр, int (числовое значение)

Результат:
Возвращает массив объектов ad, каждый из которых содержит следующие поля:

  • id — идентификатор объявления
  • name — название объявления
  • campaign_id — идентификатор кампании
  • link_url
  • arhive
  • ad_format — формат объявления
  • cost_type — тип оплаты
  • all_limit — общий лимит объявления в рублях
    • 0 — лимит не задан
  • status — статус объявления:
    • 0 — объявление остановлено;
    • 1 — объявление запущено;
    • 2 — объявление удалено
  • approved — статус модерации объявления:
    • 0 — объявление ожидает модерации;
    • 10 — объявление одобрено;
    • 20 — объявление отклонено

Получение списка размеров баннеров

Для получение списка размеров баннеров используется метод ads.materials.banner.sizes.get

Результат:
Возвращает массив ответов на запросы в массиве response:

response: {
       count: %total%,
       items: [{
            id: %banner_id%,
            title: ‘%banner title%’
       },..]
}

Получение списка стран

Для получение списка стран используется метод data.geo.countries.get

Результат:
Возвращает массив ответов на запросы в массиве response:

response: {
   count: %,
   items: [{
       id: %country_id%,
       title: %country_name%
   },..]
}

Получение списка регионов по заданому фильтру

Для получения списка регионов по заданому фильтру используется метод data.geo.regions.get

Параметры Значение Дополнительные атрибуты
country_id идентификатор страны, полученный в методе ads.geo.countries положительное число, обязательный параметр

Результат:
Возвращает массив ответов на запросы в массиве response:

response: {
        count: %,
        items: [{
               id: %region_id%,
               title: %region_name%
        },..]
}

Получение списка доступных платежных систем

Для получения списка доступных платежных систем используется метод data.balance.systems.get

Результат:
Возвращает массив ответов на запросы в массиве response:

response: {
        count: %total%,
        items: [{
               id: %pay_system_id%,
               title: ‘%pay system title%’
        },..]
}

Загрузка медиа файлов

Для загрузки медиа файлов (jpg, png, gif) используется метод data.upload.media.update

Параметры Значение Дополнительные атрибуты
ad_format формат объявления: /ads.formats.get int (числовое значение)
file CURLFile object

Результат:
Возвращает массив с ссылкой на конечный объект или error в случае ошибки

response: {
        image: “%link%”
}

Пример отправки файла с использование curl в php:

       $token = ‘полученный токен’;
       $ad_format = ‘формат объявления’;
       $app_id = ‘ваш app id’;
       $file = '@/полный путь к файлу';
       $finfo = finfo_open(FILEINFO_MIME_TYPE);
       $finfo = finfo_file($finfo, $link);
       $cFile = new \CURLFile($link, $finfo, basename($link));
       $post = array('file'=>$cFile, 'ad_format' => $ad_format, 'app_id' => $app_id);
       $ignoreParams = array('file'); //поле file не участвует в построении подписи
       ksort( $post );
       $result = array ();
       foreach( $post as $key => $value ) {
         	if(false == in_array($key, $ignoreParams)) {
		      $result[] = $key . '=' . urlencode( $value );
	        }
       }
       $result = implode( '&', $result );
       $signature = md5( $result . $token );
       $target_url = 'http://api.kadam.net/data.upload.media?signature=' . $signature;
       $ch = curl_init();
       curl_setopt($ch, CURLOPT_URL,$target_url);
       curl_setopt($ch, CURLOPT_POST, true);
       curl_setopt($ch, CURLOPT_POSTFIELDS, $post);
       curl_setopt($ch, CURLOPT_RETURNTRANSFER,1);
       $result = curl_exec ($ch); //ответ сервера

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

Для получения текущего времени сервера в формате ISO 8601 используется метод server.time.get

Результат:
Возвращает массив ответов на запросы в массиве response:

       {
           iso8601: %time%
       }

Статистика для Вебмастера

Для получения статистики по вебмастерам используется метод webmaster.reports.report.get

Параметры Значение Дополнительные атрибуты
secret Ключ доступа для вебмастера(обязательный) Можно получить по требованию
date_from Начало периода строка вида "YYYY-MM-DD", не обязательный параметр, в случае отсутствия будет взята текущая дата
date_to Окончание периода строка вида "YYYY-MM-DD", не обязательный параметр, в случае отсутствия будет взята текущая дата

Максимальный период выгрузки 1 месяц
Результат:

  • blockviews — К-во просмотров блоков
  • moneyin — Заработано денег

Возвращает данные в виде

Array
(
    [responce] => Array
        (
            [2017-11-10] => Array
                (
                    [blockviews] => 300
                    [moneyin] => 100.00
                )

        )

)

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

Для перевода денег используется метод ads.clients.balance.update

Параметры Значение Дополнительные атрибуты
client_id Идентификатор клиента, ему будут перечислены деньги. Обязательное
sum сумма перевода Обязательное
type Тип операции Обязательное - всегда type = "transfer"
comment Комментарий Обязательное - допускается пустое значение

Операцию можно совершать только при наличии достаточного кол-ва средств на аккаунте
Деньни будут сняты у поьзователя указанного в app_id
Результат:
Результатом операции будет списание средств с основного пользователя - транзакция вывода. И перевод денег на аккаунт агенства - транзакция ввода.

Возвращает данные в виде

Array
(
    [status] => "success"

)

В случае ошибки - код ошибки