Документация BILLmanager

Интеграция с сайтом

BILLmanager имеет открытый API для взаимодействия со сторонними системами. Его можно использовать для интеграции с сайтом провайдера. 

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

Ниже описаны API-запросы, используемые при интеграции сайта с BILLmanager.

Обратите внимание!

Если вы включили reCATPCHA для BILLmanager, который интегрирован с сайтом, то взаимодействие биллинговой системы и сайта будет нарушено. Чтобы интеграция работала корректно, добавьте на сайт reCAPTCHA с теми же ключами, что и в BILLmanager. Подробнее см. в статье Интеграция с сайтом при включённой reCAPTCHA.

Общая информация


Все запросы к API BILLmanager выполняются по стандартному протоколу (HTTP). Ответ можно получить в виде XML или JSON. Для указания необходимого формата, к запросу добавляется '&out=xml', '&out=json' или '&out=sjson'.

В примерах используются следующие обозначения:

  • DOMAIN — доменное имя сервера BILLmanager.
  • PRICELIST_ID — Id тарифного плана.
  • ADDON_ID — Id дополнения к тарифному плану.
  • PERIOD_ID — Id периода оплаты. Триальный: -100, день: -50, вечный: 0. Если значение больше нуля, то длина периода указана в месяцах. 
  • ITEM_id — Id услуги.
  • ACCOUNT_ID — Id клиента.
  • PARTNER_ID — Id реферала.
  • COUNTRY_ID — Id страны в справочнике Страны.
  • PROJECT_ID — Id провайдера. В версии "BILLmanager" = 1.
  • ITEMTYPE_INTNAME — внутреннее (служебное) наименование типа продукта. Значения можно посмотреть в разделе Типы продуктов, поле Внутреннее наименование.

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

Регистрация клиента


Регистрация

Чтобы зарегистрировать клиента в BILLmanager, выполняется перенаправление пользователя с сайта на форму регистрации:

Регистрация в BILLmanager
https://DOMAIN/billmgr?func=register


Для регистрации клиента на сайте, без перехода в BILLmanager, используется функция register, удаленный вызов которой зарегистрирует клиента в биллинговой системе. Функция имеет следующие параметры:

  • sok со значением ok — признак сохранения данных;
  • email — логин и E-mail нового клиента;
  • passwd — пароль нового клиента;
  • realname — ФИО клиента;
  • phone — номер телефона;
  • conditions_agree со значением on, если для регистрации необходимо принятие условий использования;
  • offer_xxx со значение on, если используется принятие договора-оферты при регистрации;
  • country — код страны в соответствии со справочником BILLmanager, необязательный параметр;
  • state — код страны в соответствии со справочником BILLmanager, необязательный параметр;
  • project — код провайдера. В редакции "BILLmanager" имеет значение 1;
  • recovery со значением on, если необходимо в письме о регистрации отправить клиенту ссылку на сброс пароля;
  • _ga — код привязки к Google Analytics, необязательный параметр;
  • partner — при использовании реферальной программы сайт должен запоминать 'PARTNER_ID' (код партнера), если клиент пришел по реферальной ссылке. Обычно этот параметр сохраняют в cookies;
  • sesid — если используется реферальная программа. Идентификатор клика;
  • tzoffset — смещение часового пояса клиента относительно GMT, необязательный параметр, в BILLmanager выставляется через JavaScirpt следующим образом:

Получение смещения часового пояса пользователя
function tzoffset() {
        var january_offset = get_date_offset(new Date(2010, 0, 2)),
            june_offset = get_date_offset(new Date(2010, 5, 2)),
            diff = january_offset — june_offset;
        var result = get_date_offset(new Date());
        if (diff < 0 || diff > 0) {
            result = result + ",1";
        } else {
            result = result + ",0";
        }
        return result;
      }
Регистрация клиента
https://DOMAIN/billmgr?func=register&sok=ok&email=user@example.com&passwd=q1w2e3&realname=Петров Иван Семёнович&phone=71234567788

