Техническая документация

Описание API

API позволяет более гибко управлять процессом оформления подписки

Javascript SDK API

Javascript SDK подключается автоматически при размещении кода на сайте.
Никаких дополнительный действий не требуется.

Доступные обработчики событий:

```
window.linber.events.onReady = function(){}
```
Вызывается после того, как загружены все необходимые ресурсы, и можно работать с Javascript SDK API.
```
window.linber.events.onOpenWindow = function(){}
```
Вызывается во время открытия виджета оформления/просмотра подписки
```
window.linber.events.onCloseWindow = function(){}
```
Вызывается во время закрытия виджета оформления/просмотра подписки
```
window.linber.events.onPaymentSuccess = function(){}
```
Вызывается, если пользователь успешно оформил подписку
```
window.linber.events.onPaymentCancel = function(){}
```
Вызывается, если пользователь отказался от оформления подписки

window.linber.events.onGetSubscription = function(subscription){}

Вызывается каждый раз после получения/обновления информации о текущей подписке. Может быть вызван несколько раз подряд.
Если подписка есть, то объект subscription содержит:

{
    IdSubscription: "9d42d627-5630-4bee-a447-a8579b9189f8"   // ID подписки
    IdTariff: "9d42d627-5630-4bee-a447-a8579b9189f8"         // ID тарифа
    AllowExtendedOn: "2020-08-05T10:32:32.465Z"              // Дата, после которой можно продлить подписку (UTC) 
    ExpiredOn: "2020-08-08T10:32:32.465Z"                    // Дата окончания действия подписки (UTC) 
    UserKey: "MjcwOTk5NjgyOTkxOTYzNKG6h3c3Kv+BFaERFDgx..."   // Пользовательский ключ
}

Если подписки нет - subscription = null

Доступные методы:
Любой из нижеследующих методов можно вызывать только после наступления события linber.events.onReady.

```
window.linber.methods.openWindow()
```
Отображает виджет оформления/просмотра подписки
```
window.linber.methods.closeWindow()
```
Закрывает виджет оформления/просмотра подписки
```
window.linber.methods.hasActiveSubscription(idTariff = undefined)
```
Возвращает признак наличия активной подписки у текущего пользователя (с неистекшим сроком действия).
Если передан параметр idTariff, то проверяется не только наличие подписки, но и наличие у подписки указанного тарифа.
Входные параметры:
idTariff (string | undefined) ID тарифа
Возвращает:
true - подписка существует и активна, false - подписка не существует или не активна
```
window.linber.methods.hasExpiredSubscription(idTariff = undefined)
```
Возвращает признак наличия истекшей подписки у текущего пользователя (с истекшим сроком действия).
Если передан параметр idTariff, то проверяется не только наличие подписки, но и наличие у подписки указанного тарифа.
Входные параметры:
idTariff (string | undefined) ID тарифа
Возвращает:
true - подписка существует и истекла, false - подписка не существует или активна
```
window.linber.methods.hasSubscription(idTariff = undefined, status = undefined)
```
Возвращает признак наличия подписки (в том числе истекшей) у текущего пользователя.
Если передан параметр idTariff, то проверяется не только наличие подписки, но и наличие у подписки указанного тарифа.
Если передан параметр status, то дополнительно проверяется статус подписки.
Входные параметры:
idTariff (string | undefined) ID тарифа
status (boolean | undefined) Фильтр по статусу подписки
   true - проверяет только активную подписку,
   false - проверяет только истекшую подписку,
   undefined - не проверяет статус подписки
Возвращает:
true - подписка существует, false - подписка не существует
```
window.linber.methods.getSubscription()
```
Возвращает информацию о подписке текущего пользователя.
Возвращает:
object - объект подписки, аналогичный параметру в событии window.linber.events.onGetSubscription
null - подписка не существует

Пример вызова окна подписки через API:

// Подписываемся на событие открытия виджета оформления подписки
window.linber.events.onOpenWindow = function() {
   alert("Окно открыто");
};

// Открываем виджет через API
window.linber.events.onReady = function() {
   window.linber.methods.openWindow();
};

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

// Проверяем, что у пользователя есть активная подписка
window.linber.events.onReady = function() {
   var hasSubscription = window.linber.methods.hasActiveSubscription();

   // Если активная подписка есть, то скрываем рекламный блок
   if (hasSubscription) {
      document.querySelector(".banner").style.display = "none";
   } else { // Иначе показываем
      document.querySelector(".banner").style.display = "block";
   }

   // Проверяем, что у пользователя есть подписка с указанным тарифом
   var hasTariff = window.linber.methods.hasActiveSubscription("aab8b1b8-c7ce-4691-9fe4-65f0d2f0585d");
   if (hasTariff) {
      document.querySelector(".banner-tariff1").style.display = "block";
   }
};

