API Friendhosting

Contents

1. Introduction
2. HTTP Gateway Description
2.1. Real Access
2.2. Test Access
3. Sending HTTP Requests
3.1. Commands
3.2. Input Data Format
3.3. Command Execution Results’ Format
3.4. General Request Fields
3.5. Error Notifications
3.6. Authentication Methods
3.6.1. Password-Based Authentication
3.6.2. Authentication Based on the API Key
4. Commands’ Description
4.1. Creating an Order
4.2. Renewing an Order
4.3. Suspending an Order
4.4. Starting a Suspended Order
4.5. Viewing the Tariff Plan List
4.6. Restarting an Order
4.7. Reinstalling an Order
4.8. Getting the List of Orders
4.9. Getting the User’s Balance

1. Introduction

This instruction manual describes the HTTP gateway to the distributed registration system(hereinafter API).
HTTP gateway is a method of interacting with the distributed registration system API. It allows making operations in real time in just one step.

To carry out one-step (one-stage) operations, all the information has to be included in one HTTP request. The API interface doesn’t recognize states, and all requests are independent from one another. The HTTP interface supports such operations as creating an order, prolonging an order, suspending an order, launching an order and more. The available operations are described further in this document.

2. HTTP Gateway Description

provides not only the real access to the HTTP gateway but also the test access to debug interaction with the system API.

2.1. Real Access

Requests to the HTTP gateway have to be directed at the following URL: https://my.friendhosting.net/apih.php

2.2. Test Access

Friendhosting LTD provides test access to its gateway for testing the registration system. The test access is different from the real one in the following three ways:
– Operations are conducted free of charge
– Operations with orders are not actually done, accounts are not created
– The test system doesn’t contain order information available in the real registry.

To use the test system, HTTP requests have to be directed at the same URL as for the real system. In this case, use the following authorization data:
login: test
pass: test

3. Sending HTTP Requests

3.1. Commands

HTTP gateway allows conducting different commands. Below in the table you will find the list of commands that can be carried out using the HTTP gateway. You need to use specific parameters (fields) that are described below for each command.

Command
(command value)
Description
createOrder Creating a new order
renewOrder Renewing the order
suspendOrder Suspending an order
unSuspendOrder Launching a suspended order
getTarifs Getting the list of tariff plans
restartOrder Restarting an order
reinstallOrder Reinstalling an order
getOrders Getting the list of orders

3.2. Input Data Format

The commands are transferred in the form of a standard HTTP/1.0 request using the POST or GET method. The command parameters are transferred as HTTP parameters. The following rules are applied in this case:
– All fields’ values are strings.
– All fields’ values are transferred in UTF-8 encoding.
– All required fields have to be included in the request and have to contain at least one character.
– HTTP parameters’ names have to match the names of the fields (capitalization is respected).
– All fields’ values have to be urlencoded.

3.3. Command Execution Results’ Format

The API interface answer is a serialized string containing a parameter array received using the PHP functions serialize. The response string is encoded using UTF-8. To convert the serialized string into a parameter array, you need to use the PHP function unserialize. There is also a possibility to get the answer in the JSON format.

3.4. General Request Fields

In this table you will find all the required fields that have to be included in any request.

Field Name Description
command Defines the command that has to be executed; for instance, createOrder
login User login in the billing system
pass User password in the billing system. Pass and apikey fields are mutually exclusive and can’t be included in the same request. More information in the section 3.6.
apikey The key for gaining access to the API interface. Pass and apikey fields are mutually exclusive and can’t be included in the same request. More information in the section 3.6.
json If the field value is 1, the system will return the answer in the JSON format. The field is not obligatory.

3.5. Error Notifications

There are two types of errors – critical and non-critical. In the event of a critical error, it is considered that the command is not executed. In the event of a non-critical error, it is considered that the command is executed or will be executed later. In the event of an errors during command execution, API returns parameters listed in the table below.

Field Name Description
status The result of command execution. In the event of a critical error, the value is always ERROR. In the event of a non-critical one, it is SUCCESS.
errorCode Error code.
errorMsg A detailed description of the error.

 

In the table below you will find possible critical errors you may encounter when working with the API.