В ответ BILLmanager вернет значения user.id — код созданного пользователя и account.id — код зарегистрированного клиента.

Авторизация

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

  • username — логин, поле Имя пользователя в разделе Пользователи. Обычно совпадает с email, указанным при регистрации клиента;
  • password — пароль пользователя;
  • lang — язык интерфейса BILLmanager;
  • project — код провайдера. В версии "BILLmanager" = 1.
Авторизация клиента
https://DOMAIN/billmgr?username=user@example.com&password=q1w2e3&lang=ru&project=PROJECT_ID&func=auth

Проверка авторизации

Для того, чтобы определить под каким аккаунтом авторизован клиент используется функция whoami. Функция возвращает код авторизованного клиента и ФИО.

Проверка данных авторизации
https://DOMAIN/billmgr?func=whoami

Информация о тарифах


Функция и параметры

Чтобы загружать информацию о тарифных планах автоматически из BILLmanager на сайт, используется функция pricelist.export, со следующими параметрами: 

  • elid=PROJECT_ID — Id провайдера в BILLmanager;
  • onlyavailable — вывести активные тарифы, которые доступны для заказа текущему пользователю. Может принимать значения "On" и "Off". 

     Пояснения к параметру

    Например, в BILLmanager есть два тарифа: "VDS for all" и "VDS for partner". VDS for all доступен всем клиентам провайдера. VDS for partner доступен клиентам из группы "Partners". API-запрос без авторизации в BILLmanager и с параметром onlyavailable="yes" не выведет тариф "VDS for partner". API-запрос без авторизации и с параметром onlyavailable="off" выведет тариф "VDS for all" и "VDS for Partner". 

  • pricelist — Id тарифов через запятую, указывается только если нужно получить данные не всех тарифов;
  • addonitemtype — Id типов продуктов дополнений к тарифным планам, указывается, если в выводе нужны не все дополнения;
  • itemtype — Id типа продукта тарифов, которые нужно вывести, указывается, когда нужны тарифы только определенного типа;
  • exclude_pricelist — Id тарифов через запятую, которые нужно исключить из вывода функции;
  • othercurrency — ISO код валюты, в которую нужно пересчитать цены тарифов и дополнений, если требуется вывод в валюте отличной от валюты провайдера. Пересчет идет по текущему курсу в BILLmanager;
  • out — формат вывода информации. Может принимать значения "json" и "xml". 

Функция возвращает стоимость тарифов и дополнений в выбранном формате.

Информация о тарифных планах
https://DOMAIN/billmgr?func=pricelist.export

Как получить информацию о всех тарифах

Чтобы получить информацию о всех тарифах, в том числе неактивных, используйте функцию pricelist.export с параметром pricelist. 

Обратите внимание!

 Для получения информации о всех тарифах нужна авторизация в BILLmanager с правами администратора. 


  1. Предварительно получите ID всех тарифов. Например, для этого можно использовать функцию pricelist: 

    https://domain.com?func=pricelist&out=print
  2. Используйте функцию pricelist.export с параметром pricelist:

    https://domain.com?func=pricelist.export&out=print&onlyavailable=off&pricelist=id_list
     Пояснения к запросу

    domain.com — домен или публичный IP-адрес сервера с BILLmanager. 

    id_list — все ID тарифов, созданных в BILLmanager. Указываются через запятую. 

Заказ услуг


Обычно услугу и ее параметры клиент выбирает непосредственно на сайте провайдера. После чего, например, при нажатии кнопки "Заказать" или "Оплатить" на сайте, клиент перенаправляется в биллинговую систему для завершения заказа и оплаты услуги. Если клиент не авторизован в системе, то BILLmanager предложит зарегистрироваться или войти под существующим аккаунтом. После регистрации/авторизации клиент автоматически направляется на страницу заказа услуги в биллиногой системе. 

Перенаправление на страницу заказа

