Описание API

Методы

Типы данных

Описание API

Общие сведения

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

Данный функционал регулярно расширяется и улучшается.

В основе API лежит использование протокола SOAP с WSDL поверх HTTP. Данный подход позволяет в автоматическом режиме обнаруживать доступные пользователю методы и параметры их вызова, типизировать передаваемые между сервером и клиентом данные, позволяя на стороне клиента проводить предварительную фильтрацию данных по их типу. На данный момент для большинства языков программирования существуют библиотеки, позволяющие работать с этим протоколом не вникая в технические подробности его работы.

Далее будут рассмотрены основные методы API и примеры его использования на PHP.

Доступ к API

1. Если у Вас еще нет аккаунта в системе, зарегистрируйте его тут.

2. Обратитесь к менеджеру для предоставлени доступа к зоне разработчика.

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

4. После активации вашей партнерской системы, загрузите ключ доступа к API и SSL сертификаты.

Ключ вместе с логином пользователя и паролем в системе (нужно вводить тот пароль, который вы указывали п.3) используется для авторизации доступа к API и управления вашими пользователями (привлеченными вами по партнерской программе).

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

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

Методы API

Список доступных методов API отображается в левой колонке.

Внимание! Набор методов, их названия и параметры вызова могут отличаться от доступных вам (в зависимости от вашего уровня доступа).

Ссылка "WSDL" позволяет получить xml файл wsdl описания.

Обработка ошибок

Любые, предусмотренные авторами API, ошибки возвращаются клиенту как fault - ассоциативный массив, описывающий произошедшую ошибку.



Рис. 6: Простой fault

Простые ошибки в detail получают массив из двух элементов: error - текстовый код ошибки и incoming - пришедшие в метод данные.



Рис. 7: Сложный fault

Сложные ошибки в detail получают массив из трех элементов: error - текстовый код ошибки, errors - массив с ошибками по каждому полю (в основном для методов добавления/редактирования сущностей) и incoming - пришедшие в метод данные.

Примеры кода (php)

Для примера рассмотрим процедуру получения информации о сайте партнера.

Первое, что необходимо - подключить библиотеку работы с SOAP, в данном случае используется nusoap.

Далее в переменные сохраним логин и пароль доступа к API.

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

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

Далее создадим объект nusoap_client, в качестве параметра указываем адрес эндпоинта API.

Добавим к запросу элементы авторизации и, наконец, вызовем сам метод.

Обратите внимание, что параметры оборачиваются в массив, т.е. если необходимо передать число 5, то в call вторым параметром передается array(5),

если массив: array(array('first' => 1, 'second' => 2)), если два параметра: array(1, 'second').

К примеру, для метода: 

StatArray StatApi.siteStat(int siteId, int startDate, int endDate)

параметры будут выглядеть так:

$methodToCall = 'StatApi.siteStat';

$methodParams = array(111, 222222, 333333);

$result = $client->call($methodToCall, $methodParams);

что будет означать получить статистику по сайту 111 с 222222 по 333333.



Далее приведен пример обработки результата ответа сервера, как видно из кода, предусмотрено получение fault (ошибка пришла с сервера), error (ошибка на стороне клиента, например не получилось распарсить ответ сервера) и самого результата, если все прошло хорошо. 



require_once 'nusoap.php';
 
/* Реквизиты доступа к API */

$apiUser = 'ваш_логин';

$apiKey = 'ваш_пароль';
 
/* Метод API для вызова */

$methodToCall = 'PartnerSiteApi.getSite';

$methodParams = array( айди_сайта_партнера );
 
/* Хеш ключа доступа */

$apiKeyHash = md5($methodToCall.md5($apiKey));
 
/* Инстанциализация клиента */

$client = new nusoap_client('https://tlsapi.clickio.com/soapapi/PartnerAPI.php?wsdl');
 
$client->authtype                     = 'certificate';

$client->decode_utf8                  = 0;

$client->soap_defencoding             = 'UTF-8';

$client->certRequest['sslcertfile']   = 'путь_до_crt_файла_сертификата';

$client->certRequest['sslkeyfile']    = 'путь_до_key_файла_сертификата';

$client->certRequest['verifypeer']    = 0;

$client->certRequest['verifyhost']    = 0;
 
$client->setUseCurl(true);

$client->decodeUTF8(false);
 
/* Дополнительные хедеры доступа */

$client->setHeaders('<ApiAuthHeader><login>'.$apiUser.'</login>'
                   .'<hash>'.$apiKeyHash.'</hash></ApiAuthHeader>');
 
$result = $client->call($methodToCall, $methodParams);
 
/* Обработка результатов */

if ($client->fault) {
    echo '<h2>Fault</h2><pre>';
    print_r($result);
    echo '</pre>';

} else {
    $err = $client->getError();
    if ($err) {
        echo '<h2>Error</h2><pre>' . $err . '</pre>';
        echo "<p>".$client->debug_str."</p>";
    } else {
        echo '<h2>Результат</h2><pre>';
        print_r($result);
        echo '</pre>';
    }

}


Для вызова методов можно использовать и объектно-ориентированный подход, для этого можно использовать proxy. вызов метода call заменяется на:



$proxy = $client->getProxy();

$result = $proxy->PartnerSiteApi__getSite($methodParams);


Обратите внимание на то, что точка (которая обозначает вызов метода класса) заменяется в данном случае на два знака подчеркивания (в других библиотеках может быть по-другому), а в сам метод параметры передаются напрямую, как если бы вызывалась локальная функция.

Для удобства работы, можно также создать отдельный класс для работы с нашим API (параметры придется оборачивать в array перед передачей на обработку в класс):



require_once 'nusoap.php';
 
class ApiClient
{
    /**
     * @var nusoap_client
     */
    protected $client = null;
 
    /* Реквизиты доступа к API */
    protected $apiUser = 'логин';
    protected $apiKey = 'пароль';
 
    public function __construct()
    {
        $this->client = new nusoap_client('https://tlsapi.clickio.com/soapapi/PartnerAPI.php?wsdl');
 
        $this->client->authtype= 'certificate';
        $this->client->decode_utf8= 0;
        $this->client->soap_defencoding= 'UTF-8';
        $this->client->certRequest['sslcertfile']= 'путь_до_crt_файла_сертификата';
        $this->client->certRequest['sslkeyfile']= 'путь_до_key_файла_сертификата';
        $this->client->certRequest['verifypeer']= 0;
        $this->client->certRequest['verifyhost']= 0;
 
        $this->client->setUseCurl(true);
        $this->client->decodeUTF8(false);
    }
 
    public function call($methodName, $methodParams = array())
    {
        /* Хеш ключа доступа */
        $apiKeyHash = md5($methodName.md5($this->apiKey));
 
        /* Дополнительные хедеры доступа */
        $this->client->setHeaders('<ApiAuthHeader><login>'.$this->apiUser.'</login>'
                           .'<hash>'.$apiKeyHash.'</hash></ApiAuthHeader>');
 
        /* Отправляем запрос на сервер */
        $result = $this->client->call($methodName, $methodParams);
 
        if ($this->client->fault) {
            /* Обрабатываем fault */
        } else {
            $err = $this->client->getError();
            /* Обрабатываем error */
        }
 
        return $result;
    }

}

© 2008 - 2024 Clickio