Описание ROOTPANEL.NET API системы управления хостингом и серверами Friendhosting.net

Содержание

1. Введение
2. Описание HTTP шлюза
    2.1. Реальный доступ
    2.2. Тестовый доступ
3. Отправка HTTP запросов
    3.1. Команды
    3.2. Формат входных данных
    3.3. Формат результата выполнения команды
    3.4. Общие поля запросов
    3.5. Сообщения об ошибках
    3.6. Способы аутентификации
        3.6.1. Аутентификация по паролю
        3.6.2. Аутентификация по ключу API
4. Описание команд
    4.1. Создание заказа
    4.2. Продление заказа
    4.3. Остановка заказа
    4.4. Запуск остановленного заказа
    4.5. Получение списка тарифных планов
    4.6. Заказ дополнительных услуг
    4.7. Переустановка заказа
    4.8. Получение списка заказов
    4.9. Получение суммы внутреннего баланса пользователя
    4.10. Включение сервера
    4.11. Выключение сервера
    4.12. Перезагрузка сервера
    4.13. Сброс сервера
    4.14. Открытие VNC-консоли

1. Введение

Это справочное руководство описывает HTTP-шлюз к системе распределённой регистрации Friendhosting.net (далее ROOTPANEL.NET API).
HTTP-шлюз — это метод взаимодействия с системой распределённой регистрации ROOTPANEL.NET API, позволяющий осуществлять операции в реальном времени за один шаг.

Для осуществления одношаговых (одноэтапных) операций, вся информация должна быть представлена в одном единственном HTTP-запросе. В интерфейсе ROOTPANEL.NET API нет понятия "состояния" и все запросы независимы друг от друга. HTTP-интерфейс поддерживает такие операции как создание заказа, продление заказа, приостановка заказа, запуск заказа и т.п. Доступные операции описаны ниже в этом документе.

2. Описание HTTP шлюза

Компания Friendhosting.net предоставляет не только реальный доступ к HTTP-шлюзу, но также и тестовый доступ для отладки взаимодействия с системой ROOTPANEL.NET API.

2.1. Реальный доступ

Запросы к HTTP-шлюзу должны направляться на URL:

https://my.friendhosting.net/apih.php

Среднее время ответа при нормальных нагрузках сервера должно быть не более 10 секунд.

2.2. Тестовый доступ

Friendhosting.net предоставляет тестовый доступ к своему шлюзу для тестирования системы регистрации. Отличия тестового доступа от реального таковы:

    - Плата за операции не взимается
    - Операции с заказами реально не производятся, аккаунты не создаются
    - Тестовая система не содержит информации о заказах, которая присутствует в реальном реестре.

Для использования тестовой системы, HTTP запросы должны направляться на тот же URL, что и для реальной системы. При этом используются следующие авторизационные данные:

    login: test
    pass: test

3. Отправка HTTP-запросов

3.1. Команды

HTTP-шлюз позволяет выполнять различные команды. В таблице ниже приведён список команд, которые могут быть осуществлены с использованием HTTP-шлюза. Для каждой операции требуется указание различных параметров (полей), которые описаны ниже в этом документе.

Команда (значение command)	Описание
createOrder	Создание заказа
renewOrder	Продление заказа
suspendOrder	Остановка заказа
unSuspendOrder	Запуск остановленного заказа
getTarifs	Получение списка тарифных планов
reinstallOrder	Переустановка заказа
getOrders	Получение списка заказов
getBalance	Получение суммы внутреннего баланса пользователя
addonsOrder	Заказ дополнительных услуг
startServer	Включение сервера
shutdownServer	Выключение сервера
rebootServer	Перезагрузка сервера
resetServer	Сброс сервера
getVnc	Открытие VNC-консоли

3.2. Формат входных данных

Команды передаются в виде стандартного запроса HTTP/1.0 методом POST или GET. Параметры команды передаются в виде HTTP параметров. При этом действуют следующие правила:

- Значения всех полей являются строками.
- Значения полей передаются в кодировке utf-8.
- Все обязательные поля должны присутствовать в запросе и должны содержать как минимум один символ.
- Названия параметров HTTP-запроса должны в точности соответствовать названиям полей с учётом регистра символов.
- Значения всех полей должны быть urlencoded.

3.3. Формат результата выполнения команды