Клиента можно перенаправлять на разные страницы заказа: 

  • страницу выбора тарифных планов. Клиенту остается выбрать тарифный план, период оплаты, параметры тарифа и произвести оплату;
  • страницу заказа конкретного тарифного плана с выбранным периодом оплаты. Клиенту остается выбрать параметры тарифа и произвести оплату;
  • страницу оплаты конкретного тарифа с выбранным периодом оплаты и выбранными параметрами. Клиенту остается произвести оплату.

Ссылка на выбор тарифного плана

Ссылка на выбор тарифного плана по услуге выглядит следующим образом:

Перенаправление на страницу выбора тарифного плана
https://DOMAIN/billmgr?func=register&redirect=startpage%3DITEMTYPE_INTNAME%26startform%3DITEMTYPE_INTNAME%252Eorder%26pricelist%3DPRICELIST_ID%26project%3DPROJECT_ID

Параметры запроса:

  • startpage — страница/список, которая будет открыта после регистрации/авторизации
  • startform — форма заказа услуги, которая будет открыта после регистрации/авторизации
  • pricelist — код тарифного плана
  • project — код провайдера

Стандарт URL накладывает некоторые ограничения на используемые символы. В связи с этим все ссылки лучше кодировать в URL формат, иначе ссылки могут отрабатывать некорректно.

В разделе "Заказ услуг" используются закодированные ссылки, их необходимо использовать именно в таком формате.

Пример ссылки на выбор тарифного плана виртуального хостинга (startform=vhost.order):

Перенаправление на страницу заказа определенного тарифа виртуального хостинга
https://DOMAIN/billmgr?func=register&redirect=startpage%3Dvhost%26startform%3Dvhost%252Eorder%26project%3D1

Ссылка на заказ конкретного тарифа с выбранным периодом оплаты

Ссылки на заказ тарифных планов BILLmanager генерирует автоматически, их можно найти в разделе Тарифные планы → Изменить → вкладка Ссылки

Так же можно передать значение дополнительно заказанных ресурсов в параметрах вида addon_N=xxx — где N — код дополнения, xxx — значение ресурса, смысл которого отличается в зависимости от типа дополнения:

  • целочисленные дополнения — целочисленное значение заказываемого ресурса;
  • дополнения, заданные перечислениями — код элемента перечисления;
  • дополнения с типом учета "по выбору клиента" — код дополнения, входящего в состав основного дополнения. При этом значение заказываемого ресурса для этого дополнения так же передается в параметре вида addon_N

Код дополнения можно найти на странице Тарифные планы → Конфиг. → поле Id.

Ссылка на заказ тарифного плана с выбранными параметрами выглядит следующим образом:

Перенаправление на страницу заказа виртуального хостинга с параметрами
https://DOMAIN/billmgr?func=register&redirect=startpage%3Dvhost%26startform%3DITEMTYPE_INTNAME%252Eorder%252Eparam%26pricelist%3DPRICELIST_ID%26period%3DPERIOD_ID%26project%3DPROJECT_ID%26addon_N=xxx%26addon_N=xxx

Пример заказа тарифа виртуального хостинга (startform=vhost.order.param) с кодом 2 (pricelist=2). При этом значение дополнения "Лимит Web доменов" выставляем равным 15 (addon_5=15), значение дополнения "Дисковое пространство" выставляем равным 2048 (addon_3=2048)

Перенаправление на страницу заказа виртуального хостинга с параметрами
https://DOMAIN/billmgr?func=register&redirect=startpage%3Dvhost%26startform%3Dvhost%252Eorder%252Eparam%26pricelist%3D2%26period%3D3%26project%3D1%26addon_3=2048%26addon_5=15

Ссылка на оплату услуги

Если необходимо переадресовать клиента сразу в корзину или на оплату сделанного заказа, необходимо изменить следующие параметры: значение параметра startform меняется на quickorder, добавляется параметр redirect со значением basket (переадресация в корзину), или payment (переадресация на оплату заказа)

Ссылка, переадресовывающая клиента в корзину:

