Integration between BILLmanager and website
| Category path: | BILLmanager -> Integration |
| BILLmanager Corporate -> Integration |
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.
Contents
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.
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:
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"
