Содержание

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. Получение суммы внутреннего баланса пользователя

1. Введение

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

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

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

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

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

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

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

Friendhosting LTD предоставляет тестовый доступ к своему шлюзу для тестирования системы регистрации. Отличия тестового доступа от реального таковы:
— Плата за операции не взимается
— Операции с заказами реально не производятся, аккаунты не создаются
— Тестовая система не содержит информации о заказах, которая присутствует в реальном реестре.

Для использования тестовой системы, 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 параметров. При этом действуют следующие правила:
— Значения всех полей являются строками.
— Значения полей передаются в кодировке utf-8.
— Все обязательные поля должны присутствовать в запросе и должны содержать как минимум один символ.
— Названия параметров HTTP-запроса должны в точности соответствовать названиям полей с учётом регистра символов.
— Значения всех полей должны быть urlencoded.

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

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

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

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

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

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

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

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

В таблице ниже приведены возможные критические ошибки при работе с 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	Необходимо заказать дополнительную услугу из группы
54	Доступ запрещен. IP отсутствует в списке разрешенных

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

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

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

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

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

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

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

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

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

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

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

Имя поля	Описание
vid	Тип тарифного плана. Допустимые значения — hosting, vds, dedicated. Если значение не задано, то используется hosting.
tarifid	ID тарифного плана. Список доступных тарифных планов можно получить, выполнив команду, описанную в разделе 4.5.
period	Период, на который производится создание заказа. Допустимые значения для данного поля по каждому тарифному плану можно получить, выполнив команду, описанную в разделе 4.5.. Значение необходимо указывать в месяцах. Пример: 1.
domain	Полное доменное имя, для которого создается заказ, например example.com. Допустимы алфавитно-цифровые символы и символ дефиса. Русские имена доменов указываются в кодировке utf-8. Поле не является обязательным, если значение параметра allowWithoutDomain для тарифного плана равняется 1.
addons	ID дополнительной услуги, которую необходимо прикрепить к заказу. Несколько ID указываются через запятую. Список доступных дополнительных услуг для тарифного плана можно получить, выполнив команду, описанную в разделе 4.5. Поле не обязательное.