Программный интерфейс (API) для партнеров

Программный интерфейс позволяет принимать заказы хостинга прямо на вашем сайте и отправлять их на наш сервер для обработки. В основе реализации интерфейса лежит протокол SOAP. К описанию прилагается рабочий пример, который можно встроить на ваш сайт.

Подключение к API

Для вызовов к API Вам потребуются:

Для партнеров: логин (ваш PIN) и пароль. Используйте следующий URL для вызовов SOAP: https://api.from.sh/wm.php;
Для дилеров: логин и пароль. Используйте следующий URL для вызовов SOAP: https://api.from.sh/dealer.php;
Для реселлеров: логин и пароль. Используйте следующий URL для вызовов SOAP: https://api.from.sh/seller.php;

Если PIN привязан к аккаунту виртуального хостинга, для авторизации следует использовать PIN и пароль для входа в Панель управления аккаунтом.

Классы

Работы с классами SOAP осуществляется посредством методов. Методы принимают входные параметры и возвращают значения. Также возможен выброс исключения (throw exception), которое можно соответствующим образом обработать. Имя класса передается в качестве параметра к URL (например: https://api.from.sh/wm.php?Soap_Order)

Класс Soap_Order (Заказ хостинга)

Класс, предназначенный для создания заказа хостинга — в частности, для проверки корректности указываемых в нем данных. Для тестирования процедуры заказа можно использовать метод validate, который аналогичен методу create, за исключением возвращаемого значения (выбрасываемые исключения будут такие же, как и в случае создания заказа). Вы можете использовать один из файлов примеров для реализации работы с API:

sample_order1.php — простой вариант с минимумом кода, реализующий только заказ хостинга на физическое лицо;
sample_order2.php — расширенный вариант, реализующий заказ хостинга на физическое лицо, юридическое лицо или на ИП. Данный вариант содержит форму с AJAX-валидацией.

Основываясь на этих примерах и используя документацию, приведенную в данном разделе, вы сможете без труда разместить на своем сайте собственную форму для заказа хостинга.

Метод getAvailablePackages

Описание

array getAvailablePackages ()

Метод реализует получение списка доступных для заказа тарифных планов.

Возвращаемые значения

Возвращаемое значение — массив, в ключах которого идентификаторы, а в значениях — массивы вида:

Array
(
    [1st] => Array
        (
            [package_descr] => Первый
            [package_descr_en] => First
        )
...

Элемент массива package_descr содержит название тарифного плана на русском языке;
Элемент массива package_descr_en содержит название тарифного плана на английском языке;

Метод getPackageInfo

Описание

array getPackageInfo ( [ string $package ] )

Метод возвращает информацию о тарифном плане. Этот метод можно использовать для проверки доступности тарифного плана.

Возвращаемые значения

Возвращаемое значение — массив вида:

Array
(
    [1st] => Array
        (
            [package_descr] => Первый
            [package_descr_en] => First
        )
...

Элемент массива package_descr содержит название тарифного плана на русском языке;
Элемент массива package_descr_en содержит название тарифного плана на английском языке;

Метод getAvailablePeriods

Описание

array getAvailablePeriods ( [ string $package ] )

Метод реализует получение списка доступных для заказа периодов предоставления услуг хостинга.

Параметры

package — идентификатор тарифного плана

Возвращаемые значения

Возвращаемое значение — массив значений доступных периодов заказа в месяцах для выбранного тарифа. Если идентификатор тарифного плана не указан, будут возвращены все доступные значения.

Метод validate

Описание

array validate ( array $params )

Метод реализует проверку корректности данных, указанных в заказе.

Параметры

params — массив значений (string), в зависимости от типа заказа:
- order_type — тип заказа (см. ниже);
- domain — имя домена;
- regmov — атрибут «заказ/перенос домена». Допустимые значения: 'reg' (регистрация), 'mov' (перенос);
- package — идентификатор тарифного плана;
- period — период заказа услуги. Допустимые значения: '1m', '3m', '6m', '12m' (1, 3, 6 и 12 месяцев соответственно). Для некоторых тарифных планов могут быть допустимы только некоторые значения;
- comment — комментарий к заказу;
Заказ на физическое лицо (order_type = 'f'):
- name — Ф.И.О.;
- email — контактный адрес электронной почты;
- birth_date — дата рождения;
- passport — паспортные данные;
- address — адрес;
Заказ на организацию (order_type = 'u'):
- org_name — наименование организации;
- org_email — контактный адрес электронной почты;
- inn — ИНН;
- kpp — КПП;
- bank — наименование банка;
- bik — БИК;
- c_acc — корреспондентский счет;
- r_acc — расчетный счет;
- org_boss — Ф.И.О. руководителя организации;
- org_address — юридический адрес организации;
- org_post_address — почтовый адрес;
- org_post_receiver — получатель корреспонденции;
- org_phone — телефон организации;
- org_fax — факс организации;
- contact_name — Ф.И.О. контактной персоны;
- contact_phone — телефон контактной персоны;
Заказ на ИП (order_type = 'i'):
- inpr_name — Ф.И.О.;
- inpr_email — контактный адрес электронной почты;
- inpr_birth_date — дата рождения;
- inpr_passport — паспортные данные;
- inpr_inn — ИНН;
- inpr_bank — наименование банка;
- inpr_bik — БИК;
- inpr_c_acc — корреспондентский счет;
- inpr_r_acc — расчетный счет;
- inpr_address — адрес;
- inpr_post_address — почтовый адрес;
- inpr_post_receiver — получатель корреспонденции;
- inpr_phone — телефон;
- inpr_fax — факс;
- inpr_contact_name — Ф.И.О. контактной персоны;
- inpr_contact_phone — телефон контактной персоны;

Большинство параметров проверяются на соответствие шаблонам (можно использовать как подсказки в формах):

ФИО — Аникеева Ирина Сергеевна;
Адрес электронной почты — ira@misspups.net или, если нужно указать несколько адресов: ira@misspups.net, anothermail@somewhere.com;
Адреса — 123456, Москва, Кулечный пер., д.5, кв.14 или 123456, Одинцово, Московская обл., Кулечный пер., д.5, кв.14;
Паспорт — 34 02 651241 выдан 48 о/м г.Москвы 26.12.1990;
Телефоны и факсы — +7 495 1234122 или, если нужно указать несколько номеров: +7 495 1234122, +7 495 6786789;
Дата рождения — 19.08.1971;
Получатель корреспонденции — Аникеева И.С.;

Возвращаемые значения

Исходный массив значений, после санации.

Исключения

Order type is required — тип заказа (order_type) не указан;
Order type incorrect — тип заказа (order_type) указан неверно, допустимые типы: 'f' (физическое лицо), 'u' (организация), 'i' (ИП);
Domain required — не указано имя домена (domain);
Incorrect field: domain — имя домена указано неверно (домен должен выглядеть как domainname.tld);
Domain unavailable — указанное в заказе доменное имя недоступно. Скорее всего, домен находится в черном списке бесплатных хостингов (сам или его часть), например somedomain.ucoz.ru вызовет данное исключение;
Register or move attribute required — не указан (или указан неверно) атрибут «заказ/перенос домена» (regmov). Допустимые значения: 'reg' (регистрация), 'mov' (перенос);
Package incorrect — тарифный план (package) не указан или указан неверно;
Period incorrect — период заказа (period) указан неверно. Допустимые значения: '1m', '3m', '6m', '12m' (1, 3, 6 и 12 месяцев соответственно). Для некоторых тарифных планов могут быть допустимы только некоторые значения (например, только '12m');
PIN incorrect — неверно указан PIN (если авторизация прошла успешно, такое может быть только в случае блокировки PIN);
Error while handle request — ошибка обработки запроса. Обратитесь к разработчику.

Исключения для ошибок в полях формы стандартизованы (шаблон: Incorrect field: %fieldname%) для удобной валидации формы на стороне клиента (где %fieldname% — название поля формы).

Для заказов на физическое лицо (order_type = 'f'):

Incorrect field: name — Ф.И.О. (name) указаны неверно;
Incorrect field: email — контактный адрес электронной почты (email) указан неверно;
Incorrect field: birth_date — дата рождения (birth_date) указана неверно;
Incorrect field: passport — паспортные данные (passport) указаны неверно (должны совпадать с шаблоном);
Incorrect field: address — адрес (address) указан неверно (должен совпадать с шаблоном);

Для заказов на организацию (order_type = 'u'):

Incorrect field: org_name — наименование организации (org_name) указано неверно;
Incorrect field: org_email — контактный адрес электронной почты (org_email) указан неверно;
Incorrect field: inn — ИНН (inn) указан неверно;
Incorrect field: kpp — КПП (kpp) указан неверно;
Incorrect field: bank — наименование банка (bank) указано неверно;
Incorrect field: bik — БИК (bik) указан неверно;
Incorrect field: c_acc — корреспондентский счет (c_acc) указан неверно;
Incorrect field: r_acc — расчетный счет (r_acc) указан неверно;
Incorrect field: org_boss — Ф.И.О. руководителя организации (org_boss) указаны неверно;
Incorrect field: org_address — юридический адрес (org_address) организации указан неверно (должен совпадать с шаблоном);
Incorrect field: org_post_address — почтовый адрес (org_post_address) организации указан неверно (должен совпадать с шаблоном);
Incorrect field: org_post_receiver — получатель корреспонденции (org_post_receiver) указан неверно;
Incorrect field: org_phone — телефон организации (org_phone) указан неверно (должен совпадать с шаблоном);
Incorrect field: org_fax — факс организации (org_fax) указан неверно (должен совпадать с шаблоном);
Incorrect field: contact_name — Ф.И.О. контактной персоны (contact_name) указаны неверно;
Incorrect field: contact_phone — телефон контактной персоны (contact_phone) указан неверно (должен совпадать с шаблоном);

Для заказов на ИП (order_type = 'i'):

Incorrect field: inpr_name — Ф.И.О. (inpr_name) указаны неверно;
Incorrect field: inpr_email — контактный адрес электронной почты (inpr_email) указан неверно;
Incorrect field: inpr_birth_date — дата рождения (inpr_birth_date) указана неверно;
Incorrect field: inpr_passport — паспортные данные (inpr_passport) указаны неверно (должны совпадать с шаблоном);
Incorrect field: inpr_inn — ИНН (inpr_inn) указан неверно;
Incorrect field: inpr_bank — наименование банка (inpr_bank) указано неверно;
Incorrect field: inpr_bik — БИК (inpr_bik) указан неверно;
Incorrect field: inpr_c_acc — корреспондентский счет (inpr_c_acc) указан неверно;
Incorrect field: inpr_r_acc — расчетный счет (inpr_r_acc) указан неверно;
Incorrect field: inpr_address — адрес (inpr_address) указан неверно (должен совпадать с шаблоном);
Incorrect field: inpr_post_address — почтовый адрес (inpr_post_address) указан неверно (должен совпадать с шаблоном);
Incorrect field: inpr_post_receiver — получатель корреспонденции (inpr_post_receiver) указан неверно;
Incorrect field: inpr_phone — телефон (inpr_phone) указан неверно;
Incorrect field: inpr_fax — факс (inpr_fax) указан неверно;
Incorrect field: inpr_contact_name — Ф.И.О. контактной персоны (inpr_contact_name) указаны неверно;
Incorrect field: inpr_contact_phone — телефон контактной персоны (inpr_contact_phone) указан неверно;

Метод create

Описание

int create ( array $params )

Метод реализует создание нового заказа хостинга.

Параметры

params — массив значений, в зависимости от типа заказа, структура аналогична одноименному параметру в методе validate, кроме одного дополнительного параметра ip в котором следует передавать IP-адрес пользователя (например $_SERVER['REMOTE_ADDR'])

Возвращаемые значения

Возвращаемое значение — номер созданного заказа.

Исключения

Наследует исключения метода validate;
Error while handle request — Ошибка обработки запроса. Обратитесь к разработчику.

Класс Soap_Whois (Проверка домена)

Класс реализует получение информации о доступности домена. Вы можете использовать файл примера для реализации работы с API: sample_whois.php.

Метод getInfo

Описание

array getInfo ( string $domain )

Метод реализует, собственно, получение информации о доступности домена.

В зависимости от состояния домена возвращается различный набор значений. Работа этого метода может быть проиллюстрирована диаграммой:

Параметры

domain — имя домена для проверки

Возвращаемые значения

Массив с различными ключами (зависит от состояния домена):

Для всех состояний:

Элемент массива domain содержит имя домена;
Элемент массива domain_wo_tld содержит имя домена без суффикса зоны;
Элемент массива domain_tld содержит суффикс зоны;
Элемент массива state результат проверки (taken — занят, free — свободен, exist — уже существует на хостинге).

Для состояний:

Домен занят (state = 'taken'):
- Элемент массива whois содержит ответ Whois-сервера по запрашиваемому домену.
Домен свободен (state = 'free'):
- Элемент массива available (значения 'y', 'n') содержит информацию о возможности заказа домена.

Исключения

Domain name incorrect — имя домена указано неверно;
Unsupported tld — зона (tld) не поддерживается сервисом;
Error while handle request — ошибка обработки запроса. Обратитесь к разработчику.

Метод getAvailableTlds

Описание

array getAvailableTlds ()

Метод возвращает массив доступных для регистрации зон (tld).

Возвращаемые значения

Возвращает массив вида:

Array
(
    [biz] => 3
    [cc] => 3
    [cn] => 3
    [com] => 2
    ...

Каждый элемент массива: ключ — зона (tld), доступная для регистрации, значение — минимально допустимое количество символов в имени домена.

Метод massCheck

Описание

array massCheck ( string $domain_wo_tld, array $tlds)

Проверка домена на занятость по списку зон (tld).

Параметры

domain_wo_tld — имя домена без зоны (например, для домена example.com это будет example)
tlds — массив зон для проверки (например, полученный из метода getAvailableTlds)

Возвращаемые значения

Возвращает массив вида:

Array
(
    [0] => Array
        (
            [domain] => domain.biz
            [state] => t
        )

    [1] => Array
        (
            [domain] => domain.cc
            [state] => t
        )

    [2] => Array
        (
            [domain] => domain.cn
            [state] => t
        )
    ...
)

Каждый элемент массива представляет собой массив из двух значений — домен (domain) и занятость (state, может принимать значения 't' — занят, 'f' — свободен).

Исключения

Error while handle request — ошибка обработки запроса. Обратитесь к разработчику.

Класс Soap_Auth (Вход в Панель управления)

Аутентификация пользователей Панели управления для создания собственной формы входа. Файл с примером для реализации работы с API:

sample_auth.php

Метод auth

Описание

array auth ( string $login, string $pass, string $ip )

Метод осуществляет проверку пары имя пользователя/пароль и возвращает данные для входа в Панель управления: ссылку и ключ (token). Для входа в Панель управления нужно перейти по ссылке с параметром key, равным значению ключа.

Параметры

login — имя пользователя;
pass — пароль пользователя;
ip — IP-адрес пользователя;

Возвращаемые значения

Возвращаемое значение — массив вида:


Array 
( 
    [username] => testuser 
    [url] => https://cp.example.com/login.php 
    [key] => 6c6e46efe3275d8b7811f8346ae41d48bafdbf55be86a744 ) 
)

Элемент массива username содержит имя пользователя;
Элемент массива url содержит URL для перехода;
Элемент массива key содержит ключ (token), действительный в течение 30 секунд;

Исключения

Authentication failed — аутентификация не пройдена (не совпадает пара логин/пароль, пользователя не существует или же пользователь заблокирован/удален);

Класс Soap_Dealers (Для дилеров)

В этом классе Вы найдете полезные методы для интеграции нашей системы с Вашим сайтом.

Метод getclients

Описание

array getClients ( )

Метод возвращает список клиентов дилеров.

Возвращаемые значения

Возвращаемое значение — массив вида:


Array
(
    [0] => Array
        (
            [login] => testuser
            [package] => 1st
            [statement] => -10
            [suspended] => no
        )

Элемент массива login содержит имя пользователя;
Элемент массива package содержит название тарифа;
Элемент массива statement текущий баланс пользователя в рублях;
Элемент массива suspended заблокирован ли пользователь (значения 'yes', 'no');

Исключения

Authentication failed — аутентификация не пройдена (не совпадает пара логин/пароль, пользователя не существует или же пользователь заблокирован/удален);

Примеры

Примеры для работы с API:

sample_order1.php — простой вариант формы заказа;
sample_order2.php — расширенный вариант формы заказа;
sample_whois.php — пример получения информации о доступности домена.
sample_auth.php — пример формы входа в Панель управления.