API биллинга

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

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

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

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

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

/components/jobs/install.php:
	// ...

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