Ответом интерфейса ROOTPANEL.NET API является сериализованная строка, содержащая в себе массив параметров, полученная с помощью PHP-функции serialize.
Кодировка строки ответа utf-8.
Для преобразования сериализованной строки обратно в массив параметров, необходимо использовать PHP-функцию unserialize.
Так же есть возмоность получать ответ в формате JSON.

3.4. Общие поля запросов

В таблице перечислены все обязательные поля, которые должны присутствовать в любом запросе.

Имя поля	Описание
command	Определяет команду, которая должна быть выполнена, например createOrder
login	Логин пользователя в биллинговой системе
pass	Пароль пользователя в биллинговой системе. Поля pass и apikey являются взаимоисключающими и не могут встречаться в одном запросе. См. раздел 3.6.
apikey	Ключ для доступа к интерфейсу ROOTPANEL.NET API. Поля pass и apikey являются взаимоисключающими и не могут встречаться в одном запросе. См. раздел 3.6.
json	Если для поля задано значение равное единице, то система будет выдавать ответ в JSON-формате. Поле не обязательное.

3.5. Сообщения об ошибках

Существует два типа ошибок - критические и не критические.
В случае критической ошибки считается, что команда не выполнена.
В случае не критической ошибки считается, что команда выполнена, либо будет выполнена позже.

В случае ошибки при выполнении команды, ROOTPANEL.NET API возвращает параметры, перечисленные в таблице ниже.

Имя поля	Описание
status	Результат выполнения команды. В случае критической ошибки значение всегда равно ERROR. В случае не критической SUCCESS.
errorCode	Код ошибки
errorMsg	Подробное описание ошибки

В таблице ниже приведены возможные критические ошибки при работе с ROOTPANEL.NET API.

Код ошибки	Описание
1	Ошибка подключения к БД
2	Ошибка сохранения данных в БД
3	Не указан логин пользователя
4	Пользователь не найден
5	Доступ к API отключен
6	Не указан пароль или ключ API
7	Указан неправильный пароль или ключ API
8	Неизвестная команда
9	Запрещено использовать пароль и ключ API в одном запросе
10	Тарифные планы отсутствуют
11	Не указан идентификатор тарифного плана
12	Тарифный план не найден
13	Не указано доменное имя
14	Тарифный план для указанного доменного имени уже заказан
15	Не указан срок заказа
16	Указан недопустимый срок заказа
17	Указана недопустимая дополнительная услуга
18	Не указан идентификатор заказа
19	Заказ не найден
20	Для заказа есть неоплаченные или необработанные счета
21	Заказ уже приостановлен
22	Заказ уже запущен
23	Заказ просрочен
24	Тип тарифного плана указан неверно
25	Операция не поддерживается для заказов данного типа
26	Заказы отсутствуют
27	Тарифный план может быть заказан только одним клиентом только один раз
28	Указано недопустимое количество дополнительной услуги
29	Необходимо заказать дополнительную услугу из группы
40	Указана недопустимая локация.
41	Указано недопустимое значение для автопродления.
42	Не указан период автопродления.
43	Указан недопустимый период автопродления.
44	В очереди уже есть заявка на установку или переустановку для этого заказа.
45	Ошибка добавления заявки в очередь.
46	Дополнительный трафик, Порт 1GB и Порт 1Gbps с оплатой по факту - не совместимые услуги.
47	Указанная панель управления не доступна для выбранной операционной системы.
48	Не указан идентификатор операционной системы или дополнительная услуга не найдена.
49	Не указан идентификатор панели управления или дополнительная услуга не найдена.
50	Операция временно не доступна для данной локации.
51	Дополнительный диск и Еженедельный бекап - не возможно заказать одновременно. Закажите услуги отдельно.
52	Не указан идентификатор дополнительной услуги.
53	Сначала необходимо продлить заказ.
54	Доступ запрещен. IP отсутствует в списке разрешенных
55	Ошибка выполнения команды

В таблице ниже приведены возможные не критические ошибки при работе с ROOTPANEL.NET API.

Код ошибки	Описание
30	Заявка принята, но по техническим причинам будет обработана в ручном режиме.
31	Заявка принята, но будет обработана после оплаты счета.

3.6. Способы аутентификации

В системе регистрации ROOTPANEL.NET API поддерживается два способа аутентификации: по логину и паролю, а также аутентификация по ключу API.

3.6.1. Аутентификация по паролю

Аутентификация осуществляется с использованием полей запроса login и pass. Пользователь с указанным логином и паролем должен существовать в биллинговой системе для успешного прохождения аутентификации. Так же для него должен быть включен доступ к API.

