Документация:Интеграция

Ключевые слова: api, удалённая регистрация, авторизация

Под интеграцией в данной статье мы понимаем процесс объединения информационной биллинговой системы JBs с использованием внешних веб-интерфейсов со сторонними информационными системами.

Описание интерфейса

Удалённый вызов функций системы JBs осуществляется с использованием протокола HTTP. Передача параметров может осуществляться как через GET так и через POST запросы. Обязательным для передачи всегда является параметр XMLHttpRequest=yes.

Ответы системы представлены в виде объектов формата JSON. Общий вид ответа выглядит следующим образом:

{Status:('Error','Exception','Ok'),Name1:Value1,Name2:Value2...}

Свойство Status присутствует во всех ответах системы и может принимать одно из трех указанных значений.

Виды ответа на запрос

• Если в процессе обработки запроса произошла ошибка (нет доступа к базе данных, ошибка работы с файловой системой и т.д.) - ответ системы будет выглядеть следующим образом:

{Status:'Error',Error:{CodeID:500,String:'Критическая ошибка'}}

• В случае, если в процессе обработки запроса произошло "исключение" (не верный формат входных данных, объект не найден в базе данных и т.д.) - ответ системы будет выглядеть как:

{Status:'Exception',Exception:{CodeID:'EXCEPTION_CODE',String:'Произошло исключение'}}

Исключение "ожидаемо", т.е. система уже была готова к тому что такая ситуация может произойти и среагировать на нее. Это отличает "исключения" от "ошибок". Каждый вызываемый модуль имеет свои исключения.

• Если системе успешно удалось обработать входящий запрос ответ будет следующим:

{Status:'Ok',Name1:Value1,Name2:Value2,...}

Ответ может содержать любые данные выдаваемые модулем.

Типы входных значений

• Число, строка передаются в стандартном виде:

http://domain/Module?String=hello&Number=100

• Массив - множество данных, передается в виде пар-значений:

http://domain/Module?Array[]=first&Array[]=second

Таким образом, массив Array состоит из 2х элементов [first,second]

Для удаленного вызова функций Вы в начале должны пройти авторизацию.

Авторизация в системе

Авторизация - совокупность двух этапов: идентификации и авторизации. Идентификация в системе JBs происходит с использованием электронного адреса и пароля пользователя.

Имя модуля	/API/Logon
Параметры
Email	Электронный адрес пользователя	Строка
Password	Пароль пользователя	Строка

В случае успешного выполнения ответ будет выглядеть как:

{Status:'Ok',SessionID:'SESSION48e65f5de64e3',Home:'/Home'}

• SessionID - уникальный идентификатор сессии выданный системой, может быть в последующем передаваться системе для выполнения многократных запросов.
• Home - адрес домашней страницы пользователя. По умолчанию для всех клиентов устанавливается как /Home, для администраторов /Administrator/Home.

После успешной удаленной авторизации на вашем сайте, Вы можете перенаправить пользователя в систему:

Location: http(s)://domain{Home}?SessionID={SessionID}

Пример сценария авторизации на языке PHP:

<?php
#-------------------------------------------------------------------------------
$Email    = 'admin@company.com';
$Password = 'default';
#-------------------------------------------------------------------------------
$Request = SPrintF('http://joonte.com/API/Logon?XMLHttpRequest=yes&Email=%s&Password=%s',$Email,$Password);
#-------------------------------------------------------------------------------
$Answer = @File_Get_Contents($Request);
if(!$Answer)
  Exit('Request error');
#-------------------------------------------------------------------------------
$Answer = @JSON_Decode($Answer,TRUE);
if(!$Answer)
  Exit('Bad answer');
#-------------------------------------------------------------------------------
switch($Answer['Status']){
  case 'Error':
    #---------------------------------------------------------------------------
    $Error = $Answer['Error'];
    #---------------------------------------------------------------------------
    Exit($Error['String']);
  case 'Exception':
    #---------------------------------------------------------------------------
    $Exception = $Answer['Exception'];
    #---------------------------------------------------------------------------
    Exit($Exception['String']);
  case 'Ok':
    #---------------------------------------------------------------------------
    Header(SPrintF('Location: http://joonte.com%s?SessionID=%s',$Answer['Home'],$Answer['SessionID']));
    #---------------------------------------------------------------------------
    Exit;
  default:
    Exit('Wrong status');
}
#-------------------------------------------------------------------------------
?>

Регистрация пользователя

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

Имя модуля	/API/UserRegister
Параметры
Email	Электронный адрес пользователя	Строка
Password	Будущий пароль пользователя	Строка
Name	Имя пользователя	Строка

В случае успешного выполнения ответ будет выглядеть как:

{Status:'Ok',SessionID:'SESSION48e65f5de64e3',Home:'/Home',ContractID:1000,UserID:1000}

• SessionID - уникальный идентификатор сессии выданный системой, может быть в последующем передаваться системе для выполнения многократных запросов.
• Home - адрес домашней страницы пользователя. По умолчанию для всех клиентов устанавливается как /Home.
• ContractID - идентификатор договора по умолчанию. Может использоваться в дальнейших запросах.
• UserID - идентификатор пользователя. Может использоваться в дальнейших запросах.

Запрос информации из БД

Для доступа к модулю требуется авторизация одного из администраторов.

Имя модуля	/Administrator/API/SelectDB
Параметры
TableID	Имя таблицы в базе данных	Строка
ColumnsID	Список полей	Массив
Conditions	Условия выборки	Массив

Пример, вывод новостей из базы данных:

http://domain/Module?TableID=Clauses&ColumnsIDs[]=Title&ColumnsIDs[]=Text&Conditions[]=Partition=News

В случае успешного выполнения ответ будет выглядеть как:

{Status:'Ok',Rows:{Row1:{},...}}

• Rows - массив записей.

В случае, если данные не найдены ответ будет следующим:

{Status:'Empty'}

Обращение к службе WhoIs

Имя модуля	/API/WhoIs
Параметры
DomainName	Доменное имя	Строка
DomainZone	Имя доменной зоны	Строка

В случае не доступности сервера WhoIs ответ будет выглядеть как:

{Status:'Fail'}

В случае, если домен занят ответ будет выглядеть как:

{Status:'Borrowed',[...]}

• [...] - совокупность дополнительных параметров: именные сервера, дата окончания и т.д.

В случае, если домен свободен ответ будет выглядеть как:

{Status:'Free'}