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

Материал из ISPWiki
Перейти к: навигация, поиск

Если вам необходимо более гибкое решение чем Витрина, то вы можете интегрировать BILLmanager со своим сайтом на более низком уровне, обращаясь к биллингу по API. В статье описаны некоторые сценарии использования и способы их реализации.

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

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

DOMAIN - доменное имя сервера с BILLmanager
PRICELIST_ID - Id тарифного плана.
ADDON_ID - Id дополнения к тарифному плану.
PERIOD_ID - Идентификатор периода оплаты. Если больше нуля, значит длинна периода в месяцах. -100 - триальный; -50 - день; 0 - вечный;
ITEM_id - Id услуги
ACCOUNT_ID -Id клиента
PARTNER_ID - Id реферала.
COUNTRY_ID - Id страны из справочника "страны"
PROJECT_ID - Id провайдера. В дистрибутивах младше Corporate = 1

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

Для интеграции создайте нового сотрудника. В правах разрешите только необходимые функции. Если запрос необходимо выполнять от имени сотрудника, в запросе будет указано AUTHIТFO_ADMIN.

Table view.png

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

Если клиент переадресуется в BILLmanager для регистрации, то клиента необходимо перенаправлять на URL:

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, не обязательный параметр
  • recovery со значение on, если необходимо отправить клиенту в письме о регистрации ссылку на сброс пароля
  • _ga - код привязки к Google Analytics, не обязательный параметр
  • 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;
      }
  • partner - если используется реферальная программа, то сайт должен запоминать PARTNER_ID (код партнера), если клиент пришел по реферальной ссылке. Обычно этот параметр сохраняют в cookies.
  • sesid - если используется реферальная программа. Идентификатор клика.

В ответ будет возвращено значение user.id - код созданного пользователя и account.id - код зарегистрированного клиента

Ссылки на регистрацию и заказ услуг

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

https://DOMAIN/billmgr?func=register&redirect=startpage%3DITEMTYPE_INTNAME%26startform%3DITEMTYPE_INTNAME%252Eorder%26pricelist%3DPRICELIST_ID%26project%3DPROJECT_ID

Где redirect представляет из себя описание перенаправления клиента после регистрации/авторизации в кодировке URL.


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

startpage=ITEMTYPE_INTNAME&startform=ITEMTYPE_INTNAME.order&pricelist=PRICELIST_ID&project=PROJECT_ID

Где

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


Если заказ выполняется на выбранный период, возможна переадресация клиента сразу на форму выбора параметров услуги. В этом случае значение параметров будет:

  • startform=ITEMTYPE_INTNAME.order.param
  • period=PERIOD_ID


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

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


Если необходимо переадресовать клиента сразу в корзину или на оплату сделанного заказа, необходимо изменить следующие параметры:

  • startform меняется на quickorder
  • добавляется параметр redirect со значением basket (переадресация в корзину), или payment (переадресация на оплату заказа)


Так же могут быть добавлены значения заказываемых ресурсов


Ссылка на заказ доменного имени

Отличие ссылки на заказ конкретного доменного имени, с переадресацией на заполнение данных контакта, в наличии ряда обязательных параметров, размещенных в параметре redirect:

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


Пример параметра: example____________ru:1:PRICELIST_ID:1

  • 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

Авторизация

 https://DOMAIN/billmgr?username=user@example.com&password=q1w2e3&lang=ru&project=PROJECT_ID&func=auth

Полезные функции

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

https://DOMAIN/billmgr?func=pricelist.export

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

Параметры:

  • elid=PROJECT_ID - Id провайдера в BILLmanager.
  • onlyavailable - выводить только доступные для заказа тарифные планы.
  • pricelist - Id тарифов через запятую, указывается только если нужно получить данные не всех тарифов
  • addonitemtype - Id типов продуктов дополнений к тарифным планам, указывается, если в выводе нужны не все дополнения
  • itemtype - Id типа продукта тарифов, которые нужно вывести, указывается только если нужны тарифы только определенного типа
  • exclude_pricelist - Id тарифов через запятую, которые нужно исключить из вывода функции
  • othercurrency - ISO код валюты, в которую нужно пересчитать цены тарифов и дополнений, если вдруг нужен дополнительный вывод в валюте отличной от валюты провайдера. Пересчет идет по текущему курсу в BILLmanager.

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

Запрос позволяет выдать стоимость одной услуги определенного тарифа, с определенными дополнениями.

https://DOMAIN/billmgr?func=pricelist.calculate&pricelist=PRICELIST_ID&period=PERIOD_ID&addon_XXX=VALUE
  • addon_XXX=VALUE - дополнительные заказанные услуги в рамках тарифа. XXX - Id дополнения к тарифному плану, ADDON_ID.

Проверить текущую авторизацию клиента, получить логин и ФИО

https://DOMAIN/billmgr?func=whoami

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

https://DOMAIN/billmgr?func=promotion.promocode.check&pricelist=PRICELIST_ID&period=PERIOD_ID&promocode=PROMOCODE

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

Возможно использовать callback для json. Пример:

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