Skip to content

README.md

Latest commit

 

History

History
154 lines (101 loc) · 7.76 KB

README.md

File metadata and controls

154 lines (101 loc) · 7.76 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__');
$path = getenv('__PARTNER_PATH__');

$data = (new Crypt)->encrypt($dataJson, $cryptKey);
$data = unrencode($data);

$url = "https://sandbox.promopult.org/{$path}/hello?k=zaa{$hash}{$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!" 
}
*/

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

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

interface CryptInterface {
   public function encrypt(string $string, string $key): string;
   public 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> — строка, идентифицирующая алгоритм шифрования (всегда zaa)
<HASH> — уникальная 32-х символьная строка, идентифицирующий пользователя
<DATA> — дополнительные параметры в зашифрованом виде

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