Опис ROOTPANEL.NET API системи керування хостингом та серверами HOSTETSKI:)


Содержание

1. Введение

Это справочное руководство описывает HTTP-шлюз к системе распределённой регистрации HOSTETSKI:) (далее ROOTPANEL.NET API).

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

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

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

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

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

Запросы к HTTP-шлюзу должны направляться на URL https://my.hostetski.com/apih.php

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

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

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

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

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

3.1. Команды

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

Команда
(значение command)
Описание
createOrderСоздание заказа
renewOrderПродление заказа
suspendOrderОстановка заказа
unSuspendOrderЗапуск остановленного заказа
getTarifsПолучение списка тарифных планов
restartOrderПерезагрузка заказа
reinstallOrderПереустановка заказа
getOrdersПолучение списка заказов

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

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

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.
languageЯзык подробного описания ошибок (russian, english, ukrainian). Поле не обязательное. По умолчанию: russian
jsonЕсли для поля задано значение равное единице, то система будет выдавать ответ в JSON-формате. Поле не обязательное.
currencyТрехбуквенный код валюты. Если для поля задано значение, все цены в ответах будут в заданной валюте, в противном случае цены будут в валюте, которая указана в настройках клиента. Поле не обязательное.

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Тарифный план не доступен для данного заказа
31Недостаточно среств на внутреннем балансе
38Продление не возможно ранее чем за {X} дней до окончания оплаченного периода
54Доступ запрещен. IP отсутствует в списке разрешенных

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

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

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 Тип тарифного плана. Допустимые значения - hosting, vds, vpn.
tarifid ID тарифного плана.
Список доступных тарифных планов можно получить, выполнив команду, описанную в разделе 4.5.
period Период на который производится создание заказа. Допустимые значения для данного поля по каждому тарифному плану можно получить, выполнив команду, описанную в разделе 4.5.. Значение необходимо указывать в месяцах. Пример: 1.
domainПолное доменное имя для которого создается заказ, например example.com. Допустимы алфавитно-цифровые символы и символ дефиса. Русские имена доменов указываются в кодировке utf-8. Поле не является обязательным, если значение параметра allowWithoutDomain для тарифного плана равняется 1.
addonsID дополнительной услуги, которую необходимо прикрепить к заказу. Несколько ID указываются через запятую.
Список доступных дополнительных услуг для тарифного плана можно получить, выполнив команду, описанную в разделе 4.5. Поле не обязательное.
useridID клиента для которого необходимо создать заказ. Поле не используется при работе под обычным клиентом и является обязательным при работе под админом.

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

Имя поляОписание
statusЕсли команда выполнена успешно, значение всегда будет SUCCESS.
orderidID заказа. В дальнейшем используется для управления заказом.
vidТип тарифного плана, который был использован для создания заказа.
tarifidID тарифного плана, который был использован для создания заказа.
domainДоменное имя для которого был создан заказ.
periodПериод на который был создан заказ.
addonsID дополнительных услуг, которые были прикреплены к заказу.
balanceТекущий баланс пользователя.
costСтоимость создания заказа.
currencyКод валюты в которой возвращены стоимость и баланс. Идентична валюте пользователя в биллинговой системе.
serverloginДополнительные данные: логин заказа на сервере.
serverpasswordДополнительные данные: пароль заказа на сервере.
remarkДополнительные данные: примечание - может содержать различную дополнительную информацию по заказу.

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

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

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

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

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

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

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


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

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

Имя поляОписание
orderidID заказа, возвращаемый командой, описанной в разделе 4.1.
serverloginЛогин заказа на сервере. Поле не обязательное. Может использоваться вместо orderid. Не будет работать если в базе биллинга есть несколько заказов с указанным логином.

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

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

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

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

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

Имя поляОписание
orderidID заказа, возвращаемый командой, описанной в разделе 4.1.
serverloginЛогин заказа на сервере. Поле не обязательное. Может использоваться вместо orderid. Не будет работать если в базе биллинга есть несколько заказов с указанным логином.

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

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

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

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

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

Имя поляОписание
vidТип тарифного плана. Допустимые значения - hosting, vds, vpn.

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

Имя поляОписание
statusЕсли команда выполнена успешно, значение всегда будет SUCCESS.
tarifsВ данном поле возвращается массив полей. Некоторые поля массива в свою очередь так же являются массивами и содержит в себе другие поля:

