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

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

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

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

Регистрация

Чтобы зарегистрировать клиента в 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 — код провайдера.
• 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 с правами администратора.

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

   https://domain.com?func=pricelist&out=print

   DIFF

2. Используйте функцию pricelist.export с параметром pricelist:

   https://domain.com?func=pricelist.export&out=print&onlyavailable=off&pricelist=id_list

   DIFF
   Пояснения к запросу

   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

    CODE
• 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:

https://DOMAIN/billmgr?callback=JSON_CALLBACK&username=" + user.login + "&password=" + user.password + "&lang=ru&project=2&func=auth&out=json"