Error Code Description
1 Error in connection to the database
2 Error in saving the data in the database
3 User login is not stated
4 User is not found
5 API access is denied
6 Password or API key is not stated
7 The stated password or API key is not correct
8 Unknown command
9 It is prohibited to use the password and API key in the same request
10 Tariff plans are absent
11 Tariff plan identifier is not provided
12 Tariff plan is not found
13 Domain name is not provided
14 The tariff plan for the stated domain name is already ordered
15 The order period is not stated
16 The order period stated is unacceptable
17 The stated additional service is unacceptable
18 The order identifier is not stated
19 The order is not found
20 There are unpaid bills for this order
21 The order is already suspended
22 The order is already started
23 The order is expired
24 The tariff plan type is not valid
25 The operation is not supported for this type of orders
26 Orders are absent
27 The tariff plan can be ordered by one client only once
28 The stated amount of the additional service is unacceptable
29 You need to order an additional service from the group
54 Access denied. IP address is not on the list of permissioned ones

 

IN the table below you will find possible non-critical errors you may encounter when working with API.

Error Code Description
30 The order is placed, but due to technical reasons it will be processed manually.
31 The order is placed, but it will be processed after the payment.

 

3.6. Authentication Methods

The API registration system supports two authentication methods: based on the login and passwords, or based on the API key.

3.6.1. Password-Based Authentication

Authentication is done using the request field login and pass. The user with the stated login and password has to exist in the billing system for the successful authentication. Besides, the said user has to have API access enabled for them.

3.6.2. Authentication Based on the API Key

Authentication is done using the request fields login and apikey. The user with the stated login and API key has to exist in the billing system for the successful authentication. Besides, the said user has to have API access enabled for them.

4. Commands’ Description

4.1. Creating an Order

This command is used for creating a new order. You need to use createOrder as a value for the field command of this operation.
In the table below you will find the fields used when creating an order.

Field Name Description
vid Tariff plan type. The acceptable values are: hosting, vds, dedicated. If the value is not stated, hosting is used by default.
tarifid Tariff plan ID. The list of available tariff plans can be gained by executing the command described in 4.5.
period Period for the created order. You can view the acceptable values for this field by executing the command described in 4.5.. The value has to be stated in months. Example: 1.
domain The full domain name that the order is created for (for instance, example.com). Alphabet characters, digits, and hyphens are allowed. The Cyrillic domain names are stated in the UTF-8 encoding. The field is not required if the allowWithoutDomain parameter value is 1.
addons ID of the additional service that has to be attached to the order. Several IDs are separated by commas. The list of available additional services for each tariff plan can be viewed by executing the command described in 4.5. This field is not obligatory.

 

In the event of a successful command execution, API will return the fields listed in the table below.

Field Name Description
status If the command is executed successfully, the value will always be SUCCESS.
orderid Order ID in the API system. It is used for further order management.
vid The type of tariff plan that was used for creating the order.
tarifid Tariff plan ID in the API system that was used for creating the order.
domain The domain name the order was created for.
period The period the order was created for.
addons ID of the additional services that were attached to the order.
balance The current user balance.
cost Order creation price.
currency The code of the currency used for the returned price and balance. It is identical to the currency of the user in the billing system.
serverlogin Additional data: the order login on the server.
serverpassword Additional data: the order password on the server.
remark Additional data: notes; the field may contain various additional information regarding the order.

 

4.2. Renewing an Order

This command is used for renewing an order. You need to use renewOrder as a value for the field command of this operation.
In the table below you will find the fields used when renewing an order.

Field Name Description
orderid Order ID in the API system which is returned by the command described in 4.1.
period Period for the created order. You can view the acceptable values for this field by executing the command described in 4.5.. The value has to be stated in months. Example: 1.

 

In the event of a successful command execution, API will return the fields listed in the table below.

Field Name Description
status If the command is executed successfully, the value will always be SUCCESS.
orderid Order ID in the API system.
period The period the order was renewed for.
balance The current user balance.
cost Order renewal price.
currency The code of the currency used for the returned price and balance. It is identical to the currency of the user in the billing system.

4.3. Suspending an Order

This command is used for suspending an order. You need to use suspendOrder as a value for the field command of this operation.
In the table below you will find the fields used when suspending an order.

Field Name Description
orderid Order ID in the API system which is returned by the command described in 4.1.

In the event of a successful command execution, API will return the fields listed in the table below.