3.6.2. Аутентификация по ключу API

Аутентификация осуществляется с использованием полей запроса login и apikey. Пользователь с указанным логином и ключом API должен существовать в биллинговой системе для успешного прохождения аутентификации. Так же для него должен быть включен доступ к API.

4. Описание команд

4.1. Создание заказа

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

Имя поля	Описание
vid	Тип тарифного плана. Допустимые значения - vds.
tarifid	ID тарифного плана. Список доступных тарифных планов можно получить, выполнив команду, описанную в разделе 4.5.
locationid	ID локации в которой необходимо разместить сервер. Список доступных локаций можно получить, выполнив команду, описанную в разделе 4.5. Поле не обязательное.
period	Период, на который производится создание заказа. Допустимые значения для данного поля по каждому тарифному плану можно получить, выполнив команду, описанную в разделе 4.5.. Значение необходимо указывать в месяцах. Пример: 1.
addons	ID дополнительной услуги, которую необходимо прикрепить к заказу. Несколько ID указываются через запятую. Список доступных дополнительных услуг для тарифного плана можно получить, выполнив команду, описанную в разделе 4.5.
autorenew	Автопродление заказа. Допустимые значения - 0 (выключено), 1 (включено). По умолчанию: 0 (выключено). Поле не обязательное.
autorenewperiod	Период, на который будет производиться автоматическое продление заказа (аналогично полю period). Поле обязательное если включено автопродление.

В случае успешного выполнения команды, ROOTPANEL.NET API вернет поля, перечисленные в таблице ниже.

Имя поля	Описание
status	Если команда выполнена успешно, значение всегда будет SUCCESS.
orderid	ID заказа в системе ROOTPANEL.NET API. В дальнейшем используется для управления заказом.
vid	Тип тарифного плана, который был использован для создания заказа.
tarifid	ID тарифного плана в системе ROOTPANEL.NET API, который был использован для создания заказа.
domain	Доменное имя, для которого был создан заказ.
period	Период на который был создан заказ.
addons	ID дополнительных услуг, которые были прикреплены к заказу.
balance	Текущий баланс польователя.
cost	Стоимость создания заказа.
currency	Код валюты в которой возвращены стоимость и баланс. Идентична валюте пользователя в биллинговой системе.
serverlogin	Логин заказа.
serverpassword	Пароль заказа.

4.2. Продление заказа

Эта команда служит для продления заказа. В качестве значения поля command для этой команды должно быть указано renewOrder.
В таблице ниже перечислены поля, используемые при продлении заказа.

Имя поля	Описание
orderid	ID заказа в системе ROOTPANEL.NET API, возвращаемый командой, описанной в разделе 4.1.
period	Период, на который производится продление заказа. Допустимые значения для данного поля по каждому тарифному плану можно получить, выполнив команду, описанную в разделе 4.5.. Значение необходимо указывать в месяцах. Пример: 1.

В случае успешного выполнения команды, ROOTPANEL.NET API вернет поля, перечисленные в таблице ниже.

Имя поля	Описание
status	Если команда выполнена успешно, значение всегда будет SUCCESS.
orderid	ID заказа в системе ROOTPANEL.NET API.
period	Период на который был продлен заказ.
balance	Текущий баланс польователя.
cost	Стоимость продления заказа.
currency	Код валюты в которой возвращены стоимость и баланс. Идентична валюте пользователя в биллинговой системе.

4.3. Остановка заказа

Эта команда служит для остановки заказа. В качестве значения поля command для этой команды должно быть указано suspendOrder.
В таблице ниже перечислены поля, используемые при остановке заказа.

Имя поля	Описание
orderid	ID заказа в системе ROOTPANEL.NET API, возвращаемый командой, описанной в разделе 4.1.

В случае успешного выполнения команды, ROOTPANEL.NET API вернет поля, перечисленные в таблице ниже.

Имя поля	Описание
status	Если команда выполнена успешно, значение всегда будет SUCCESS.
orderid	ID заказа в системе ROOTPANEL.NET API.

4.4. Запуск остановленного заказа

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

Имя поля	Описание
orderid	ID заказа в системе ROOTPANEL.NET API, возвращаемый командой, описанной в разделе 4.1.

В случае успешного выполнения команды, ROOTPANEL.NET API вернет поля, перечисленные в таблице ниже.

