Skip to content
Permalink
master
Go to file
 
 
Cannot retrieve contributors at this time
161 lines (108 sloc) 8.01 KB

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

Информация, представленная в документе, актуальна для API версии 1 сервиса SP Integra 3.x.

Содержание

Формат взаимодействия

Запросы к API выполняются по протоколу HTTPS методами GET или POST. Все данные, необходимые для вызова метода API, находятся в PATH-части URL запроса.

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

GET https://<HOST>/<PARTNER_PATH>/<METHOD>?k=<PREFIX><IDENTITY_HASH><DATA>

где

<HOST> — адрес сервера API
<PARTNER_PATH> — уникальный путь Партнера
<METHOD> — название вызываемого метода
<PREFIX> — строка, идентифицирующая алгоритм шифрования (всегда zaa)
<IDENTITY_HASH> — уникальный 32-х символьный hash, идентифицирующий пользователя или партнера
<DATA> — аргументы вызываемого метода в виде строки JSON зашифрованной алгоритмом симметритчного шифрования (см. раздел Шифрование данных)

Использование API предполагает два контекста вызываемых методов:

  • контекст общего действия (сразу над несколькими пользователями или вообще никак не связанного с пользователями)
  • контекст действия пользователя

Например, получение списка пользователей это общее действие, а пополнение счета — пользовательское.

В зависмости от контекста вызываемого метода для подготовки запроса требуются разные пары hash и cryptKey. Для вызовов методов общих действий используются hash и cryptKey Партнера, а для операций с пользователем — hash и cryptKey, полученные при регистрации пользователя.

Пример вызова API на PHP (см. файл examples/example-hello.php):

/* Подготавливаем URL */

$dataJson = json_encode([
  'name' => 'Dmitry'
]);

// Для вызова данного метода используем hash и cryptKey Партнера
$hash = getenv('__PARTNER_HASH__');
$cryptKey = getenv('__PARTNER_KEY__');

$data = Crypt::encrypt($dataJson, $cryptKey);

$url = 'https://sandbox.promopult.org/iframe/hello?k=zaa' . $hash . urlencode($data);


/* Вызываем API */

$streamContext = stream_context_create([
  'http' => [
    'method' => 'GET',
    'header' => "Content-type: application/json\r\n"
  ]
]);

$response = file_get_contents($url, false, $streamContext);

var_dump($response);

/*
{ 
  status: {
    code: 0, 
    message: "ok" 
  }, 
  error: false, 
  data: "Hello, Dmitry!" 
}
*/

Шифрование данных

Для безопасной работы по протоколу HTTP используется смметричное шифрование данных.

При интеграции мы предоставим исходный код класса, реализующий следующий интерфейс шифрования (см. файл examples/crypt.php):

interface CryptInterface {
   public static function encrypt(string $string, string $key): string;
   public static function decrypt(string $string, string $key): string;
}

Регистрация пользователя и получени доступа

Для того чтобы получить доступ к веб-интерфейсу сначала необходимо зарегистрировать пользователя в Integra.

Регистрация осуществляется путем вызова API-метода createUser, который принимает на вход два обязательных параметра: hash и username. В случае успешной регистрации createUser в ответе вернет cryptKey, который следует сохранить на стороне Партнера, т.к. в дальнейшем этот ключ будет использоваться сервером для расшифровки параметров вызова API в контексте пользователя.

Диаграмма последовательности регистрации пользователя:

Регистрация пользователя и получение доступа к UI

IFrame

Веб-интерфейс модуля продвижения встраивается в веб-страницу Партнера используя HTML-элемент <iframe>.

HTML-код <iframe> генерируется динамически на стороне Партнера, атрибут src содержит уникальный для каждого пользователя URL. Атрибут seamless обеспечивает корректную работу в некоторых браузерах.

Также, в случае несколькольких iframe-ов на странице, следует указать атрибут name, содержащий любое уникальное значение, например префиксированный внунтренний идентификатор проекта <iframe name="int-123456"....

<html>
    <!-- ... -->
    <iframe name="{уникальное-имя-айфрейма}" src="{уникальный-url-пользователя}" seamless="seamless"></iframe>
    <!-- ... -->
</html>

Для формирования URL используется следующий синтаксис:

https://<HOST>/<PARTNER_PATH>/iframe?k=<PREFIX><HASH><DATA>

где

<HOST> — адрес сервера API
<PARTNER_PATH> — уникальный путь, индивидуальный для каждого партнера
<PREFIX> — строка, идентифицирующая алгоритм шифрования (всегда kaa)
<HASH> — уникальная 32-х символьная строка, идентифицирующий пользователя
<DATA> — дополнительные параметры в зашифрованом виде

Дополнительные материалы

You can’t perform that action at this time.