Integration between BILLmanager and website

From ISPWiki
Jump to: navigation, search

If you need a more flexible solution than Shop-window, you can integrate BILLmanager with your website through BILLmanager API. In this article you can find a few integration variants.

General information

All requests are sent to BILLmanager API through a standard protocol. It's possible to get a response in XML or JSON. To perform this, add &out=xml, &out=json or &out=sjson to each request depending on a required format.

DOMAIN - BILLmanager server's domain name
PRICELIST_ID - Tariff plan ID.
ADDON_ID - ID of tariff plan's add-on.
PERIOD_ID - Payment period ID. If it is more than 0, the period is measured in months. -100 - trial; -50 - day; 0 - lifetime;
ITEM_id - Service ID
ACCOUNT_ID - Client ID
PARTNER_ID - Partner ID.
COUNTRY_ID - Country ID from the "Country" directory.
PROJECT_ID - Provider ID. Available only in BILLmanager 5 Corporate, in BILLmanager Standard or Advanced = 1.

By default, the ID column is hidden in most lists. To enable this column, click "Table settings", and select the "Column ID" check.

To set up integration, create a new administrator. Navigate to the "Rights" module to allow only required functions. If it's necessary to execute a request as Administrator, AUTHIТFO_ADMIN will be indicated in the request.

Table view-en.png

Client registration

If you want a client to be redirected to BILLmanager for registration, you should redirect him to the following URL:

https://DOMAIN/billmgr?func=register

In the tariff edit form you can find links for registration and order of a certain tariff or product type. After registration the client will be automatically redirected to a service order form associated with a certain tariff and selected order period, or to a payment form, or to a Cart (if the quick order links are used).

If the client is already registered in the system, after authorization he will be redirected to a service order form.

If the client gets registered directly on a website, without redirection to BILLmanager, you need to call the 'register function with the following parameters:

  • sok set to ok - save data
  • email - Login and email of a new client.
  • passwd - Password
  • realname - Client's name
  • phone - phone number
  • conditions_agree set to on, if a client needs to agree to a service agreement
  • offer_xxx set to on, if a client needs to agree to an offer while the registration process
  • country - country id according to BILLmanager directory, an optional parameter
  • state - country id according to BILLmanager directory, an optional parameter
  • recovery set to on, if you want to send a password reset notification
  • _ga - Google Analytics id, an optional parameter
  • tzoffset - time zone offset against GMT, an optional parameter, in BILLmanager in can be set via JavaScirpt:
The following is the example of the time zone offset
      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 - If you use an affiliate program, the site should remember PARTNER_ID in case a client was referred by the referral link. Usually, this parameter is kept in cookies.
  • sesid - If you use an affiliate program. Click identifier.

The system will return user.id - id of the newly created client, and account.id - id of the registered client

Links to client registration and service order

A tariff order form looks like this:

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

where redirect describes redirection of a client after registration/login, in the URL encoding.

The following is the same example after decoding:

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

where

  • startpage - page/list that will open after registration/login
  • startform - service order form that will open after registration/login
  • pricelist - tariff id
  • project - provider id

If a client makes an order for a certain period, he can be redirected directly to the service properties form. Parameter values:

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

You can also pass add-ons addon_xxx - where xxx is a resource value:

  • integer add-ons - integer value of the resource that a client orders
  • add-on specified by enumeration - id of the enumeration element
  • "client can choose" add-on - id of the add-on included into the main add-on. The value of the resource that a client orders should be passed in a parameter addon_xxx

If you want a client to be redirected directly to the Cart or payment form, edit the following parameters:

  • change startform into quickorder
  • add the redirect parameter with basket (redirect to a Cart), or payment (redirect to a payment form) value.

You can also add values for the resources that a client orders.

Domain order link

There is a number of required parameters in the redirect parameter:

  • checked_domain - a list of checked domains with additional parameters. The format:
    • The '-' symbols in a domain name is changed into '_', '.', is changed into '____________'
    • A domain status separated with ':' will be added to the resulting value:
      • 0 - not checked,
      • 1 - available,
      • 2 - in use,
      • 3 - error defining status,
      • 4 - domain is registered in BILLmanager.
    • For domain registration use 1 as its status, 3 - for transfer.
    • A tariff id separated with ':' will be added to the resulting value
    • Domain name selection identifier (0 - not selected, 1 - selected), separated with ':' will added to the resulting value


Parameter example: example____________ru:1:PRICELIST_ID:1

  • domain_action - register for registration of a new domain name, transfer for domain transfer
  • domain_name - domain name
  • selected_domain - domain name encoded as described above
  • selected_pricelist - id of the selected tariff plan

When passing several values into checked_domain, selected_domain and selected_pricelist, values are separated with ','.

Example of the link:

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

Information about tariff plans

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

This function returns the cost of tariffs and add-ons in the selected format. Parameters:

  • elid=PROJECT_ID - Provider ID in BILLmanager.
  • onlyavailable - Show only tariff plans that are available for order.
  • pricelist - Tariff plans' ID separated by commas, they are specified, only if you need to get data only from certain add-ons.
  • addonitemtype - ID of product type add-ons to tariff plans. They are specified, only if you need to get data only from certain add-ons.
  • itemtype - Product type ID. They are specified, only if you need tariff plans of a certain type.
  • exclude_pricelist - Tariffs ID separated by commas, which are excluded from the function output.
  • othercurrency - ISO code of the currency, in which you want to bill clients for tariffs and add-ons, if you need additional output in another currency (different from provider's currency). It is converted according to the current exchange rate in BILLmanager.

Authorization

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

Useful functions

Information about tariff plans

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

this function returns prices for tariff plans and their add-ons in the selected format.

Parameters:

  • elid=PROJECT_ID - provider Id in BILLmanager.
  • onlyavailable - show only available for order tariff plans.
  • pricelist - Id of tariff plans space separated, if you want to show only a few plans
  • addonitemtype - Id of product type add-ons. It is specified, if you want to show only a few add-ons
  • itemtype - Id of the product types you want to show. It is specified, if you want to show only certain tariff plans.
  • exclude_pricelist - Id of tariff plans, space separated, that you want to exclude from the function output
  • othercurrency - ISO code of the currency, if you need to show prices of tariff plans and add-ons in currency that differs from the default provider's currency. Recalculation will be made at the exchange rate of BILLmanager, which is prevailing the date of making changes.

Calculating order price

The following request allows to show the price for a certain service and certain add-ons:

https://DOMAIN/billmgr?func=pricelist.calculate&pricelist=PRICELIST_ID&period=PERIOD_ID&addon_XXX=VALUE
  • addon_XXX=VALUE - tariff add-ons. XXX - Id of the tariff add-on, ADDON_ID.

Checking client authorization, retrieving his login and full name

https://DOMAIN/billmgr?func=whoami

Checking promo code

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

Additional information

You can use callback for json. For example:

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