Field Name Description
status If the command is executed successfully, the value will always be SUCCESS.
orderid Order ID in the API system.

4.4. Starting a Suspended Order

This command is used for launching a suspended order. You need to use unSuspendOrder as a value for the field command of this operation.
In the table below you will find the fields used when launching a suspended order.

Field Name Description
orderid Order ID in the API system which is returned by the command described in 4.1.

In the event of a successful command execution, API will return the fields listed in the table below.

Field Name Description
status If the command is executed successfully, the value will always be SUCCESS.
orderid Order ID in the API system.

4.5. Viewing the Tariff Plan List

This command is used for getting a list of available tariff plans. You need to use getTarifs as a value for the field command of this operation.
In the table below you will find the fields used to get the list of tariff plans.

Field Name Description
vid Tariff plan type. The acceptable values are: hosting, vds, dedicated. If the value is not stated, hosting is used by default.

In the event of a successful command execution, API will return the fields listed in the table below.

Field Name Description
status If the command is executed successfully, the value will always be SUCCESS.
tarifs This field returns an array of fields. Each field of the array is, in its turn, an array and contains the following fields:
id – tariff plan ID
vid – tariff plan type
name – tariff plan name
costMonthly – tariff plan monthly price
costSetup – tariff plan installation cost
currency – the currency code used for the prices
allowWithoutDomain – if it’s value is 1, you can order this tariff plan without stating a domain name
months – a field array containing available order periods:
months – the order period in months
discount – the discount for this order period
allowForNewOrder – if it’s 1, you are allowed to use the order period for new orders
allowForRenew – if it’s 1, you are allowed to use the order period for renewing orders
addons – a field array containing available additional services:
id – additional service ID
name – additional service name
costMonthly – additional service monthly price
costSetup – additional service installation price

4.6. Restarting an Order

This command is used for restarting an order (server). The command is supported only by certain types of servers. You need to use restartOrder as a value for the field command of this operation.
In the table below you will find the fields used when restarting an order.

Field Name Description
orderid Order ID in the API system which is returned by the command described in 4.1.

 

In the event of a successful command execution, API will return the fields listed in the table below.

Field Name Description
status If the command is executed successfully, the value will always be SUCCESS.
orderid Order ID in the API system.

4.7. Reinstalling an Order

This command is used for reinstalling an order (server). The command is supported only by certain types of servers. You need to use reinstallOrder as a value for the field command of this operation.
In the table below you will find the fields used when reinstalling an order.

Field Name Description
orderid Order ID in the API system which is returned by the command described in 4.1.

In the event of a successful command execution, API will return the fields listed in the table below.

Field Name Description
status If the command is executed successfully, the value will always be SUCCESS.
orderid Order ID in the API system.

4.8. Getting the List of Order

This command is used for getting the list of the client’s orders. The command is supported only by certain types of servers. You need to use getOrders as a value for the field command of this operation.
In the table below you will find the fields used when getting the list of orders.

Field Name Description
orderid Order ID in the API system which is returned by the command described in 4.1.
Not a required field! If stated, only one order will be returned.

In the event of a successful command execution, API will return the fields listed in the table below.

Field Name Description
status If the command is executed successfully, the value will always be SUCCESS.
orders This field returns a field array. Each array contains the following fields:
orderid – order ID
domain – domain name
domain_reg – 0 – without domain registration, 1 – with domain registration, 3 – with domain transfer
vid – tariff plan type
tarifid – tariff plan ID
tarifname – tariff plan name
orderdate – order placement date
startdate – order start date
todate – the date until which the order is paid for
leftdays – the number of days until the order’s end
status – order status (0 – not processed, 1 – processed, 2 – suspended, 3 – being processed)

4.9. Getting the User’s Balance

This command is used for viewing the sum on the balance of a billing system. You need to use getBalance as a value for the field command of this operation.

In the event of a successful command execution, API will return the fields listed in the table below.

Field Name Description
status If the command is executed successfully, the value will always be SUCCESS.
balance Current user balance.
currency The currency code of the returned balance. It is identical to the user currency in the billing system.
This site is using cookie files, Google Analytics system to collect statistics about website visitors and also collects data like your IP and geolocation. More in our policy.
By continuing to use current website you are automatically agreed with using described technologies.