Description of ROOTPANEL.NET API for hosting and server management system Apply.dk
Содержание
- 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. Изменение тарифного плана
1. Введение
Это справочное руководство описывает HTTP-шлюз к системе распределённой регистрации Apply.dk (далее ROOTPANEL.NET API).
HTTP-шлюз — это метод взаимодействия с системой распределённой регистрации ROOTPANEL.NET API, позволяющий осуществлять операции в реальном времени за один шаг.
Для осуществления одношаговых (одноэтапных) операций, вся информация должна быть представлена в одном единственном HTTP-запросе. В интерфейсе ROOTPANEL.NET API нет понятия "состояния" и все запросы независимы друг от друга. HTTP-интерфейс поддерживает такие операции как создание заказа, продление заказа, приостановка заказа, запуск заказа и т.п. Доступные операции описаны ниже в этом документе.
2. Описание HTTP шлюза
Компания Apply.dk предоставляет не только реальный доступ к HTTP-шлюзу, но также и тестовый доступ для отладки взаимодействия с системой ROOTPANEL.NET API.
2.1. Реальный доступ
Запросы к HTTP-шлюзу должны направляться на URL
https://my.apply.dk/apih.php
Среднее время ответа при нормальных нагрузках сервера должно быть не более 5 или 10 секунд.
2.2. Тестовый доступ
Apply.dk предоставляет тестовый доступ к своему шлюзу для тестирования системы регистрации. Отличия тестового доступа от реального таковы:
- Плата за операции не взимается
- Операции с заказами реально не производятся, аккаунты не создаются
- Тестовая система не содержит информации о заказах, которая присутствует в реальном реестре.
Для использования тестовой системы, HTTP запросы должны направляться на тот же URL, что и для реальной системы. При этом используются следующие авторизационные данные:
- Логин: test
- Пароль: test
3. Отправка HTTP-запросов
3.1. Команды
HTTP-шлюз позволяет выполнять различные команды. В таблице ниже приведён список команд, которые могут быть осуществлены с использованием HTTP-шлюза. Для каждой операции требуется указание различных параметров (полей), которые описаны ниже в этом документе.
| Команда (значение command) | Описание |
| createOrder | Создание заказа |
| renewOrder | Продление заказа |
| suspendOrder | Остановка заказа |
| unSuspendOrder | Запуск остановленного заказа |
| getTarifs | Получение списка тарифных планов |
| restartOrder | Перезагрузка заказа |
| reinstallOrder | Переустановка заказа |
| getOrders | Получение списка заказов |
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. |
| 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, reseller, vds, dedicated, vpn, ssh, rtpllic, iptv. |
| tarifid | ID тарифного плана. Список доступных тарифных планов можно получить, выполнив команду, описанную в разделе 4.5. |
| period | Период на который производится создание заказа. Допустимые значения для данного поля по каждому тарифному плану можно получить, выполнив команду, описанную в разделе 4.5.. Значение необходимо указывать в месяцах. Пример: 1. |
| domain | Полное доменное имя для которого создается заказ, например example.com. Допустимы алфавитно-цифровые символы и символ дефиса. Русские имена доменов указываются в кодировке utf-8. Поле не является обязательным, если значение параметра allowWithoutDomain для тарифного плана равняется 1. |
| addons | ID дополнительной услуги, которую необходимо прикрепить к заказу. Несколько ID указываются через запятую. Список доступных дополнительных услуг для тарифного плана можно получить, выполнив команду, описанную в разделе 4.5. Поле не обязательное. |
| userid | ID клиента для которого необходимо создать заказ. Поле не используется при работе под обычным клиентом и является обязательным при работе под админом. |
В случае успешного выполнения команды, ROOTPANEL.NET API вернет поля, перечисленные в таблице ниже.
| Имя поля | Описание |
| status | Если команда выполнена успешно, значение всегда будет SUCCESS. |
| orderid | ID заказа. В дальнейшем используется для управления заказом. |
| vid | Тип тарифного плана, который был использован для создания заказа. |
| tarifid | ID тарифного плана, который был использован для создания заказа. |
| domain | Доменное имя для которого был создан заказ. |
| period | Период на который был создан заказ. |
| addons | ID дополнительных услуг, которые были прикреплены к заказу. |
| balance | Текущий баланс пользователя. |
| cost | Стоимость создания заказа. |
| currency | Код валюты в которой возвращены стоимость и баланс. Идентична валюте пользователя в биллинговой системе. |
| serverlogin | Дополнительные данные: логин заказа на сервере. |
| serverpassword | Дополнительные данные: пароль заказа на сервере. |
| remark | Дополнительные данные: примечание - может содержать различную дополнительную информацию по заказу. |
4.2. Продление заказа
Эта команда служит для продления заказа. В качестве значения поля command для этой команды должно быть указано renewOrder.
В таблице ниже перечислены поля, используемые при продлении заказа.
| Имя поля | Описание |
| orderid | ID заказа, возвращаемый командой, описанной в разделе 4.1. |
| serverlogin | Логин заказа на сервере. Поле не обязательное. Может использоваться вместо orderid. Не будет работать если в базе биллинга есть несколько заказов с указанным логином. |
| period | Период на который производится продление заказа. Допустимые значения для данного поля по каждому тарифному плану можно получить, выполнив команду, описанную в разделе 4.5.. Значение необходимо указывать в месяцах. Пример: 1. |
В случае успешного выполнения команды, ROOTPANEL.NET API вернет поля, перечисленные в таблице ниже.
| Имя поля | Описание |
| status | Если команда выполнена успешно, значение всегда будет SUCCESS. |
| orderid | ID заказа. |
| period | Период на который был продлен заказ. |
| balance | Текущий баланс пользователя. |
| cost | Стоимость продления заказа. |
| currency | Код валюты в которой возвращены стоимость и баланс. Идентична валюте пользователя в биллинговой системе. |
4.3. Остановка заказа
Эта команда служит для остановки заказа. В качестве значения поля command для этой команды должно быть указано suspendOrder.
В таблице ниже перечислены поля, используемые при остановке заказа.
| Имя поля | Описание |
| orderid | ID заказа, возвращаемый командой, описанной в разделе 4.1. |
| serverlogin | Логин заказа на сервере. Поле не обязательное. Может использоваться вместо orderid. Не будет работать если в базе биллинга есть несколько заказов с указанным логином. |
В случае успешного выполнения команды, ROOTPANEL.NET API вернет поля, перечисленные в таблице ниже.
| Имя поля | Описание |
| status | Если команда выполнена успешно, значение всегда будет SUCCESS. |
| orderid | ID заказа. |
4.4. Запуск остановленного заказа
Эта команда служит для запуска остановленного заказа. В качестве значения поля command для этой команды должно быть указано unSuspendOrder.
В таблице ниже перечислены поля, используемые при запуске остановленного заказа.
| Имя поля | Описание |
| orderid | ID заказа, возвращаемый командой, описанной в разделе 4.1. |
| serverlogin | Логин заказа на сервере. Поле не обязательное. Может использоваться вместо orderid. Не будет работать если в базе биллинга есть несколько заказов с указанным логином. |
В случае успешного выполнения команды, ROOTPANEL.NET API вернет поля, перечисленные в таблице ниже.
| Имя поля | Описание |
| status | Если команда выполнена успешно, значение всегда будет SUCCESS. |
| orderid | ID заказа. |
4.5. Получение списка тарифных планов
Эта команда служит для получения списка доступных тарифных планов. В качестве значения поля command для этой команды должно быть указано getTarifs.
В таблице ниже перечислены поля, используемые при получении списка тарифных планов.
| Имя поля | Описание |
| vid | Тип тарифного плана. Допустимые значения - hosting, reseller, vds, dedicated, vpn, ssh, rtpllic, iptv. |
В случае успешного выполнения команды, 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.
В таблице ниже перечислены поля, используемые при перезагрузке заказа.
| Имя поля | Описание |
| orderid | ID заказа, возвращаемый командой, описанной в разделе 4.1. |
| serverlogin | Логин заказа на сервере. Поле не обязательное. Может использоваться вместо orderid. Не будет работать если в базе биллинга есть несколько заказов с указанным логином. |
В случае успешного выполнения команды, ROOTPANEL.NET API вернет поля, перечисленные в таблице ниже.
| Имя поля | Описание |
| status | Если команда выполнена успешно, значение всегда будет SUCCESS. |
| orderid | ID заказа. |
4.7. Переустановка заказа
Эта команда служит для переустановки заказа (сервера). Команда поддерживается только для некоторых типов серверов. В качестве значения поля command для этой команды должно быть указано reinstallOrder.
В таблице ниже перечислены поля, используемые при переустановке заказа.
| Имя поля | Описание |
| orderid | ID заказа, возвращаемый командой, описанной в разделе 4.1. |
| serverlogin | Логин заказа на сервере. Поле не обязательное. Может использоваться вместо orderid. Не будет работать если в базе биллинга есть несколько заказов с указанным логином. |
В случае успешного выполнения команды, ROOTPANEL.NET API вернет поля, перечисленные в таблице ниже.
| Имя поля | Описание |
| status | Если команда выполнена успешно, значение всегда будет SUCCESS. |
| orderid | ID заказа. |
4.8. Получение списка заказов
Эта команда служит для получения списка заказов клиента. В качестве значения поля command для этой команды должно быть указано getOrders.
В таблице ниже перечислены поля, используемые при получении списка заказов.
| Имя поля | Описание |
| orderid | ID заказа для которого нужно получить информацию. Поле не обязательное. |
| serverlogin | Логин заказа на сервере для которого нужно получить информацию. Поле не обязательное. Может использоваться вместо orderid. Не будет работать если в базе биллинга есть несколько заказов с указанным логином. |
| userid | ID клиента для которого необходимо получить список заказов. Поле не используется при работе под обычным клиентом и является обязательным при работе под админом если не указан 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.
В таблице ниже перечислены поля, используемые при получении суммы внутреннего баланса.
| Имя поля | Описание |
| orderid | ID заказа для владельца которого необходимо получить сумму внутреннего баланса. Поле не используется при работе под обычным клиентом и является не обязательным при работе под админом. |
| serverlogin | Логин заказа на сервере для владельца которого необходимо получить сумму внутреннего баланса. Поле не используется при работе под обычным клиентом и является не обязательным при работе под админом. Может использоваться вместо orderid. Не будет работать если в базе биллинга есть несколько заказов с указанным логином. |
| userid | ID клиента для которого необходимо получить сумму внутреннего баланса. Поле не используется при работе под обычным клиентом и является обязательным при работе под админом если не указан orderid или serverlogin. |
В случае успешного выполнения команды, ROOTPANEL.NET API вернет поля, перечисленные в таблице ниже.
| Имя поля | Описание |
| status | Если команда выполнена успешно, значение всегда будет SUCCESS. |
| balance | Текущий баланс пользователя. |
| currency | Код валюты в которой возвращен баланс. Идентична валюте пользователя в биллинговой системе. |
4.10. Изменение тарифного плана
Эта команда служит для изменения тарифного плана у существующего заказа. В качестве значения поля command для этой команды должно быть указано updateOrderTarif.
В таблице ниже перечислены поля, используемые при изменении тарифного плана.
| Имя поля | Описание |
| orderid | ID заказа, возвращаемый командой, описанной в разделе 4.1. |
| serverlogin | Логин заказа на сервере. Поле не обязательное. Может использоваться вместо orderid. Не будет работать если в базе биллинга есть несколько заказов с указанным логином. |
| tarifid | ID нового тарифного плана. Список доступных тарифных планов можно получить, выполнив команду, описанную в разделе 4.5. |
В случае успешного выполнения команды, ROOTPANEL.NET API вернет поля, перечисленные в таблице ниже.
| Имя поля | Описание |
| status | Если команда выполнена успешно, значение всегда будет SUCCESS. |
| orderid | ID заказа. |
| tarifid | ID нового тарифного плана. |
| balance | Текущий баланс пользователя. |
| cost | Стоимость изменения тарифного плана. |
| currency | Код валюты в которой возвращены стоимость и баланс. Идентична валюте пользователя в биллинговой системе. |