Имя поля	Описание
status	Если команда выполнена успешно, значение всегда будет SUCCESS.
orderid	ID заказа в системе ROOTPANEL.NET API.

4.5. Получение списка тарифных планов

Эта команда служит для получения списка доступных тарифных планов. В качестве значения поля command для этой команды должно быть указано getTarifs.
В таблице ниже перечислены поля, используемые при получении списка тарифных планов.

Имя поля	Описание
vid	Тип тарифного плана. Допустимые значения - vds.
tarifid	ID тарифа в системе ROOTPANEL.NET API Не обязательное поле! Если указано, будет возвращен только один тариф.

В случае успешного выполнения команды, ROOTPANEL.NET API вернет поля, перечисленные в таблице ниже.

Имя поля	Описание
status	Если команда выполнена успешно, значение всегда будет SUCCESS.
tarifs	В данном поле возвращается массив полей. Каждое поле массива в свою очередь так же является массивом и содержит в себе следующие поля: id - ID тарифного плана vid - тип тарифного плана name - название тарифного плана costMonthly - ежемесячная стоимость тарифного плана currency - код валюты, в которой указана стоимость allowWithoutDomain - если 1, то разрешено заказывать тарифный план без указания доменного имени months - массив полей доступных сроков заказа: months - срок заказа в месяцах discount - скидка для данного срока заказа allowForNewOrder - если 1, то разрешено использовать срок заказа для новых заказов allowForRenew - если 1, то разрешено использовать срок заказа для продления заказов addons - массив полей доступных дополнительных услуг: id - ID доп. услуги name - название доп. услуги costMonthly - ежемесячная стоимость доп. услуги cntforoneorder - максимальное кол-во услуги в заказе (0 - без ограничений) onlyifrenew - если 1, то услуга доступна только для существующих заказов locations - массив полей доступных локаций: id - ID локации name - название локации costMonthly - ежемесячная стоимость тарифного плана в локации

4.6. Заказ дополнительных услуг

Эта команда служит для заказа дополнительных услуг. В качестве значения поля command для этой команды должно быть указано addonsOrder.
В таблице ниже перечислены поля, используемые при переустановке заказа.

Имя поля	Описание
orderid	ID заказа в системе ROOTPANEL.NET API, возвращаемый командой, описанной в разделе 4.1.
addons	ID дополнительной услуги, которую необходимо прикрепить к заказу. Несколько ID указываются через запятую. Список доступных дополнительных услуг для тарифного плана можно получить, выполнив команду, описанную в разделе 4.5.

В случае успешного выполнения команды, ROOTPANEL.NET API вернет поля, перечисленные в таблице ниже.

Имя поля	Описание
status	Если команда выполнена успешно, значение всегда будет SUCCESS.
orderid	ID заказа в системе ROOTPANEL.NET API.
addons	ID дополнительных услуг, которые были прикреплены к заказу.
balance	Текущий баланс польователя.
cost	Стоимость дополнительных услуг.
currency	Код валюты в которой возвращены стоимость и баланс. Идентична валюте пользователя в биллинговой системе.

4.7. Переустановка заказа

Эта команда служит для переустановки заказа (сервера). Комманда поддерживается только для некоторых типов серверов. В качестве значения поля command для этой команды должно быть указано reinstallOrder.
В таблице ниже перечислены поля, используемые при переустановке заказа.

Имя поля	Описание
orderid	ID заказа в системе ROOTPANEL.NET API, возвращаемый командой, описанной в разделе 4.1.
osid	ID дополнительной услуги (операционной системы), которую необходимо использовать при переустановке. Список доступных дополнительных услуг для тарифного плана можно получить, выполнив команду, описанную в разделе 4.5.
panelid	ID дополнительной услуги (панели управления), которую необходимо использовать при переустановке. Список доступных дополнительных услуг для тарифного плана можно получить, выполнив команду, описанную в разделе 4.5.

В случае успешного выполнения команды, ROOTPANEL.NET API вернет поля, перечисленные в таблице ниже.

Имя поля	Описание
status	Если команда выполнена успешно, значение всегда будет SUCCESS.
orderid	ID заказа в системе ROOTPANEL.NET API.
serverlogin	Новый логин заказа.
serverpassword	Новый пароль заказа.

4.8. Получение списка заказов

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

Имя поля	Описание
orderid	ID заказа в системе ROOTPANEL.NET API, возвращаемый командой, описанной в разделе 4.1. Не обязательное поле! Если указано, будет возвращен только один заказ.