Перенаправление на корзину
https://DOMAIN/billmgr?func=register&redirect=startpage%3DITEMTYPE_INTNAME%26startform%3Dquickorder%26pricelist%3DPRICELIST_ID%26period%3DPERIOD_ID%26project%3D1%26addon_N%3Dxxx%26addon_N%3Dxxx%26redirect%3Dbasket

Ссылка, переадресовывающая клиента на страницу выбора метода оплаты услуги:

Перенаправление на страницу выбора метода оплаты
https://DOMAIN/billmgr?func=register&redirect=startpage%3DITEMTYPE_INTNAME%26startform%3Dquickorder%26pricelist%3DPRICELIST_ID%26period%3DPERIOD_ID%26project%3D1%26addon_N%3Dxxx%26addon_N%3Dxxx%26redirect%3Dpayment

Заказ доменного имени

Ссылка на заказ доменного имени содержит обязательные параметры, размещаемые в 'redirect':

  • checked_domain — список проверенных доменов с дополнительными параметрами. Формат записи следующий:
    • В доменном имени знак '-' заменяется на '_', знак '.', заменяется на '____________'
    • К полученному значению, с использованием разделителя ':', добавляется статус домена:
      • 0 — не проверен,
      • 1 — свободен,
      • 2 — занят,
      • 3 — ошибка определения статуса,
      • 4 — домен присутствует в BILLmanager.
    • Для регистрации домена, в качестве статуса следует использовать значение — 1, для трансфера — 3
    • К полученной строке добавляется код тарифного плана, с использованием разделителя ':'
    • К полученной строке добавляется флаг выбора доменного имени (0 — не выбран, 1 — выбран), с использованием разделителя ':'

      Пример параметра 'checked_domain'
      example____________ru:1:PRICELIST_ID:1
  • startform=domain.order.contact — перенаправление в BILLmanager для  заполнения информации о контакте (паспортные данные, ИНН и т.п.).
  • domain_action — действие с доменом. 'register' — регистрация нового домена, 'transfer'  — трансфер домена.
  • domain_name — имя регистрируемого домена.
  • selected_domain — закодированное по вышеописанному алгоритму доменное имя.
  • selected_pricelist — код выбранного тарифного плана.

При передаче нескольких значений в 'checked_domain', 'selected_domain' и 'selected_pricelist' значения разделяются через знак ','.

Все указанные параметры следует экранировать при подстановке в параметр 'redirect':

Пример ссылки
https://DOMAIN/billmgr?func=register&redirect=startpage%3Ddomain%26startform%3Ddomain.order.contact%26checked_domain%3Dexample____________ru%253A1%253APRICELIST_ID%253A1%252C%26domain_action%3Dregister%26domain_name%3Dexample.ru%26period%3D12%26selected_domain%3Dazcol18____________ru%26selected_pricelist%3DPRICELIST_ID

Расчет стоимости заказа

Функция pricelist.calculate возвращает стоимость услуги на указанный период, учитывает все выбранные дополнения:

Расчет стоимости заказа
https://DOMAIN/billmgr?func=pricelist.calculate&pricelist=PRICELIST_ID&period=PERIOD_ID&addon_XXX=VALUE

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

addon_XXX=VALUE — дополнительные ресурсы, где:

    • XXX — Id дополнения к тарифному плану, ADDON_ID.
    • VALUE — количество выделяемого ресурса. 

Проверка промокода

На сайте можно разместить поле ввода промокода на скидку. Чтобы провести проверку наличия такого кода в биллинговой системе используется команда promotion.promocode.check:


Проверка промокода
https://DOMAIN/billmgr?func=promotion.promocode.check&pricelist=PRICELIST_ID&period=PERIOD_ID&promocode=PROMOCODE

Дополнительная информация


Запросы к API BILLmanager поддерживают использование callback для json:

Использование callback
https://DOMAIN/billmgr?callback=JSON_CALLBACK&username=" + user.login + "&password=" + user.password + "&lang=ru&project=2&func=auth&out=json"