API3 Накопителя. Протокол SOAP
API доступно по адресу: http://api3.nako-reactor.ru/soap/
WSDL находится здесь: http://api3.nako-reactor.ru/soap/?wsdl
Кодировка по-умолчанию: UTF-8.
На данный момент поддерживаются следующие методы:
- array status(terminal_id, code) - получение статуса терминала.
- array region(terminal_id, code, id) - получение списка дочерних регионов по отношению к указанному.
- array region_path(terminal_id, code, id) - получение пути к указанному региону.
- array category(terminal_id, code, id) - получение списка дочерних категорий по отношению к указанной.
- array category_path(terminal_id, code, id) - получение пути к указанной категории.
- array form(terminal_id, code, category_id, type, detail) - получение элементов формы выбранной категории и типа формы.
- array add(terminal_id, code, category_id, region_id, contact, is_paid, ad_data, ad_files) - добавление объявления.
- array search(terminal_id, code, category_id, region_id, keywords, search_params, only_paid, deep_search, detail, limit, offset, sort) - получение списка объявлений по заданным параметрам поиска.
- integer search_count(terminal_id, code, category_id, region_id, keywords, search_params, only_paid) - получение количества объявлений по заданным параметрам поиска.
- array search_quick(terminal_id, code, region_id, category_id, tag_id, keywords, only_paid, deep_search, detail, limit, offset) - быстрый поиск объявлений по ключевым словам.
- array info(terminal_id, code, id) - получение информации об указанном объявлении.
- boolean promote(terminal_id, code, id) - пометка объявления, как оплаченного.
Общая схема ответа сервера
Ответ от сервера возвращается либо в логическом типе либо в виде массива (часто содержащего вложенные массивы).
В случае серверной ошибки или при отправке неправильных данных возвращается SoapFault.
Экономия трафика
В целях экономии трафика поддерживается GZIP-сжатие SOAP-ответов. Для включения сжатия при создании SOAP-клиента необходимо указать HTTP-заголовок "Accept-Encoding: gzip". В PHP это делается так:
$client = new SoapClient($wsdl, array( 'compression' => SOAP_COMPRESSION_ACCEPT | SOAP_COMPRESSION_GZIP ) );
Готовый PHP-класс для работы с API
Чтобы вам не приходилось каждый раз заново писать класс для работы с API, мы предоставляем вам в общее пользование наш класс. Помимо основных функций, в нем есть еще и пара дополнительных, которые здорово облегчат вам жизнь.
Язык — PHP. Смотреть исходный код.
Подробное описание команд
В этом разделе параметры, отмеченные звездочкой (*) обязательны.
array status(terminal_id, code)
Возвращает информацию о том:
- Активен ли терминал (может ли он вообще работать с системой). Зависит от того, активны ли терминал и партнер. Если хоть кто-то из них заблокирован, то терминал не активен.
- Может ли терминал добавлять платные объявления. Зависит от активности терминала, способа оплаты и баланса. Если партнер работает по факту и терминал активен, то возможность имеется. Если партнер работает в кредит и терминал активен, то возможность имеется. Если партнер работает по предоплате и на счету еще есть предоплаченные объявления, то возможность имеется.
- Может ли терминал добавлять бесплатные объявления. Зависит от активности терминала и способа оплаты партнера. Если партнер работает в кредит или по факту, то возможность запрещена. Может быть разрешена в исключительных случаях.
- Может ли терминал искать бесплатные объявления. Зависит от активности терминала и способа оплаты партнера. Если партнер работает в кредит или по факту, то возможность запрещена. Может быть разрешена в исключительных случаях.
Входящие данные
- * integer terminal_id - идентификатор терминала. Не меньше 1.
- * string code - код доступа к терминалу.
Возвращаемые данные
Данные возвращаются в виде обычного массива со строковыми ключами.
array(
is_active => (boolean)[Флаг активности терминала],
allow_add_paid => (boolean)[Можно добавлять платные объявления],
allow_search_free => (boolean)[Можно искать бесплатные объявления],
allow_add_free => (boolean)[Можно добавлять бесплатные объявления]
);
array region(terminal_id, code, id)
Команда получает идентификатор региона и возвращает объект-массив записей о дочерних регионах.
Если дочерних регионов не было, то возвращается пустой объект-массив.
Входящие данные
- * integer terminal_id - идентификатор терминала. Не меньше 1.
- * string code - код доступа к терминалу.
- * integer id - идентификатор региона. Не меньше 1.
Возвращаемые данные
array(
parent => (array)[Текущий регион и информация о нем],
elements => (array)[Массив дочерних регионов]
);
Каждый элемент региона из массива elements, а также сам элемент parent представляют собой массив информации о регионе:
array(
id => (integer)[Идентификатор региона],
path => (string)[Путь к региону],
title => (string)[Название региона],
depth => (integer)[Глубина региона],
is_popular => (boolean)[Отмеченный,популярный]
);
Вам, скорее всего, потребуются только три свойства - id, title и is_popular.
Свойство is_popular означает, что регион выносится в начало списка. Например, города федерального значения. Или столица региона.
array region_path(terminal_id, code, id)
Команда получает идентификатор региона и возвращает цепочку регионов от корня до указанного.
Если указан неправильный идентификатор региона, то возвращается ошибка.
Входящие данные
- * integer terminal_id - идентификатор терминала. Не меньше 1.
- * string code - код доступа к терминалу.
- * integer id - идентификатор региона. Не меньше 1.
Возвращаемые данные
array(
current => (array)[Указанный регион],
path => (array)[Массив дочерних регионов]
);
Каждый элемент региона из массива path, а также и объект current представляет собой следующую структуру:
array(
id => (integer)[Идентификатор региона],
path => (string)[Путь к региону],
title => (string)[Название региона],
depth => (integer)[Глубина региона],
is_popular => (boolean)[Отмеченный,популярный]
);
Вам, скорее всего, потребуются только два свойства - id и title.
array category(terminal_id, code, id)
Команда получает идентификатор категории и возвращает массив записей о дочерних категориях.
Если дочерних категорий не было, то возвращается пустой массив.
Входящие данные
- * integer terminal_id - идентификатор терминала. Не меньше 1.
- * string code - код доступа к терминалу.
- * integer id - идентификатор категории. Не меньше 1.
Возвращаемые данные
array(
parent => (array)[Текущая категория и информация о ней],
elements => (array)[Массив дочерних категорий]
);
Каждый элемент категории из массива elements, а также сам элемент parent представляют собой массив информации о категории:
array(
id => (integer)[Идентификатор категории],
path => (string)[Путь к категории],
title => (string)[Название категории],
depth => (integer)[Глубина категории]
);
Вам, скорее всего, потребуются только два свойства - id и title.
array category_path(terminal_id, code, id)
Команда получает идентификатор категории и возвращает цепочку категорий от корня до указанной.
Если указан неправильный идентификатор категории, то возвращается ошибка.
Входящие данные
- * integer terminal_id - идентификатор терминала. Не меньше 1.
- * string code - код доступа к терминалу.
- * integer id - идентификатор категории. Не меньше 1.
Возвращаемые данные
array(
current => (array)[Указанная категория],
path => (array)[Массив дочерних категорий]
);
Каждый элемент категории из массива path, а также и объект current представляет собой следующую структуру:
array(
id => (integer)[Идентификатор категории],
path => (string)[Путь к категории],
title => (string)[Название категории],
depth => (integer)[Глубина категории]
);
Вам, скорее всего, потребуются только два свойства - id и title.
array form(terminal_id, code, category_id, type, detail)
Команда получает идентификатор категории, тип требуемой формы и уровень детализации и возвращает массив элементов формы со специфичными параметрами для каждого элемента (в зависимости от типа данных элемента).
Если для указанной категории не заведена форма, то ищется форма категории уровнем выше и так до тех пор, пока не найдется категория, у которой есть форма (в крайнем случае корневая категория - у нее точно есть форма).
Входящие данные
- * integer terminal_id - идентификатор терминала. Не меньше 1.
- * string code - код доступа к терминалу.
- * integer id - идентификатор категории. Не меньше 1.
- * string type - тип формы. Возможные варианты: add, search, edit.
- integer detail - уровень детализации формы. Возможные варианты: 1, 2, 3. По-умолчанию: 2.
Возвращаемые данные
Возвращается массив, содержащий вложенный массив, описывающий поле формы. Каждый элемент возвращенного массива - это одно из полей формы.
array(
(array)[Поле 1],
(array)[Поле 2],
(array)[Поле 3],
(array)[Поле 4],
(array)[Поле 5],
...
);
Каждый возвращаемый элемент (атрибут) имеет набор свойств. В зависимости от типа данных атрибута, полезными могут оказаться следующие свойства:
Целое число (integer)
array(
attribute => (integer)[Идентификатор атрибута],
is_range => (boolean)[Флаг, что атрибут является интервалом],
solid_size => (integer)[Длина целой части],
unit => (string)[Единица измерения],
title => (string)[Название атрибута],
type => (string)'integer'
)
Дробное число (numeric)
array(
attribute => (integer)[Идентификатор атрибута],
is_range => (boolean)[Флаг, что атрибут является интервалом],
solid_size => (integer)[Длина целой части],
frac_size => (integer)[Длина дробной части],
unit => (string)[Единица измерения],
title => (string)[Название атрибута],
type => (string)'numeric'
)
Текст (text)
array(
attribute => (integer)[Идентификатор атрибута],
max_text_length => (integer)[Максимальная длина текста],
is_textarea => (boolean)[Флаг, что следует отображать в виде TEXTAREA],
title => (string)[Название атрибута],
type => (string)'text'
)
Дата (date)
array(
attribute => (integer)[Идентификатор атрибута],
is_range => (boolean)[Флаг, что атрибут является интервалом],
title => (string)[Название атрибута],
type => (string)'date'
)
Логический (boolean)
array(
attribute => (integer)[Идентификатор атрибута],
title => (string)[Название атрибута],
type => (string)'boolean'
)
Список (list)
array(
attribute => (integer)[Идентификатор атрибута],
is_multiselect => (boolean)[Флаг, что атрибут является интервалом],
title => (string)[Название атрибута],
type => (string)'list',
elements => (array)[Список вариантов значений спискового атрибута]
}
В объекте elements содержится список вариантов значения для выпадающего списка. Каждый элемент вариантов значений спискового атрибута состоит из следующих полей:
array(
label => (string)[Название элемента],
value => (integer)[Значение элемента],
is_popular => (boolean)[Отмеченный]
)
Внимание: при отрисовке поля формы <SELECT> необходимо указывать имя поля с квадратными скобками (массив) - data-32[].
Поле is_popular означает, что это свойство специально выносится в начало списка. Например, самые популярные производители из всего числа производителей.
Описание свойств
is_range - означает, что элемент формы представляет собой интервал из минимального и максимального значений. Поэтому, в случае, если is_range равен true, необходимо отрисовывать не одно поле формы, а два. С именами data-NN-min и data-NN-max, где NN - идентификатор атрибута. Может использоваться в атрибутах типа integer, numeric, date.
solid_size - означает максимальную длину целой части значения. Например, атрибут Год может быть длиной не больше 4 символов. Если значение не указано либо равно 0, то проверять длину целой части не нужно. В интерфейсе желательно проводить проверку. Но в любом случае проверка выполняется также и в API и лишние символы обрезаются. Может использоваться в атрибутах типа integer, numeric.
frac_size - означает максимальную длину дробной части значения. Например, дробная часть атрибута Цена может быть длиной не больше 2 символов (копейки). Если значение не указано либо равно 0, то проверять длину дробной части не нужно. В интерфейсе желательно проводить проверку. Но в любом случае проверка выполняется также и в API и лишние символы обрезаются. Может использоваться в атрибутах типа integer, numeric.
max_text_length - максимальная длина текстового поля. Если не указана, то длина текста не ограничена. По этому параметру можно также определять и атрибут size тега <input>, чтобы для текстовых строк с максимальной длиной в 5 символов не выводить текстовое поле длиной 60 символов. Но, если максимальная длина указана как 500 символов, то не устанавливайте атрибут size="500". Может использоваться в атрибутах типа text.
is_multiselect - означает, что в выпадающем списке можно выбрать несколько значений, удерживая при щелчке по элементам клавишу CTRL. Соответственно, не забывайте о том, чтобы для тега <select> в этом случае нужно установить атрибут multiple, который позволяет выбирать несколько элементов, а также атрибут size="N", который меняет вид выпадающего списка, делая его не однострочным, а в несколько строк. К примеру, для N можно выбрать значение 5. Может использоваться в атрибутах типа list.
array add(terminal_id, code, category_id, region_id, contact, is_paid, ad_data, ad_files)
Команда получает данные и добавляет их в базу данных. Возвращает идентификатор объявления и код доступа к нему.
Входящие данные
- * integer terminal_id - идентификатор терминала. Не меньше 1.
- * string code - код доступа к терминалу.
- * integer category_id - идентификатор категории. Не меньше 1.
- * integer region_id - идентификатор региона. Не меньше 1.
- * string contact - контактная информация (максимум 150 символов).
- * boolean is_paid - флаг "оплаченное объявление" (для партнеров, работающих в кредит или по предоплате).
- * array ad_data - значения полей формы для добавления в массиве с текстовыми ключами в формате data-XX[-min|-max]. XX - номер атрибута из формы. Поля могут иметь следующие имена: data-XX-min (для минимального значения), data-XX-max (для максимального значения), data-XX (для единичного значения).
- * array ad_files - массив файлов. Каждый элемент массива описывает один файл. Элемент состоит из двух ключей: 'content-type' и 'content'. Поле 'content-type' не обязательно. В поле 'content' находится содержимое файла с изображением в формате base64 (т.е. зашифровано). Поддерживаемые типы файлов на данный момент: jpg, gif, png. Максимальное число загружаемых файлов — 10.
Возвращаемые данные
array(
id => (integer)[Идентификатор объявления],
code => (string)[Код объявления]
)
array search(terminal_id, code, category_id, region_id, keywords, search_params, only_paid, deep_search, detail, limit, offset, sort)
Команда получает данные для поиска и возвращает результат поиска объявлений. Если успешно, возвращается список найденных объявлений в виде текстовых записей.
Входящие данные
- * integer terminal_id - идентификатор терминала. Не меньше 1.
- * string code - код доступа к терминалу.
- * integer category_id - идентификатор категории. Не меньше 1.
- * integer region_id - идентификатор региона. Не меньше 1.
- * string keywords - ключевые слова (не используется).
- * array search_params - значения полей формы для добавления с текстовыми индексами в формате data-XX[-min|-max]. XX - номер атрибута из формы. Поля могут иметь следующие имена: data-XX-min (для минимального значения), data-XX-max (для максимального значения), data-XX (для единичного значения).
- * boolean only_paid - искать только оплаченные объявления.
- * boolean deep_search - Флаг того, что искать нужно не только в указанной категории, но и во всех дочерних категориях. Если установлено в 1, то ищет во всех дочерних категориях. Внимание: при использовании данной функции при расширенном поиске (при заполненой форме с параметрами) качество результата не гарантируется, т.к. для каждой категории существует свой набор поисковых атрибутов и они могут не пересекаться.
- * boolean detail - вместо сокращенной формы объявлений возвращать их в полной форме (как результат функции info(...)). В этом случае максимальное количество возвращаемых объявлений не превышает 20.
- * integer limit - количество возвращаемых объявлений. 1..100
- * integer offset - смещение в результатах поиска. 0..
- * array sort - массив вариантов сортировки результатов поиска. Должен передаваться одномерный массив со строковым значением: array('price') или array('date'). По-умолчанию сортировка по дате.
Возвращаемые данные
array(
(array)[Объявление],
(array)[Объявление],
(array)[Объявление],
(array)[Объявление],
(array)[Объявление],
(array)[Объявление],
...
)
Структура отдельного объекта объявления:
array(
id => (integer)[Идентификатор объявления],
text => (string)[Текст объявления (параметры)],
text_region => (string)[Текстовое представление региона],
text_category => (string)[Текстовое представление категории],
contact => (string)[Контактная информация],
date => (string)[Дата создания в формате YYYY-MM-DD HH:MM:SS.MS],
is_free => (boolean)[Флаг "Бесплатное объявление"]
)
integer search_count(terminal_id, code, category_id, region_id, keywords, search_params, only_paid, deep_search)
Команда получает данные для поиска и возвращает количество объявлений, которое подходит под указанные параметры.
Входящие данные
- * integer terminal_id - идентификатор терминала. Не меньше 1.
- * string code - код доступа к терминалу.
- * integer category_id - идентификатор категории. Не меньше 1.
- * integer region_id - идентификатор региона. Не меньше 1.
- * string keywords - ключевые слова (не используется).
- * array search_params - значения полей формы для добавления с текстовыми индексами в формате data-XX[-min|-max]. XX - номер атрибута из формы. Поля могут иметь следующие имена: data-XX-min (для минимального значения), data-XX-max (для максимального значения), data-XX (для единичного значения).
- * boolean only_paid - искать только оплаченные объявления.
- * boolean deep_search - Флаг того, что искать нужно не только в указанной категории, но и во всех дочерних категориях. Если установлено в 1, то ищет во всех дочерних категориях. Внимание: при использовании данной функции при расширенном поиске (при заполненой форме с параметрами) качество результата не гарантируется, т.к. для каждой категории существует свой набор поисковых атрибутов и они могут не пересекаться.
Возвращаемые данные
(integer)
array search_quick(terminal_id, code, region_id, category_id, tag_id, keywords, only_paid, deep_search, detail, limit, offset)
Команда получает данные для поиска и возвращает результат поиска объявлений. Если успешно, возвращается список найденных объявлений в виде текстовых записей.
Входящие данные
- * integer terminal_id - идентификатор терминала. Не меньше 1.
- * string code - код доступа к терминалу.
- * integer region_id - идентификатор региона.
- * integer category_id - идентификатор категории.
- * integer tag_id - идентификатор тега.
- * string keywords - контактная информация.
- * boolean only_paid - искать только оплаченные объявления.
- * boolean deep_search - Флаг того, что искать нужно не только в указанной категории, но и во всех дочерних категориях. Если установлено в 1, то ищет во всех дочерних категориях. Внимание: при использовании данной функции при расширенном поиске (при заполненой форме с параметрами) качество результата не гарантируется, т.к. для каждой категории существует свой набор поисковых атрибутов и они могут не пересекаться.
- * boolean detail - вместо сокращенной формы объявлений возвращать их в полной форме (как результат функции info(...)). В этом случае максимальное количество возвращаемых объявлений не превышает 20.
- * integer limit - количество возвращаемых объявлений. 1..100
- * integer offset - смещение в результатах поиска. 0..
Теги
Теги представляют из себя метки для категорий, которые могут объединять категории по типу.
Существующие метки:
- куплю (значение 1)
- продаю (значение 2)
- сниму (значение 3)
- сдам (значение 4)
- требуется (значение 5)
- ищу работу (значение 6)
- отдам (значение 7)
Используя теги можно производить быстрый поиск по нескольким категориям.
Возвращаемые данные
array( 'total' => (integer)[Общее количество найденных объявлений], 'elements' => array( (array)[Объявление], (array)[Объявление], (array)[Объявление], (array)[Объявление], (array)[Объявление], (array)[Объявление], ... ) )
Структура отдельного объекта объявления:
array(
id => (integer)[Идентификатор объявления],
text => (string)[Текст объявления (параметры)],
is_free => (boolean)[Флаг "Бесплатное объявление"]
)
При установке флага detail в значение 1 объявления будут возвращаться в таком же формате, в каком их возвращает функция info(...).
array info(terminal_id, code, id)
Команда получает идентификатор объявления и возвращает массив информации об указанном объявлении.
Если объявление имеет статус бесплатного, а партнеру запрещен доступ к бесплатным данным (большинство партнеров, работающих в оффлайне в кредит или по предоплате), то возвращается ошибка.
Входящие данные
- * integer terminal_id - идентификатор терминала. Не меньше 1.
- * string code - код доступа к терминалу.
- * integer id - идентификатор объявления. Не меньше 1.
Возвращаемые данные
array(
id => (integer)[Идентификатор объявления],
region => (integer)[Идентификатор региона],
text_region => (string)[Название региона],
category => (integer)[Идентификатор категории],
text_category => (string)[Название категории],
text => (string)[Текст объявления],
contact => (string)[Контактная информация],
date => (string)[Дата создания в формате YYYY-MM-DD HH:MM:SS.MS],
is_free => (boolean)[Флаг бесплатного объявления],
attributes => (array)[Массив атрибутов объявления],
files => (array)[Массив файлов объявления]
)
Массив атрибутов
Массив атрибутов состоит из элементов (далее "атрибутов"), каждый из которых также является массивом.
array(
(array)[Атрибут],
(array)[Атрибут],
(array)[Атрибут],
(array)[Атрибут]
...
)
Каждый атрибут содержит информацию, в зависимости от типа данных атрибута:
Целое число (integer)
array(
attribute => (integer)[Идентификатор атрибута в системе],
is_range => (boolean)[Флаг, что атрибут является интервалом],
solid_size => (integer)[Длина целой части],
unit => (string)[Единица измерения],
title => (string)[Название атрибута],
type => (string)'integer',
value => (integer|array)[Значение атрибута]
)
Значение атрибута может быть объектом, если атрибут имеет свойство is_range. В таком случае оно будет состоять из двух элементов:
array(
min => (integer)[Минимальное значение],
max => (integer)[Максимальное значение]
)
Дробное число (numeric)
array(
attribute => (integer)[Идентификатор атрибута в системе],
is_range => (boolean)[Флаг, что атрибут является интервалом],
solid_size => (integer)[Длина целой части],
frac_size => (integer)[Длина дробной части],
unit => (string)[Единица измерения],
title => (string)[Название атрибута],
type => (string)'numeric',
value => (integer|array)[Значение атрибута]
)
Значение атрибута может быть объектом, если атрибут имеет свойство is_range. В таком случае оно будет состоять из двух элементов:
array(
min => (float)[Минимальное значение],
max => (float)[Максимальное значение]
)
Текст (text)
array(
attribute => (integer)[Идентификатор атрибута в системе],
max_text_length => (integer)[Максимальная длина текста],
title => (string)[Название атрибута],
type => (string)'text',
value => (string)[Значение атрибута]
)
Дата (date)
array(
attribute => (integer)[Идентификатор атрибута в системе],
is_range => (boolean)[Флаг, что атрибут является интервалом],
title => (string)[Название атрибута],
type => (string)'date',
value => (string|array)[Значение атрибута]
)
Значение атрибута может быть объектом, если атрибут имеет свойство is_range. В таком случае оно будет состоять из двух элементов:
array(
min => (string)[Минимальное значение],
max => (string)[Максимальное значение]
)
Логический
array(
attribute => (integer)[Идентификатор атрибута в системе],
title => (string)[Название атрибута],
type => (string)'boolean',
value => (boolean)[Значение атрибута]
)
Список
array(
attribute => (integer)[Идентификатор атрибута в системе],
is_multiselect => (boolean)[Флаг мультивыбора],
title => (string)[Название атрибута],
type => (string)'list',
value => (array)[Массив значений атрибута]
)
Каждый элемент вариантов значений спискового атрибута состоит из следующих полей:
array(
label => (string)[Название элемента],
value => (integer)[Значение элемента]
)
Массив файлов
Массив файлов состоит из элементов, каждый из которых также является массивом.
array(
(array)[Файл],
(array)[Файл],
...
)
Каждый элемент файла содержит в свою очередь массив информации о файле:
array(
type => (string)[MIME-тип файла],
path => (string)[URL файла]
)
MIME-тип может быть как image/jpeg, image/png, image/gif, так в будущем могут быть и другие типы.
URL файла, это поле, содержащее полный путь к файлу.
boolean promote(terminal_id, code, id)
Команда получает идентификатор объявления и отмечает его оплаченным. При этом в зависимости от способа оплаты партнера выполняет соответствующие действия.
Выполняемые действия в зависимости от способа оплаты:
- По факту - исполнение команды запрещено.
- В кредит - меняется счет партнера (увеличивается его задолженность).
- Предоплата - если у партнера еще есть на счету предоплаченные объявления, то счет уменьшается на 1. Если нет, то возвращается ошибка.
Входящие данные
- * integer terminal_id - идентификатор терминала. Не меньше 1.
- * string code - код доступа к терминалу.
- * integer id - идентификатор объявления. Не меньше 1.
Возвращаемые данные
В случае успеха возвращается true.