В случае успешного выполнения команды, ROOTPANEL.NET API вернет поля, перечисленные в таблице ниже.

Имя поля	Описание
status	Если команда выполнена успешно, значение всегда будет SUCCESS.
orders	В данном поле возвращается массив полей. Каждый массив содержит в себе следующие поля: orderid - ID заказа vid - тип тарифного плана tarifid - ID тарифного плана tarifname - название тарифного плана orderdate - дата оформления заказа startdate - дата начала заказа todate - дата до когда оплачен заказ leftdays - кол-во дней до конца заказа status - статус заказа (0 - не обработан, 1 - обработан, 2 - приостановлен, 3 - в обработке) serverlogin - логин заказа serverpassword - пароль заказа serveripv4 - основной IPv4-адрес serveripv6 - основной IPv6-адрес extraips - массив полей дополнительных IP-адресов

4.9. Получение суммы внутреннего баланса пользователя

Эта команда служит для получения суммы внутреннего баланса пользователя биллинговой системы. В качестве значения поля command для этой команды должно быть указано getBalance.

В случае успешного выполнения команды, ROOTPANEL.NET API вернет поля, перечисленные в таблице ниже.

Имя поля	Описание
status	Если команда выполнена успешно, значение всегда будет SUCCESS.
balance	Текущий баланс польователя.
currency	Код валюты в которой возвращен баланс. Идентична валюте пользователя в биллинговой системе.

4.10. Включение сервера

Эта команда служит для включения сервера. В качестве значения поля command для этой команды должно быть указано startServer.
В таблице ниже перечислены поля, используемые при выключении сервера.

Имя поля	Описание
orderid	ID заказа в системе ROOTPANEL.NET API, возвращаемый командой, описанной в разделе 4.1.

В случае успешного выполнения команды, ROOTPANEL.NET API вернет поля, перечисленные в таблице ниже.

Имя поля	Описание
status	Если команда выполнена успешно, значение всегда будет SUCCESS.
orderid	ID заказа в системе ROOTPANEL.NET API.

4.11. Выключение сервера

Эта команда служит для программного выключения сервера. В качестве значения поля command для этой команды должно быть указано shutdownServer.
В таблице ниже перечислены поля, используемые при выключении сервера.

Имя поля	Описание
orderid	ID заказа в системе ROOTPANEL.NET API, возвращаемый командой, описанной в разделе 4.1.

В случае успешного выполнения команды, ROOTPANEL.NET API вернет поля, перечисленные в таблице ниже.

Имя поля	Описание
status	Если команда выполнена успешно, значение всегда будет SUCCESS.
orderid	ID заказа в системе ROOTPANEL.NET API.

4.12. Перезагрузка сервера

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

Имя поля	Описание
orderid	ID заказа в системе ROOTPANEL.NET API, возвращаемый командой, описанной в разделе 4.1.

В случае успешного выполнения команды, ROOTPANEL.NET API вернет поля, перечисленные в таблице ниже.

Имя поля	Описание
status	Если команда выполнена успешно, значение всегда будет SUCCESS.
orderid	ID заказа в системе ROOTPANEL.NET API.

4.13. Сброс сервера

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

Имя поля	Описание
orderid	ID заказа в системе ROOTPANEL.NET API, возвращаемый командой, описанной в разделе 4.1.

В случае успешного выполнения команды, ROOTPANEL.NET API вернет поля, перечисленные в таблице ниже.

Имя поля	Описание
status	Если команда выполнена успешно, значение всегда будет SUCCESS.
orderid	ID заказа в системе ROOTPANEL.NET API.

4.14. Открытие VNC-консоли

Эта команда служит для открытия VNC-консоли. В качестве значения поля command для этой команды должно быть указано getVnc.
В таблице ниже перечислены поля, используемые при открытии консоли.

Имя поля	Описание
orderid	ID заказа в системе ROOTPANEL.NET API, возвращаемый командой, описанной в разделе 4.1.

В случае успешного выполнения команды, ROOTPANEL.NET API вернет поля, перечисленные в таблице ниже.

Имя поля	Описание
status	Если команда выполнена успешно, значение всегда будет SUCCESS.
orderid	ID заказа в системе ROOTPANEL.NET API.
wss_url	URL-адрес websocket прокси-сервера для использования
password	VNC пароль для этого подключения (пароль работает только в сочетании с wss_url)