PHP SDK API

Для подключения PHP SDK необходимо:

Скачать архив библиотеки из раздела настроек проекта в личном кабинете. Архив содержит папку с названием linber_xxxxxxx, в которой 2 файла - sdk.php и sync.php
Распаковать архив в корневой раздел своего сайта/проекта. Полный путь до файлов SDK должен быть таким:
https://<адрес вашего сайта>/linber_xxxxxxx/sdk.php и https://<адрес вашего сайта>/linber_xxxxxxx/sync.php
Убедиться в доступности адреса https://<адрес вашего сайта>/linber_xxxxxxx/sync.php из интернета.
Этот файл отвечает за синхронизацию подписок и периодически опрашивается нашим сервером

Далее нужно подключить файл sdk.php через include_once в местах, где будет использовано API

Пример подключения SDK и проверки наличия любой активной подписки

<?php

// Подключаем библиотеку (указывается путь до файла)
include_once "./linber_xxxxxxxxxxxx/sdk.php";

// Далее в нужном месте проверяем, что у пользователя есть любая активная подписка,
// и показываем ему блок, доступный только подписчикам
if (Linber\LinberSDK::hasActiveSubscription()) {
   echo "<div>Только для подписчиков</div>";
} else {
   echo "<div>Только без подписки</div>";
}

// ...

// Показываем блок только для пользователей без активной подписки
if (!Linber\LinberSDK::hasActiveSubscription()) {
   echo "<div>Только без подписки</div>";
}

// ...

// Показываем блок только для пользователей с активной подпиской определенного тарифа
if (!Linber\LinberSDK::hasActiveSubscription("aab8b1b8-c7ce-4691-9fe4-65f0d2f0585d")) {
   echo "<div>У вас оформлена подписка на отключение рекламы</div>";
} else {
   echo "<div>У вас не оформлена подписка на отключение рекламы</div>";
}

Доступные методы:

```
Linber\LinberSDK::hasActiveSubscription($idTariff = null)
```
Возвращает признак наличия активной подписки у текущего пользователя (с неистекшим сроком действия).
Если передан параметр $idTariff, то проверяется не только наличие подписки, но и наличие у подписки указанного тарифа.
Входные параметры:
$idTariff (string | null) ID тарифа
Возвращает:
true - подписка существует и активна, false - подписка не существует или не активна
```
Linber\LinberSDK::hasExpiredSubscription($idTariff = null)
```
Возвращает признак наличия истекшей подписки у текущего пользователя (с истекшим сроком действия).
Если передан параметр $idTariff, то проверяется не только наличие подписки, но и наличие у подписки указанного тарифа.
Входные параметры:
$idTariff (string | null) ID тарифа
Возвращает:
true - подписка существует и истекла, false - подписка не существует или активна
```
Linber\LinberSDK::hasSubscription($idTariff = null, $status = null)
```
Возвращает признак наличия подписки (в том числе истекшей) у текущего пользователя.
Если передан параметр $idTariff, то проверяется не только наличие подписки, но и наличие у подписки указанного тарифа.
Если передан параметр $status, то дополнительно проверяется статус подписки.
Входные параметры:
$idTariff (string | null) ID тарифа
$status (boolean | null) Фильтр по статусу подписки
   true - проверяет только активную подписку,
   false - проверяет только истекшую подписку,
   null - не проверяет статус подписки
Возвращает:
true - подписка существует, false - подписка не существует

Linber\LinberSDK::getSubscription()

Возвращает информацию о подписке текущего пользователя.

Возвращает:
null - подписки не существует,
array - ассоциативный массив с данными подписки:

Array
(
    [IdSubscription] => cbe23cf1-9a98-42eb-b3cf-040927dbd0f4    // ID подписки
    [IdTariff] => 780485f5-a3bf-481b-848f-a914df377c62          // ID тарифа
    [ExpiredOn] => 2020-09-06T16:46:21.3253495Z                 // Дата окончания действия подписки (UTC) 
    [AllowExtendedOn] => 2020-09-03T16:46:21.3253495Z           // Дата, после которой можно продлить подписку (UTC) 
)