id - ID тарифного плана
vid - тип тарифного плана
name - название тарифного плана
servername - название тарифного плана на сервере (доступно только админам)
costMonthly - ежемесячная стоимость тарифного плана
costSetup - разовая стоимость тарифного плана
currency - код валюты в которой указана стоимость
allowWithoutDomain - если 1, то разрешено заказывать тарифный план без указания доменного имени

months - массив полей доступных сроков заказа:
      months - срок заказа в месяцах
      discount - скидка для данного срока заказа
      allowForNewOrder - если 1, срок доступен для новых заказов
      allowForRenew - если 1, срок доступен для продления заказов
      costRenew - доп. стоимость (разовый платеж) при продлении
      freeZonesIfNewOrder - массив доменных зон, которые будут бесплатными (на 1 год) при новом заказе тарифного плана на данный срок вместе с регистрацией домена
      freeZonesIfRenew - массив доменных зон, которые будут бесплатными (на 1 год) при продлении тарифного плана на данный срок вместе с продлением домена

addons - массив полей доступных дополнительных услуг:
      id - идентификатор услуги
      textid - текстовый идентификатор услуги
      name - название услуги
      costMonthly - ежемесячная стоимость услуги
      costSetup - разовая стоимость услуги
      activeByDefault - если 1, то услуга активна по умолчанию при оформлении заказа в web-версии биллинга

4.6. Перезагрузка заказа

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

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

Имя поляОписание
orderidID заказа, возвращаемый командой, описанной в разделе 4.1.
serverloginЛогин заказа на сервере. Поле не обязательное. Может использоваться вместо orderid. Не будет работать если в базе биллинга есть несколько заказов с указанным логином.

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

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

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

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

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

Имя поляОписание
orderidID заказа, возвращаемый командой, описанной в разделе 4.1.
serverloginЛогин заказа на сервере. Поле не обязательное. Может использоваться вместо orderid. Не будет работать если в базе биллинга есть несколько заказов с указанным логином.

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

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

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

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

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

Имя поляОписание
orderidID заказа для которого нужно получить информацию. Поле не обязательное.
serverloginЛогин заказа на сервере для которого нужно получить информацию. Поле не обязательное. Может использоваться вместо orderid. Не будет работать если в базе биллинга есть несколько заказов с указанным логином.
useridID клиента для которого необходимо получить список заказов. Поле не используется при работе под обычным клиентом и является обязательным при работе под админом если не указан orderid или serverlogin.

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

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

orderid - ID заказа
domain - доменное имя
domain_reg - 0 - без регистрации домена, 1 - с регистрацией домена, 3 - с трансфером домена
vid - тип тарифного плана
tarifid - ID тарифного плана
tarifname - название тарифного плана
tarifservername - название тарифного плана на сервере (доступно только админам)
orderdate - дата оформления заказа
startdate - дата начала заказа
todate - дата до когда оплачен заказ
leftdays - кол-во дней до конца заказа
status - статус заказа (0 - не обработан, 1 - обработан, 2 - приостановлен, 3 - в обработке)

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

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

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

Имя поляОписание
orderidID заказа для владельца которого необходимо получить сумму внутреннего баланса. Поле не используется при работе под обычным клиентом и является не обязательным при работе под админом.
serverloginЛогин заказа на сервере для владельца которого необходимо получить сумму внутреннего баланса. Поле не используется при работе под обычным клиентом и является не обязательным при работе под админом. Может использоваться вместо orderid. Не будет работать если в базе биллинга есть несколько заказов с указанным логином.
useridID клиента для которого необходимо получить сумму внутреннего баланса. Поле не используется при работе под обычным клиентом и является обязательным при работе под админом если не указан orderid или serverlogin.

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

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

4.10. Изменение тарифного плана

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

В таблице ниже перечислены поля, используемые при изменении тарифного плана.

Имя поляОписание
orderidID заказа, возвращаемый командой, описанной в разделе 4.1.
serverloginЛогин заказа на сервере. Поле не обязательное. Может использоваться вместо orderid. Не будет работать если в базе биллинга есть несколько заказов с указанным логином.
tarifidID нового тарифного плана.
Список доступных тарифных планов можно получить, выполнив команду, описанную в разделе 4.5.

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

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