====== Описание взаимодействия через XHR ======


===== Выполнение запросов =====
  - Запрос осуществляется может осуществляться как методом FormData //(Content-type: application/x-www-form-urlencoded)//, так и Payload //(Content-type: application/json)//
  - URL для обработки запросов //**имя сайта**/?option=com_wmartalpha&task=api.**methodName**//
  - Первоначальное получение токена выполняется методом [[xhr_api#init|api.init]]
  - CSRF-токен должен передаваться клиентом в заголовке //csrf-token//, либо в параметре //csrfToken// тела запроса. [[xhr_api#Пример взаимодействия|Пример]]
  - Ответ возвращается в формате JSON
=== Общие структурные элементы ===
|ok|Флаг успешности выполнения запроса|int|
|errors|Запись со списком ошибок запроса|[]|

<code javascript>
  {
    ok: int,
    errors: [
      {
        error: string,
        type: string
      },
      ...
    ],
    ...
  }
</code>

=== Общие ошибки ===
|core|csrfError|CSRF токен не передан или передан неверный токен|
|core|tooManyRequests|Обнаружен флуд запросами. Данный ip адрес временно заблокирован. Поле //delay// указывает время, оставшееся до конца блокировки|
|core|forbidden|Данная операция запрещена для данного пользователя|


====== Инициализация =======

===== init =====

//имя сайта///?option=com_wmartalpha&task=api.**init**

Инициализация сессии, получение токена

=== Результат  ===
|csrfToken|csrf токен|string|


====== Авторизация =======

===== login =====

//имя сайта///?option=com_wmartalpha&task=api.**login**

Авторизация пользователя

=== Запрос  ===
|login|Логин(email или номер телефона в 11-значном формате)|string обязательный|
|password|Пароль|string обязательный|
|remember|Запомнить пользователя|bool|

=== Результат  ===
|user|Основные данные пользователя|[[xhr_api#user|объект User]]|

=== Ошибки  ===
|login|incorrect|Формат логина указан неверно|
|login|unregistred|Пользователь с таким логином не зарегистрирован|
|password|wrong|Указан неверный пароль|

===== loginOAuth =====

//имя сайта///?option=com_wmartalpha&task=api.**loginOAuth**

Регистрация/авторизация в сторонних сервисах по протоколу OAuth. Результат данного запроса должен собран и отправлен от имени пользователя.

=== Запрос  ===
|service|Тип сервиса|Поддерживаемые типы: fb, google, vk, instagram, mailru, ok, vk,yandex|
|redirectUrl|url переадресации после авторизации|string|

=== Результат  ===
|OAuthrequest|Объект, описывающий запрос|[[xhr_api#user|объект OAuthrequest]]|


=== Ошибки  ===
|service|wrong|Сервис не существует или не подключен к системе|



===== logout =====

//имя сайта///?option=com_wmartalpha&task=api.**logout**

Завершение сессии пользователя

====== Регистрация ======
===== recover =====

//имя сайта///?option=com_wmartalpha&task=api.**recover**

Восстановление пароля пользователя. Перед процедурой регистрации необходимо запросить код подтверждения методом [[xhr_api#registerCheck|api.recoverCheck]]

=== Запрос  ===
|login|Логин(email или номер телефона в 11-значном формате)|string обязательный|
|password|пароль|string обязательный|
|passwordConfirm|подтверждение пароля|string обязательный|
|code|код подтверждения из email или sms|string обязательный|

=== Результат  ===
|user|Основные данные пользователя|[[xhr_api#user|объект User]]|

=== Ошибки  ===
|login|incorrect|Логин указан неверно|
|login|unregistered|Данный логин не зарегистрирован|
|password|incorrect|Пароль указан некорректно|
|passwordConfirm|incorrect|Подтверждение пароля указано некорректно|
|passwordConfirm|unmatch|Пароли не совпадают|
|code|wrong|Некорректный код подтверждения|
|code|outdated|Код подтверждения устарел, необходимо перезапросить|


===== recoverCheck =====

//имя сайта///?option=com_wmartalpha&task=api.**recoverCheck**

Получение кода подтверждения для регистрации.

=== Запрос  ===
|login|Логин(email или номер телефона в 11-значном формате)|string обязательный|

=== Результат  ===
|delay|время, оставшееся до возможности запроса следующего кода подтверждения|float|

=== Ошибки  ===
|login|incorrect|Логин указан неверно|
|login|unregistered|Данный логин не зарегистрирован|
|login|wait|Необходимо подождать, прежде чем запрашивать код подтверждения снова|



===== register =====

//имя сайта///?option=com_wmartalpha&task=api.**register**

Регистрация пользователя. Перед процедурой регистрации необходимо запросить код регистрации методом [[xhr_api#registerCheck|api.registerCheck]]

=== Запрос  ===
|login|Логин(email или номер телефона в 11-значном формате)|string обязательный|
|password|пароль|string обязательный|
|passwordConfirm|подтверждение пароля|string обязательный|
|firstname|имя пользователя|string обязательный|
|lastname|фамилия пользователя|string обязательный|
|agree|согласие на обработку персональных данных|bool обязательный|
|code|код подтверждения из email или sms|string обязательный|

=== Результат  ===
|user|Основные данные пользователя|[[xhr_api#user|объект User]]|


=== Ошибки  ===
|login|incorrect|Логин указан неверно|
|login|registered|Данный логин уже зарегистрирован|
|agree|incorrect|Необходимо подтвердить обработку персональных данных|
|password|incorrect|Пароль указан некорректно|
|passwordConfirm|incorrect|Подтверждение пароля указано некорректно|
|passwordConfirm|unmatch|Пароли не совпадают|
|firstname|incorrect|Имя указано некорректно|
|lastname|incorrect|Фамилия указана некорректно|
|code|wrong|Некорректный код подтверждения|
|code|outdated|Код подтверждения устарел, необходимо перезапросить|

===== registerCheck =====

//имя сайта///?option=com_wmartalpha&task=api.**registerCheck**

Получение кода подтверждения для регистрации.

=== Запрос  ===
|login|Логин(email или номер телефона в 11-значном формате)|string обязательный|

=== Результат  ===
|delay|время, оставшееся до возможности запроса следующего кода подтверждения|float|

=== Ошибки  ===
|login|incorrect|Логин указан неверно|
|login|registered|Данный логин уже зарегистрирован|
|login|wait|Необходимо подождать, прежде чем запрашивать код подтверждения снова|



====== Управление аккаунтом =======
===== passwordChange =====

//имя сайта///?option=com_wmartalpha&task=api.**passwordChange**

Изменение пароля пользователя

=== Запрос  ===
|password|старый пароль|string|
|passwordNew|новый пароль|string|
|passwordNewConfirm|подтверждение пароля|string|

=== Ошибки  ===
|password|wrong|Указан неверный пароль|
|passwordNew|incorrect|Пароль указан некорректно|
|passwordNewConfirm|incorrect|Подтверждение пароля указано некорректно|
|passwordNewConfirm|unmatch|Пароли не совпадают|
|lastname|incorrect|Фамилия указана некорректно|
|code|wrong|Некорректный код подтверждения|
|code|outdated|Код подтверждения устарел, необходимо перезапросить|

===== profileChange =====

//имя сайта///?option=com_wmartalpha&task=api.**profileChange**

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

=== Запрос  ===
|firstname|имя пользователя|string|
|lastname|фамилия пользователя|string|
|sex|пол, 1 - мужской, 2 - женский|int|
|subjects|тематика|[string,string, ...]|
|description|Описание|?string|
|orgINN|ИНН организации|?string|
|country|Страна|?string|
|region|Регион|?string|
|locality|Населенный пункт|?string|

=== Ошибки  ===
|firstname|incorrect|Имя указано некорректно|
|lastname|incorrect|Фамилия указана некорректно|
|sex|incorrect|Пол указан некорректно|
|subjects|incorrect|Тематика указана некорректно|
|description|incorrect|Описание указано некорректно|
|orgINN|incorrect|ИНН организации указан некорректно|
|country|incorrect|Страна указана некорректно|
|region|incorrect|Регион указан некорректно|
|locality|incorrect|Населенный пункт указан некорректно|

=== Результат  ===
|user|Основные данные пользователя|[[xhr_api#user|объект User]]|


====== Системные функции ======
===== reference =====

//имя сайта///?option=com_wmartalpha&task=api.**reference**

Получить значения из справочника

=== Запрос  ===
|reference|Алиас справочника (доступны: subjects,country,region,locality)|string|
|parentId|id родительского значения из связанного справочника (например: отношение населенных пунктов к региону)|?int|
|start|Отступ выбираемых элементов|?int|
|limit|Количество выбираемых элементов|?int|
|search|Строка для поиска|?string|


=== Результат  ===
|values|Массив элементов справочника|[{id:int,value:string},{id:int,value:string}, ...]|
|values.id|id элемента|int|
|values.value|значение элемента|string|

=== Ошибки  ===
|reference|incorrect|Справочник не существует|

====== Пользователи ======

===== usersFilter =====

//имя сайта///?option=com_wmartalpha&task=api.**usersFilter**

Получить свойства и значения для фильтрации

=== Запрос  ===
|filterQuery|Запрос свойств|Массив объектов [[xhr_api#filterQuery|filterQuery]]|
|?listQuery|Запрос элементов|объект [[xhr_api#listQuery|listQuery]]|

=== Результат  ===
|props|Cвойствa и значения|Массив объектов [[xhr_api#props|props]]|

=== Ошибки  ===
|property|incorrect|Свойство не существует|

===== userinfo =====

//имя сайта///?option=com_wmartalpha&task=api.**userinfo**

Получение информации о пользователе. Если id не указан, возвращается информация о текущем пользователе

=== Запрос  ===
|?id|id пользователя|int|

=== Результат  ===
|user|Основные данные пользователя|[[xhr_api#user|объект User]]|

=== Ошибки  ===
|user|incorrect|Пользователь не существует|




===== usersList =====

//имя сайта///?option=com_wmartalpha&task=api.**usersList**

Получить свойства и значения для фильтрации

=== Запрос  ===
|listQuery|Запрос элементов|объект [[xhr_api#listQuery|listQuery]]|

=== Результат  ===
|users|Выбранные пользователи|Массив объектов [[xhr_api#user]]|

=== Ошибки  ===
|property|incorrect|Свойство не существует|
====== Описание объектов ======


===== OAuthRequest =====
Объект, описывающий OAuth запрос

|url|url запроса|string|
|method|Метод|string|
|params|Передаваемые переменные|{}|

<code javascript>
  {
    url: string,
    method: string,
    params: {
      param1: value1,
      param2: value2,
      ...
    }
  }
</code>


===== props =====
Запрос свойств

|id|id свойства|int|
|title|Имя свойства|string|
|alias|Алиас свойства|string|
|?count|Количество элементов с данным свойством|int|
|?values|Массив значений свойства|[]|
|values.id|id значения свойства|string|
|values.alias|alias значения свойства|string|
|values.value|Массив значений свойства|string|
|values.?count|Количество элементов с данным значением свойства|int|

<code javascript>
{   
  id: int,
  title: string,
  alias: string,
  ?values: [
    {
      id: int,
      value: string,
      alias: string,
      ?count: int,
    },
    ...
  ]
}
</code>

===== filterQuery =====
Запрос свойств. Планируется, что структура объекта будет общая для всех фильтрующихся элементов.
Для свойства необходимо указать id либо алиас.

|?id|id свойства|int|
|?alias|Алиас свойства|string|
|?count|Подсчет количества элементов по свойству|bool|
|?format|формат значений. Доступно: list. Если не указан - значения свойства не возвращаются |string|

<code javascript>
{   
  ?id: int,
  ?alias: string,
  ?count: bool,
  ?format: string,
}
</code>

===== listQuery =====
Запрос выборки по элементам. Для свойства необходимо указать id или алиас. 

|?props|Массив выбранных свойств|string|
|props ?id|id свойства|string|
|props ?alias|Алиас свойства|string|
|props ?min|min значение для свойств типа число и дата|float/datetime|
|props ?max|max значение для свойств типа число и дата|float/datetime|
|props ?valueId|массив id значений|[]|
|props ?valueAlias|массив алиасов значений|[]|
|props ?search|Строка для поиска по свойству|string|
|?search|Строка для поиска по основным свойствам|string|
|?start|Отступ выбираемых элементов|bool|
|?limit|Количество выбираемых элементов|bool|
|?sort|Порядок сортировки|string|
|?direction|Направление сортировки asc или desc|string|

<code javascript>
{   
  ?props: {
    {
      ?id: int,
      ?alias: string,
      ?min: float/datetime,
      ?max: float/datetime,
      ?search: string,
      ?valueId: [int, ...],
      ?valueAlias: [string, ...],
    }, 
    ...
  }
  ?search: string,
  ?limit: int,
  ?start: int,
  ?sort: string,
  ?direction: string,
}
</code>



===== user =====
Информация о пользователе

|id|id пользователя|int|
|registered|пользователь зарегистрирован|bool|
|login|Проритетный логин|string|
|firstname|Имя|string|
|lastname|Фамилия|string|
|fullname|Полное имя|string|
|sex|Пол (1-мужской, 2 - женский)|int|
|description|Описание|string|
|subjects|Массив объектов свойства-справочника Тематика|[{referenceId: int,value: string}, ...]|
|orgINN|ИНН организации|string|
|orgTitle|Название организации|string|
|country|Объект свойства-справочника страна|{referenceId: int,value: string}|
|region|Объект свойства-справочника регион|{referenceId: int,value: string}|
|locality|Объект свойства-справочника населенный пункт|{referenceId: int,value: string}|
|loginData|Массив данных авторизации пользователя|[]|
|loginData.type|тип логина|string|
|loginData.login|Массив данных авторизации пользователя|string|


<code javascript>
  {
    id: int,
    registered: bool,
    ?login: string,
    ?firstname: string,
    ?lastname: string,
    ?fullname: string,
    ?sex: int,
    ?description: string,
    ?subjects: [
      {
        referenceId: int,
        value: string
      },
      ...
    ],
    ?orgINN: string,
    ?orgTitle: string,
    ?country: {
      referenceId: int,
      value: string
    },
    ?region: {
      referenceId: int,
      value: string
    },
    ?locality: {
      referenceId: int,
      value: string
    },
    loginData: [
      {
        type: string,
        login: string
      },
      ...
    ],
  }
</code>




====== Пример взаимодействия ======
<code javascript>

 function cookieGet(name) {
    var matches = document.cookie.match(new RegExp(
            "(?:^|; )" + name.replace(/([\.$?*|{}\(\)\[\]\\\/\+^])/g, '\\$1') + "=([^;]*)"
            ));
    return matches ? decodeURIComponent(matches[1]) : undefined;
};

function cookieSet(name, value, options) {
    options = options || {};
    var expires = options.expires;

    if (!options.path)
        options.path = '/';

    if (typeof expires == "number" && expires) {
        var d = new Date();
        d.setTime(d.getTime() + expires * 1000);
        expires = options.expires = d;
    }
    if (expires && expires.toUTCString) {
        options.expires = expires.toUTCString();
    }

    value = encodeURIComponent(value);

    var updatedCookie = name + "=" + value;

    for (var propName in options) {
        updatedCookie += "; " + propName;
        var propValue = options[propName];
        if (propValue !== true) {
            updatedCookie += "=" + propValue;
        }
    }
    document.cookie = updatedCookie;
    return true;
}

function request(method,data,func){
    data = JSON.stringify(data); //for Payload
    let csrfToken=cookieGet('csrfToken');
    let xhr = new XMLHttpRequest();
    xhr.open('POST', 'https://fetch.melissa.team/?task=api.'+method);
    xhr.setRequestHeader('csrf-token', csrfToken);
    //xhr.setRequestHeader('Content-type', 'application/x-www-form-urlencoded'); //for FormData
    xhr.setRequestHeader('Content-type', 'application/json;charset=UTF-8'); //for Payload
    xhr.responseType = 'json';
    xhr.withCredentials = true;
    xhr.onload = function() {
      if (xhr.status != 200) {
        console.error('connection error'); 
      } else {
        if(xhr.response.errors){
            if(xhr.response.errors.core==='tooManyRequests'){
                console.error('flood detect. wait ' + xhr.response.data.delay);
                return false;
            }
            if(xhr.response.errors.core==='csrfError'){
                console.error('wrong csrf token');
                return false;
            }
        }
        if(typeof(func)==='function'){
            func(xhr.response);
        }
        if(xhr.response.csrfToken){
            cookieSet('csrf_token', xhr.response.csrfToken);
        }
      }
    };
    xhr.send(data);
}

//Инициализация
request('init');

//Авторизация
request('login',{login:'a1@lct.su', password:'12345'},data=>{ console.log(data) });

//Получение информации о текущем пользователе
request('userinfo','',data=>{ console.log(data) });

</code>