API биллинга

Это описание для Биллинга первой ветки InstantCMS. Для InstantCMS2 документация по Биллингу находится на этой странице.

1. Регистрация действий

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

Предположим, Вы написали компонент jobs (биржа труда) и в нем есть действие add_vacancy (добавление вакансии). Действие состоит из двух этапов: 1. показать пользователю форму, 2. сохранить введенные в форме данные. На первом этапе мы будем просить биллинг проверить баланс, а на втором — списать средства. Таким образом, дейтсвие add_vacancy у нас будет платным.

Цены на платные действия, в общем случае, настраиваются в админке самого биллинга. Для этого биллинг должен знать о каждом действии, за которое может быть установлена плата. Чтобы сообщить биллингу о платных действиях в Вашем компоненте, каждое из них нужно зарегистрировать. Лучше всего делать это в инсталляторе компонента.

Рассмотрим на примере компонента jobs и действия add_vacancy:

 
function install_component_jobs{
 
    // создаем таблицы в БД //
    // делаем все что нужно при установке нашего компонента
 
    // подключаем биллинг, если он установлен
    if ($inCore->isComponentInstalled('billing')){
 
        $inCore->loadClass('billing');
 
        // регистрируем платное действие
        cmsBilling::registerAction('jobs', array(
            'name' => 'add_vacancy',
            'title' => 'Добавление вакансии'
        ));
 
        // регистрируем другие платные действия, если есть
 
    }
 
}
 

Все! Теперь после установки нашего компонента, в админке биллинга в разделе «Цены» появится новое действие.

2. Инициализация биллинга

Перед тем как использовать биллинг, необходимо убедиться что он установлен. Если установлен, то нужно загрузить класс биллинга:

define('IS_BILLING', $inCore->isComponentInstalled('billing'));
if (IS_BILLING) { $inCore->loadClass('billing'); }
 

Эти строки нужно добавить в начало своего компонента. После этого в коде компонента можно проверять наличие биллинга через константу IS_BILLING:

if (IS_BILLING) { ... }
 

3. Проверка баланса

Перед совершением действия, цена на которое может быть указана в настройках биллинга, необходимо проверить что на балансе пользователя достаточно средств. Например, если речь идет о платном добавлении контента, то баланс нужно проверить непосредственно перед выводом формы.

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

if ($do == 'add_vacancy'){
 
    // проверяем баланс
    if (IS_BILLING) {
        cmsBilling::checkBalance('jobs', 'add_vacancy');
    }
 
    //
    // выводим форму добавления
    //
 
}
 

где jobs — название текущего компонента, add_vacancy — название действия.

Действие должно быть зарегистрировано в биллинге, как описано в п.1.

4. Списание средств

После совершения платного действия, в том месте кода где уже точно известно что действие совершено успешно, нужно добавить операцию списания:

// добавляем вакансию в базу данных
 
if ($success){
 
    // если запись добавлена успешно, проводим списание
    if (IS_BILLING) {
        cmsBilling::process('jobs', 'add_vacancy');
    }
 
}
 

где jobs — название текущего компонента, add_vacancy — название действия.

Если цена за действие не была установлена в настройках биллинга, либо равна нулю, то списание не произойдет и метод cmsBilling::process просто вернет false;

5. Вопросы

Данная страница будет дополняться и развиваться.

Любые вопросы по интеграции биллинга можно направлять на support@instantsoft.ru