```
Linber\LinberSDK::getAllSubscriptions()
```
Возвращает список всех подписок (всех подписчиков).
Возвращает:
array - двумерный массив с данными подписок, каждая запись которого структурно аналогична Linber\LinberSDK::getSubscription()
```
Linber\LinberSDK::allowSubscriptionExtended()
```
Возвращает признак, что текущую подписку можно продлить прямо сейчас.
Продлить подписку можно только в конце оплаченного периода или после ее истечения.
Возвращает:
true - подписку можно продлить, false - подписку нельзя продлить
```
Linber\LinberSDK::syncSubscriptions($timeoutRequest = 1)
```
Запускает процесс синхронизации подписок из API. Данный метод выгружает список всех подписок из API в локальное хранилище. Синхронизация осуществляется автоматически в заданный промежуток времени, но вы можете вызвать этот метод самостоятельно.
Входные параметры:
$timeoutRequest (float) Таймаут запроса
Возвращает:
true - синхронизация успешно завершена,
false - при синхронизации возникла ошибка. Ошибку можно посмотреть в файле /linber_xxxxxxx/error.txt

REST API

Для авторизации в REST API необходимо использовать приватный ключ проекта. Его необходимо добавлять в заголовок к каждому запросу. Ключ находится в разделе настроек конкретного проекта в личном кабинете.

Этот ключ не должен быть доступен пользователю - используйте его только для взаимодействия сервер-сервер.

x-app-private-key: MOl6LT7o2SQGeLHsj66jovq3...

При возникновении ошибки в ответ будет передан 400 код ответа и json-структура вида:

{ "error": "Application not found"  // Текст ошибки }

Доступные методы:

GET https://linber.me/public/api/external/v1/subscriptions/ 

// Заголовки запроса
x-app-private-key: MOl6LT7o2SQGeLHsj66jovq3...

// Пример ответа (200 OK)
[
 {
   "IdSubscription": "cbe23cf1-9a98-42eb-b3cf-040927dbd0f4", // ID подписки
   "IdTariff": "780485f5-a3bf-481b-848f-a914df377c62",       // ID тарифа
   "ExpiredOn": "2020-09-06T16:46:21.3253495Z",       // Дата окончания действия подписки (UTC) 
   "AllowExtendedOn": "2020-09-03T16:46:21.3253495Z"  // Дата, после которой можно продлить подписку (UTC) 
 }
]

Возвращает список всех подписок (включая истекшие).

Возвращает:
пустой array - подписок нет
array - массив подписок в json

GET https://linber.me/public/api/external/v1/subscriptions/{idSubscription}/ 

// Заголовки запроса
x-app-private-key: MOl6LT7o2SQGeLHsj66jovq3..

// Пример ответа (200 OK)
{
   "IdSubscription": "cbe23cf1-9a98-42eb-b3cf-040927dbd0f4", // ID подписки
   "IdTariff": "780485f5-a3bf-481b-848f-a914df377c62",       // ID тарифа
   "ExpiredOn": "2020-09-06T16:46:21.3253495Z",       // Дата окончания действия подписки (UTC) 
   "AllowExtendedOn": "2020-09-03T16:46:21.3253495Z"  // Дата, после которой можно продлить подписку (UTC) 
}

Возвращает информацию о подписке по ее ID

Возвращает:
404 код ответа - подписка не найдена
object - объект подписки в json. Структура объекта аналогична объекту из списка подписок

```
POST https://linber.me/public/api/external/v1/subscriptions/byUserKey/

// Заголовки запроса
Content-Type: application/json
x-app-private-key: MOl6LT7o2SQGeLHsj66jovq3...

// Тело запроса
{"UserKey": "MzY3MjU3MDIxOTQ2ODg4Nl...."}

// Пример ответа (200 OK)
// Аналогично предыдущему примеру
```
Возвращает информацию о подписке по ключу пользователя. Ключ пользователя можно получить через Javascript SDK API, PHP SDK API или напрямую из cookie.
Возвращает:
404 код ответа - подписка не найдена
object - объект подписки в json. Структура объекта аналогична объекту из списка подписок

POST https://linber.me/public/api/external/v1/subscriptions/byUserKey/status/

// Заголовки запроса
Content-Type: application/json
x-app-private-key: MOl6LT7o2SQGeLHsj66jovq3...

// Тело запроса
{"UserKey": "MzY3MjU3MDIxOTQ2ODg4Nl...."}

// Пример ответа (200 OK)
{
   "ExpiredOn": "2020-09-06T16:46:21.3253495Z", // Дата окончания действия подписки (UTC) 
   "Active": true                               // Если подписка активна, то true. Не активна - false
}

Возвращает информацию о статусе подписки по ключу пользователя. Ключ пользователя можно получить через Javascript SDK API, PHP SDK API или напрямую из cookie.

Возвращает:
404 код ответа - подписка не найдена
object - json-объект

Другие SDK API

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