API — различия между версиями

Версия 11:08, 11 февраля 2019

API авторизация

Для доступа в API понадобятся ID пользователя (app_id) и подпись (signature). Вызов разных методов осуществляется при помощи запросов по данному шаблону:

       api.kadam.net?%action%.%method%?%params%

       %action% - к чему обращаемся
       %method% - тип обращения
	    get - получить 
	    put - записать 
	    post - обновить
	    delete - удалить
       %params% - параметры запроса
       обязательные параметры %params%
       app_id - id пользователя
       signature - подпись

Пример:

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

или

       [GET] http://api.kadam.net/campaigns?app_id=%app_id%&signature=%signature%
       [GET] - метод обращения по http

Подпись (signature) создается с помощью временного токена (access_token), который можно получить используя параметры app_id и secret key.
Параметры app_id (ID пользователя) и ключ "secret key" можно получить по запросу в поддержку.
Получение токена:

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

Формирование signature для метода [GET]:

       md5 ( %sort_params% . %access_token% )
       %sort_params% - все передаваемые параметры (кроме signature) сортируются по имени

Пример:

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

Пример для php. Получение списка кампаний:

       <?
        $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);

Статистика по кампании

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

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

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

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

Под статистикой по площадкам в кабинете рекламодателя подразумевается статистика по показам и кликам на площадке в разрезе каждой кампании.
Для получения статистики по площадкам используется метод ads.campaigns.statblock.get (GET запрос)

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

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

Сортировка Сортировка по возрастанию

sort={параметр}
Пример: api.kadam.net?sort=views

Сортировка по убыванию

sort=-{параметр}
Пример: api.kadam.net?sort=-views

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

sort={параметр1},-{параметр2},{параметр3}
Пример: api.kadam.net?sort=views,-clicks,leads

Фильтрация

{параметр}={значение}
Примеры:
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

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

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

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

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

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

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

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

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

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

Errors:

   102 - unknown client
   103 - overlimit campaigns

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

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

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

Errors:

   100 - unknown campaign
   102 - unknown client

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

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

Результат:
Возвращает массив объектов 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.

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

Errors:

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

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

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

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

{
	response: {
		url: %url%
                  }
}

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

{
	“bind”: true
}

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

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

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

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

{
	“unbind”: true
}

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

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

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

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

{
	response: {
		url: %url%
                  }
}

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

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

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

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

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

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

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

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

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

Результат:
Возвращает массив объектов 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

Результат:
Возвращает массив ответов на запросы в массиве 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

Результат:
Возвращает массив с ссылкой на конечный объект или 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

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

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

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

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

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

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

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

Array
(
    [status] => "success"
)

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