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

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

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

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

Если вы включили reCAPTCHA для 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 провайдера;
ITEMTYPE_INTNAME — внутреннее (служебное) наименование типа продукта. Значения можно посмотреть в разделе Типы продуктов, поле Внутреннее наименование.

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

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

Регистрация

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

Регистрация в BILLmanager

https://DOMAIN/billmgr?func=register

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

sok=ok — подтверждение операции;
email — логин и email нового клиента;
passwd — пароль нового клиента;
realname — ФИО клиента;
phone — номер телефона;
conditions_agree со значением on, если для регистрации необходимо принятие условий использования;
offer_xxx со значение on, если используется принятие договора-оферты при регистрации;
country — код страны в соответствии со справочником BILLmanager, необязательный параметр;
state — код страны в соответствии со справочником BILLmanager, необязательный параметр;
project — код провайдера.
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 — код провайдера.

Авторизация клиента

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&out=<формат_вывода_информации>

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

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

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

Предварительно получите ID всех тарифов. Например, для этого можно использовать функцию pricelist:
```
https://domain.com?func=pricelist&out=print
```
Используйте функцию 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 со значением cart (переадресация в корзину), или 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%3Dcart

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

Перенаправление на страницу выбора метода оплаты

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, для трансфера — 2
- К полученной строке добавляется код тарифного плана, с использованием разделителя ':'
- К полученной строке добавляется флаг выбора доменного имени (0 — не выбран, 1 — выбран), с использованием разделителя ':'
  Пример параметра 'checked_domain'
```
name_domain____________ru:1:PRICELIST_ID:1
```
startform=domain.order.contact — перенаправление в BILLmanager для заполнения информации о контакте (паспортные данные, ИНН и т.п.);
domain_action — действие с доменом. register — регистрация нового домена, transfer — трансфер домена;
domain_name — имя регистрируемого домена;
selected_domain — закодированное по вышеописанному алгоритму доменное имя;
selected_pricelist — код выбранного тарифного плана;
PRICELIST_ID — id тарифного плана.

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

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

Пример ссылки

https://DOMAIN/billmgr?func=register&redirect=startpage%3Ddomain%26startform%3Ddomain.order.contact%26checked_domain%3Dname_domain____________ru%253A1%253APRICELIST_ID%253A1%252C%26domain_action%3Dregister%26domain_name%3Dname_domain.ru%26period%3D12%26selected_domain%3name_domain____________ru%26selected_pricelist%3DPRICELIST_ID

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

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

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

https://DOMAIN/billmgr?func=pricelist.calculate&pricelist=PRICELIST_ID&period=PERIOD_ID&addon_XXX=VALUE

Для вызова функции могут потребоваться данные пользователя клиента, указанные через su или authinfo.

Чтобы включить стоимость дополнения в итоговую сумму заказа, добавьте в запрос параметр 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"