Описание XML-шлюза для работы с объявлениями на сайте Доски.ру

Версия 2.3 от 24.03.2023 г.
Постоянный адрес документа: https://www.doski.ru/xmlinfo.php

Организационное подключение

XML-шлюз для работы с объявлениями предназначен для удобной работы с большим количеством часто обновляемых объявлений. Прежде всего его удобно использовать организациям, например агентствам недвижимости, автосалонам, кадровым агентствам, турфирмам и др. для быстрой публикации своих предложений в интернете. XML-шлюз позволяет в автоматическом режиме, а значит очень быстро и безошибочно, публиковать объявления, изменять их (синхронизировать данные с данными клиента), удалять устаревшие объявления. Для обычного пользователя все те же функции доступны на сайте www.doski.ru через обычный интернет-браузер.

Для того чтобы начать работу с XML-шлюзом необходимо:

1. Получить логин и пароль постоянного клиента, зарегистрировавшись на сайте www.doski.ru
2. Написать нам о том, что Вы хотите работать через наш XML-шлюз. В письме, пожалуйста, укажите Ваш E-mail или ID на нашем сайте, название и профиль деятельности Вашей компании, контактные данные. Мы свяжемся с Вами и оговорим все условия работы через автоматический шлюз. К сожалению, мы не можем сделать наш XML-шлюз открытым для использования всеми, без предварительного изучения клиента, поскольку этот удобный инструмент сразу же начнут использовать спамеры.
3. Реализовать техническое подключение по схеме, описанной ниже. Сделать это не так сложно, как может показаться на первый взгляд. Кроме того, документ описывает все возможности автоматического обмена, а Вы можете использовать только некоторые из них.

Оплата услуги по выгрузке объявлений через XML-шлюз

Поскольку выгрузка объявлений на сайт через XML-шлюз как правило используется только коммерческими организациями, данная услуга платная. Стоимость услуги зависит от объёмов выгрузки объявлений. При подключении в формате сайта Доски.ру плата за период тестирования и первый месяц работы не взимается!

^*При оплате услуг по XML-выгрузке объявлений на длительный срок (от полугода и более) предоставляются дополнительные индивидуальные скидки.

Схема оплаты услуги по выгрузке объявлений следующая. При наличии на счету клиента суммы, соответствующей минимальному тарифу, выгрузка объявлений разрешается. Со счёта клиента списывается сумма, соответствующая минимальному тарифу и объявления выгружаются до достижения разрешённого объёма выгрузки. Если количество выгружаемых объявлений клиента превышает разрешённый объём, проверяется наличие на его счету суммы, соответствующей следующему по объёму тарифу выгрузки (за вычетом уже списанной по предыдущему тарифу). Если сумма на счету клиента позволяет, со счёта списывается недостающая до нового тарифа сумма и выгрузка продолжается. Если суммы на счету клиента недостаточно для перехода на повышенный тариф, то выгрузка останавливается, клиент получает по почте извещение о недостатке средств.

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

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

Деньги списываются со счёта клиента в момент первой (за данный календарный месяц) выгрузки на сайт (тестовые выгрузки не учитываются) и выгрузка по данному тарифу считается оплаченной до того-же числа следующего месяца. Например, первая рабочая выгрузка была сделана 15-го апреля. Следующее списание со счёта клиента за услугу по выгрузке будет произведено 15-го мая. Таким образом не имеет смысла ожидать начала месяца для начала работы с XML-выгрузкой. Начинать работу можно в любой день.

Формат данных для XML-обмена

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

Если Вы не можете использовать предлагаемый XML-формат, но уже используете для XML-обмена другие популярные форматы, например, Яндекс.Недвижимость, Яндекс.Маркет, Циaн, Aвитo и другие, мы имеем возможность быстрой настройки нашего XML-шлюза на работу и с ними. Главное требование к импортируемым в нашу систему данным - объекты, товары и услуги должны иметь полноценное текстовое описание, а не просто наименование с ценой.

Для ручной загрузки объявлений через личный кабинет пользователя могут использоваться файлы формата MS Office Excel и текстовые файлы с разделителями, формата .CSV (см. описание ниже).

В случае использования Вами перечисленных или любого другого формата обмена процедура подключения XML-выгрузки следующая:

1. Вы делаете запрос на подключение к нашему сервису в Вашем формате через форму обратной связи. В запросе Вы указываете ссылку на файл с Вашими данными и примерное количество объявлений, которые Вы планируете выгружать на наш сайт.

2. Мы проверяем файл, оцениваем реализуемость подобной выгрузки, выявляем наличие технических и логических ошибок в файле, и сообщаем Вам о готовности реализовать XML-обмен.

3. Вы пополняете Ваш кошелёк на сайте на сумму, достаточную для оплаты минимального периода XML-выгрузки (1 месяц).

4. Мы настраиваем XML-импортёр под Ваш формат, загружаем Ваши объявления и сообщаем Вам о готовности ежедневной автоматической загрузки Ваших данных. Так же Вам предоставляется ссылка на отчет о загрузке данных, содержащий ссылки на размещённые на нашем сайте объявления.

Техническое подключение в формате Доски.ру

Возможны два способа обмена XML-данными:

1. Двунаправленный XML-обмен, в процессе которого клиентский софт (программа или серверный скрипт) отправляет XML-запросы на наш XML-шлюз, который обрабатывает данные клиента и немедленно передаёт клиенту результат обработки запроса в XML-виде.
2. Файловая (фид) выгрузка данных объявлений в интернет. Наш скрипт периодически (чаще всего ежедневно) сканирует файл по указанному клиентом адресу и загружает из него данные в нашу базу объявлений.

В таблице представлено сравнение двух способов обмена XML-данными по наиболее важным аспектам.

При этом в обоих способах используется один и тот же формат данных об объявлении с той лишь разницей, что при файловой выгрузке массив объявлений упаковывается в общий XML-контейнер Offers.

Реализация двунаправленного XML-обмена

Адрес шлюза https://www.doski.ru/xmlgate.php

Шлюз обрабатывает шесть типов запросов:

1. Запрос на получение актуального списка разделов и рубрик на сайте Доски.ру, доступных для импорта (необходим для первичной настройки обмена и последующей синхронизации разделов).
2. Запрос на получение актуального списка географических объектов, используемых на сайте Доски.ру.
3. Публикация объявлений клиента.
4. Обновление объявлений клиента.
5. Удаление объявлений клиента.
6. Получение списка объявлений клиента.

Передача данных осуществляется по протоколу HTTP, по стандартной схеме: клиент передает шлюзу XML-запрос в теле запроса POST, шлюз обрабатывает данные, и возвращает ответ в формате XML. Используемая кодировка UTF-8. Простейший пример PHP-функции отправки XML-запроса в теле запроса POST Вы можете посмотреть здесь.

Для авторизации пользователя в API-шлюзе запрос любого типа содержит теги:

UserID - код клиента в системе Доски.ру.

UserHash - хеш-ключ, полученный функцией crc32 из строки, содержащей код клиента в системе Доски.ру и пароль клиента. Крайне не рекомендуется использовать кириллические символы в пароле на доступ к сайту!

При использовании обмена данными через XML-файл данные поля не обязательны, поскольку настройки обмена выполняются уже авторизованными пользователями.

В любом запросе в атрибуте Type тега Request указывается тип запроса (режим работы шлюза).

В любом запросе тег Request может содержать атрибут TestMode, не нулевое значение которого указывает на тестовый режим работы шлюза, при котором шлюз возвращает корректные ответы, но никаких изменений в данных при этом не производится, плата за начало использования XML-обмена не взымается.

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

Запрос на получение актуального списка разделов и рубрик сайта

Атрибут Type тега Request имеет значение "ShowCategories"

Пример запроса списка разделов сайта:

<?xml version="1.0" encoding="UTF-8" ?> 
<Request Type="ShowCategories" UserID="23" UserHash="90823996" />

Ответ шлюза в теге Response содержит полный перечень разделов и рубрик сайта Доски.ру, в которых доступна публикация объявлений в теге Categories. Теги Class содержат атрибут ClassName - название раздела сайта. Теги Category содержат атрибуты:

CategoryID - код рубрики, который необходимо указывать при публикации объявления;

CategoryName - название рубрики.

Пример ответа на запрос списка разделов сайта:

<?xml version="1.0" encoding="UTF-8" ?> 
<Response Status="Success">
	<Categories>
		<Class ClassName="Недвижимость">
			<Class ClassName="Жилая">
				<Category CategoryID="24" CategoryName="Дома, дачи"/>
				<Category CategoryID="22" CategoryName="Квартиры"/>
				<Category CategoryID="23" CategoryName="Комнаты"/>
			</Class>
			<Class ClassName="Коммерческая">
				<Category CategoryID="27" CategoryName="Офисные помещения"/>
				<Category CategoryID="28" CategoryName="Производственные помещения"/>
				<Category CategoryID="30" CategoryName="Свободного назначения"/>
				<Category CategoryID="31" CategoryName="Складские помещения"/>
				<Category CategoryID="32" CategoryName="Торговые помещения"/>
			</Class>
			<Class ClassName="Земельные участки">
				<Category CategoryID="35" CategoryName="Дачные участки"/>
				<Category CategoryID="38" CategoryName="Промышленного назначения"/>
				<Category CategoryID="36" CategoryName="Сельхозугодья"/>
				<Category CategoryID="37" CategoryName="Участки под ИЖС и ЛПХ"/>
				<Category CategoryID="39" CategoryName="Земли прочего использования"/>
			</Class>
		</Class>
		<Category CategoryID="200" CategoryName="Прочее разное"/>
		<Category CategoryID="305" CategoryName="Отдам даром / приму"/>
	</Categories>
</Response>

Полный список разделов в виде XML-файла можно посмотреть здесь

В случае неверной авторизации при обращении к шлюзу клиент может получить следующий ответ:

<?xml version="1.0" encoding="UTF-8" ?> 
<Response Status="Error" ErrorType="1" HumanStatus="Неверный код клиента или неправильный хеш-ключ." />

Запрос на получение актуального списка географических объектов, используемых на сайте

Атрибут Type тега Request имеет значение "ShowLocations"

Пример запроса списка географических объектов

<?xml version="1.0" encoding="UTF-8" ?> 
<Request Type="ShowLocations" UserID="23" UserHash="90823996" />

Ответ шлюза в теге Locations содержит полный перечень регионов и их кодов, используемых на сайте Доски.ру с учётом их иерархии. Некоторые географические объекты объединены в группы, привязка объявлений к которым невозможна. Информация о таких группах передаётся тегами Class, которые содержат единственный атрибут ClassName - название группы географических объектов. Теги Location содержат атрибуты:

LocationID - код географического объекта в базе сайта Доски.ру, который необходимо указывать при публикации объявления;

LocationName - название географического объекта.

Пример ответа на запрос списка географических объектов:

<?xml version="1.0" encoding="UTF-8" ?> 
<Response Status="Success">
	<Locations>
		<Location LocationName="Россия" LocationID="1">
			<Location LocationName="Центральный регион" LocationID="1845">
				<Location LocationName="Москва и Московская область" LocationID="55">
					<Location LocationName="Москва" LocationID="140">
						<Class ClassName="Административные округа">
							<Location LocationName="Восточный округ" LocationID="282"/>
							<Location LocationName="Западный округ" LocationID="286"/>
							<Location LocationName="Зеленоград" LocationID="288"/>
							<Location LocationName="Северный округ" LocationID="280"/>
							<Location LocationName="Северо-Восточный округ" LocationID="281"/>
							<Location LocationName="Северо-Западный округ" LocationID="287"/>
							<Location LocationName="Центральный округ" LocationID="279"/>
							<Location LocationName="Юго-Восточный округ" LocationID="283"/>
							<Location LocationName="Юго-Западный округ" LocationID="285"/>
							<Location LocationName="Южный округ" LocationID="284"/>
						</Class>
					</Location>
				</Location>
			</Location>
		</Location>
	</Location>
</Response>

Полный список географических объектов в виде XML-файла можно посмотреть здесь

В качестве значений аттрибутов тега Location должны использоваться полные официальные названия соответствующих объектов, используемые в официальных классификаторах географических, административно-территориальных объектов без использования сокращений. Например, не "Центральный р-н", а "Центральный район", не "МО", не "Моск. обл.", а "Московская область" и т.д.

Запрос на публикацию объявления клиента

В запросе на публикацию объявления атрибут Type тега Request в запросе имеет значение "SendOffer". В теле запроса передаётся объект Offer, имеющий следующие элементы

Порядок следования тегов не имеет значения, за исключением тегов Image и Video, порядок следования которых определяет порядок следования фотографий и видео в объявлении.

В теге Video должна быть ссылка на видеоролик, выложенный на публичных видеохостингах RuTube или YouTube. Видеоролик должен быть доступен для публичного просмотра, или просмотра по ссылке.

Способ формирования объекта Locations

Каждое объявление на сайте Доски.ру должно иметь как минимум одну привязку к региону или конкретному географическому месту. Для объявлений, публикуемых в разделе "Недвижимость", такая привязка должна быть одна и она должна как можно точнее описывать местоположение объекта. Привязка здесь возможна только к географическим объектам нижнего уровня (город, район города, станция метро). Если для данного региона, например зарубежье, не определён список городов, то возможна привязка к странам. Для объявлений, публикуемых в прочих разделах, например, "Услуги" допустима привязка объявлений к нескольким географическим местам, где данные услуги могут быть оказаны, а так же к географическим объектам верхнего уровня (страны, регионы).

Для задания географической привязки объявления используется контейнер Locations, в котором могут содержаться один или несколько тегов Location, каждый из которых задаёт привязку к одному географическому месту. Тег Location может содержать следующие элементы:

Ни один из перечисленных выше элементов не является обязательным, однако их набор в теге Location должен позволять нашей информационной системе определять местонахождение объекта хотя бы одним из трех возможных способов:

1. Через явное указание кода географического объекта в теге LocationID (наиболее предпочтительный вариант);
2. Через набор элементов Country, Region, District, Locality, SubLocality, Metro, Address.
3. Через географические координаты объекта, заданные элементами Latitude и Longitude.

Ниже приведены примеры формирования тега Location.

Минимальный вариант, полностью определяющий привязку объявления к Центральному Административному округу Москвы через код географического объекта:

<Location LocationID="279"/>

Тот же вариант, дополненный географическими координатами объекта (вариант, желательный для использования с объектами недвижимости):

<Location LocationID="279" Latitude="55.756458" Longitude="37.623211"/>

Для описания объектов недвижимости при любом из вариантов указания привязки лучше дополнять его точными географическими координатами.

Вариант с использованием набора элементов, определяющих расположение объекта:

<Location>
	<Country>Россия</Country>
	<Region>Московская область</Region>
	<District>Дмитровский район</District>
	<Locality>Дмитров</Locality>
	<Address>Чекистская улица, дом 8</Address>
	<Latitude>56.338536</Latitude>
	<Longitude>37.532012</Longitude>
</Location>

Полный вариант с использованием всего возможного набора элементов (тег LocationID содержит код ближайшего к объекту метро Пушкинская):

<Location>
	<LocationID>411</LocationID>
	<Country>Россия</Country>
	<Region>Московская область</Region>
	<Locality>Москва</Locality>
	<SubLocality>Центральный округ</SubLocality>
	<Metro>Пушкинская</Metro>
	<Address>Тверская улица, 18а</Address>
	<Latitude>55.765969</Latitude>
	<Longitude>37.604034</Longitude>
</Location>

Способ формирования объекта OfferType

В зависимости от выбранной для публикации рубрики объявлению может быть присвоен один из нескольких типов, который передаётся в теге OfferType. Данный тег должен содержать хотя бы один из двух атрибутов (можно оба), определяющих выбранный тип:

Например, ниже в таблице приведены возможные типы объявлений для рубрик раздела "Недвижимость":

Примеры возможных вариантов заполнения тега OfferType (варианты эквивалентны)³:

<OfferType>
	<TypeID>1</TypeID>
	<TypeName>Продам</TypeName>
</OfferType>

<OfferType TypeID="1"/>

<OfferType TypeName="Продам"/>

Чтобы получить информацию о возможных значениях типов объявлений для интересующей Вас рубрики, выберите её название в дереве рубрик ниже

Выберите рубрику

Способ формирования элемента Parms

В контейнере Parms в элементах Parm передаются дополнительные параметры, характеризующие объект, описываемый в объявлении. Например, для объявлений о продаже квартиры такими параметрами будут количество комнат в квартире, общая и жилая площади, этаж, состояние ремонта...

Плохая новость состоит в том, что для каждого сочетания "тематическая рубрика - тип объявления" может быть определён свой (в том числе и пустой) набор параметров, часть из которых обязательна для указания. Таким образом не очень просто точно настроить экспорт данных на каждую рубрику и каждый тип объявления.

Хорошие же новости состоят в том, что, во-первых, общий перечень дополнительных параметров не такой большой. Во-вторых, при экспорте данных в структуре объявления можно передавать и те параметры, которые для данной рубрики и данного типа объявлений не используются. Это не вызовет фатальной ошибки и не прервёт обработку данного объявления. Лишние параметры будут просто проигнорированы.

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

Элемент Parm формируется следующим образом:

Примеры возможных вариантов заполнения тега Parm (варианты эквивалентны):

<Parm>
	<ParmID>1</ParmID>
	<ParmName>FlatArea</ParmName>
	<Value>34.3</Value>
	<Unit>кв.м</Unit>
</Parm>

<Parm ParmID="1" Value="34.3"/>

<Parm ParmName="FlatArea" Value="34.3"/>

Примеры возможных вариантов заполнения тега Parm для перечислимых типов (варианты эквивалентны):

<Parm>
	<ParmID>36</ParmID>
	<ParmName>Condition</ParmName>
	<ValueID>3</ValueID>
	<Value>Требует ремонта</Value>
</Parm>

<Parm>
	<ParmID>36</ParmID>
	<ValueID>3</ValueID>
</Parm>

<Parm>
	<ParmName>Condition</ParmName>
	<Value>Требует ремонта</Value>
</Parm>

<Parm ParmID="36" ValueID="3"/>

<Parm ParmName="Condition" Value="Требует ремонта"/>

На данных примерах видно, что при использовании только ParmID и ValueID получаем более компактный код, а при использовании ParmName и Value более читаемый.

Список используемых на сайте Доски.ру дополнительных параметров:

Параметры площади участка LotArea, LotAreaSot и LotAreaGa являются взаимозаменяемыми. Не найдя требуемого для данной рубрики параметра XML-парсер пытается определить его значение по наличию другого параметра площади участка с нужным коэффициэнтом пересчёта.

Для примера ниже приведена таблица использования дополнительных параметров в рубриках раздела "Недвижимость":

Чтобы получить информацию об использовании дополнительных параметров в интересующей Вас рубрике, выберите её название в дереве рубрик ниже

Выберите рубрику

Примеры запросов на добавление объявления

Минимальный вариант. Реклама услуг, предоставляемых удалённо по всей территории России. Без типа объявления, без цены, без фото, без дополнительных параметров.

<?xml version="1.0" encoding="UTF-8" ?> 
<Request Type="SendOffer" UserID="23" UserHash="90823996">
	<Offer>
		<InternalID>123456</InternalID>
		<CategoryID>385</CategoryID>
		<Locations>
			<Location LocationID="1"/>
		</Locations>
		<Title>Удалённая разработка и продвижение сайтов</Title>
		<Description>Создаю недорогие сайты для малого и среднего бизнеса. Полный спектр услуг: разработка, дизайн, вёрстка, продвижение.
	Без предоплаты, оплата по факту.</Description>
		<UserType>1</UserType>
		<ContactName>Анатолий Ефремович</ContactName>
		<ContactMail>novoselcev@site.my</ContactMail>
	</Offer>
</Request>

Полноценный вариант. Продажа квартиры.

<?xml version="1.0" encoding="UTF-8" ?> 
<Request Type="SendOffer" UserID="23" UserHash="90823996">
	<Offer>
		<InternalID>654321</InternalID>
		<CategoryID>22</CategoryID>
		<Locations>
			<Location>
				<LocationID>325</LocationID>
				<Country>Россия</Country>
				<Locality>Москва</Locality>
				<SubLocality>Западный округ</SubLocality>
				<Metro>Славянский бульвар</Metro>
				<Address>Кутузовский проспект, 52</Address>
				<Latitude>55.730944</Latitude>
				<Longitude>37.483443</Longitude>
			</Location>
		</Locations>
		<OfferType>
			<TypeID>1</TypeID>
			<TypeName>Продам</TypeName>
		</OfferType>
		<Title>Продается трехкомнатная квартира, Кутузовский проспект</Title>
		<Description>Продается трехкомнатная квартира на 5 этаже 17 этажного кирпичного дома.
Общая площадь 74м, жилая 52м, кухня 9м, с/у совмещенный, балкон, в зале два окна.
Стеклопакеты, теплые и толстые стены. Приличные соседи. Уютный двор.
Более 3 лет в собственности. Оперативный показ.</Description>
		<UserType>2</UserType>
		<CompanyName>МИАНЭЛЬ</CompanyName>
		<ContactName>Светлана</ContactName>
		<ContactMail>2345683@mianel.mi</ContactMail>
		<Phone>+7(495)2345683</Phone>
		<Price Value="17000000.00" Currency="RUR"/>
		<Pass>qwerty123</Pass>
		<Images>
			<Image>https://www.doski.ru/xmlpict1.png</Image>
			<Image>https://www.doski.ru/xmlpict2.png</Image>
			<Video>https://youtu.be/IpBjJ0dp2mc</Video>
			<Video>https://rutube.ru/video/105ab2437eda642af56912c5ec173332/?r=wd</Video>
		</Images>
		<DaysPromote>30</DaysPromote>
		<PublicDate>2024-05-13 23:00:59</PublicDate>
		<ExpireDate>2024-06-12 23:00:59</ExpireDate>
		<Parms>
			<Parm ParmName="NewFlat" Value="0"/>
			<Parm ParmName="Rooms" Value="3"/>
			<Parm ParmName="TotalArea" Value="74"/>
			<Parm ParmName="LivingArea" Value="52"/>
			<Parm ParmName="Floor" Value="5"/>
			<Parm ParmName="Condition" Value="После ремонта"/>
		</Parms>
	</Offer>
</Request>

Ответ на запрос на публикацию объявления

Единственный тег ответа на запрос Response содержит следующие атрибуты:

Status - статус обработки запроса. Success - в случае, если объявление принято к публикации, Error - если в публикации отказано.

OfferID - уникальный идентификатор нового объявления в базе сайта Доски.ру, в случае, если объявление принято к публикации. Данный идентификатор можно, например, использовать для формирования запросов на обновление и удаление объявления, поиска объявления на сайте и т.п.

ErrorType - код ошибки, в случае, если в публикации отказано.

HumanStatus - текстовое описание результата обработки объявления для удобства восприятия ответа шлюза и для отладки.

Примеры ответа на запрос на публикацию объявления

<?xml version="1.0" encoding="UTF-8" ?> 
<Response OfferID="77723" Status="Success" HumanStatus="Объявление опубликовано" />

<?xml version="1.0" encoding="UTF-8" ?> 
<Response Status="Error" ErrorType="5" HumanStatus="Отсутствует обязательное поле 'Заголовок'." />

Запрос на обновление объявления

В запросе на обновление объявления атрибут Type тега Request в запросе имеет значение "UpdateOffer".

В теле запроса передаётся объект Offer, в котором должны содержаться как минимум один из двух обязательных тегов InternalID или OfferID, соответственно внутренний (для клиента) или внешний идентификатор объявления, которое необходимо обновить. При наличии обоих тегов, используется идентификатор Доски.ру из тега OfferID.

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

Так же следует иметь в виду, что после публикации объявления игнорируется значение тегов CategoryID и OfferType, т.е. изменение рубрики, в которой изначально опубликовано объявление, и типа объявления заблокировано.

Примеры запроса на обновление объявления

Обновление заголовка объявления:

<?xml version="1.0" encoding="UTF-8" ?>
<Request Type="UpdateOffer" UserID="23" UserHash="90823996">
	<Offer>
		<OfferID>77723</OfferID>
		<Title>Срочно продается трехкомнатная квартира, Кутузовский проспект</Title>
	</Offer>
</Request>

Включение продвижения объявления на 50 дней:

<?xml version="1.0" encoding="UTF-8" ?>
<Request Type="UpdateOffer" UserID="23" UserHash="90823996">
	<Offer>
		<OfferID>77723</OfferID>
		<DaysPromote>50</DaysPromote>
	</Offer>
</Request>

Изменение порядка следования фотографий и видео в объявлении:

<?xml version="1.0" encoding="UTF-8" ?>
<Request Type="UpdateOffer" UserID="23" UserHash="90823996">
	<Offer>
		<InternalID>654321</InternalID>
		<Images>
			<Video>https://youtu.be/IpBjJ0dp2mc</Video>
			<Image>https://www.doski.ru/xmlpict2.png</Image>
			<Image>https://www.doski.ru/xmlpict1.png</Image>
		</Images>
	</Offer>
</Request>

Удаление фотографий и видео в объявлении:

<?xml version="1.0" encoding="UTF-8" ?>
<Request Type="UpdateOffer" UserID="23" UserHash="90823996">
	<Offer>
		<OfferID>77723</OfferID>
		<InternalID>654321</InternalID>
		<Images />
	</Offer>
</Request>

Как видно из последних двух примеров содержимое контейнеров Images считается полным набором фотографий и видео для данного объявления. Таким образом, при добавлении новой фотографии или видео к объявлению информацию о ней нужно передавать вместе с информацией о ранее добавленных фото и видео. Все фотографии и видео, которых нет в контейнере Images, удаляются. Если контейнер Images пуст, удаляются все фотографии и видео в данном объявлении. Если контейнер Images отсутствует в запросе на обновление объявления, фотографии и видео к объявлению (если они были) не изменяются.

То же относится к другим элементам-контейнерам Locations и Parms, которые могут содержать несколько одинаковых дочерних элементов - Location и Parm соответственно. При обновлении хотя бы одного дочернего элемента в родительском элементе-контейнере необходимо передавать полный набор дочерних элементов, включая те, которые не изменялись. Так удаётся избежать двойственности трактования отсутствия дочернего элемента, когда непонятно, удалён он, или не изменялся. При отсутствии родительских элементов Locations и Parms в запросе на обновление объявление подразумевается, что соответствующие данные не изменялись. При наличии пустого элемента Parms подразумевается, что необходимо удалить все дополнительные параметры объявления. Наличие пустого элемента Locations не допустимо, т.к. объявление обязательно должно быть привязано хотя бы к одной географической точке.

Запрос на удаление объявления

В запросе на удаление объявления атрибут Type тега Request в запросе имеет значение "DeleteOffer".

Так же в теге Request должен содержаться как минимум один из двух обязательных тегов InternalID или OfferID, соответственно внутренний (для клиента) или внешний идентификатор объявления, которое необходимо удалить. При наличии обоих тегов, используется идентификатор Доски.ру из тега OfferID.

<?xml version="1.0" encoding="UTF-8" ?>
<Request Type="DeleteOffer" UserID="23" UserHash="90823996" OfferID="77723"/>

Или так:

<?xml version="1.0" encoding="UTF-8" ?>
<Request Type="DeleteOffer" UserID="23" UserHash="90823996" InternalID="654321"/>

При удалении объявления, на счету которого остались денежные средства на продвижение объявления, эти средства возвращаются на кошелёк клиента.

Запрос на получение списка объявлений клиента

В запросе на получение списка объявлений и других данных клиента атрибут Type тега Request в запросе имеет значение "ShowMyOffers".

<?xml version="1.0" encoding="UTF-8" ?>
<Request Type="ShowMyOffers" UserID="23" UserHash="90823996" />

Ответ шлюза содержит контейнер Offers c полным перечнем объявлений клиента с их внутренними и внешними (если они были указаны при публикации) идентификаторами, кодами рубрик, статусами на сайте, и суммой на счету каждого объявления. Теги Offer содержат атрибуты:

OfferID - идентификатор объявления на сайте Доски.ру;

InternalID - идентификатор объявления в системе клиента;

CreatedDate - дата и время первой публикации объявления (в формате YYYY-MM-DD HH:mm:ss);

CategoryID - код рубрики в которой находится объявление;

Status - статус объявления (на проверке, опубликовано, изменено);

Amount - сумма на счету данного объявления.

Link - ссылка на объявление на сайте Доски.ру.

Пример ответа на запрос списка объявлений клиента:

<?xml version="1.0" encoding="UTF-8" ?> 
<Response Status="Success">
	<Offers>
		<Offer OfferID="77723" InternalID="12777" CreatedDate="2014-08-30 21:55:30" CategoryID="12" Status="InCheck"
							Amount="150.00"	Link="https://www.doski.ru/-msg77723.htm"/>
		<Offer OfferID="77724" InternalID="12779" CreatedDate="2014-08-30 21:55:31" CategoryID="23" Status="Checked"
							Link="https://www.doski.ru/-msg77724.htm"/>
		<Offer OfferID="77725" InternalID="12778" CreatedDate="2014-08-30 21:55:32" CategoryID="132" Status="Changed"
							Amount="220.00"	Link="https://www.doski.ru/-msg77725.htm"/>
	</Offers>
</Response>

Данный список можно так же получить обычным GET-запросом с теми же параметрами: https://www.doski.ru/xmlinfo.xml?type=ShowMyOffers&UserID=23&UserHash=90823996

Реализация обмена с помощью файловой (фид) выгрузки

Данная схема обмена более традиционна и проста по сравнению с описанной выше схемой двунаправленного XML-обмена, однако необходимо понимать её недостатки и ограничения. Реализуется обмен следующим образом. Чтобы интерфейс управления XML-обменом на сайте Доски.ру был доступен клиенту, ему необходимо выполнить организационное подключение. Клиент в своём интерфейсе указывает адрес постоянного местонахождения файла с данными (фида). После этого с заданной периодичностью (не реже 1 раза в сутки) система Доски.ру обрабатывает этот файл и импортирует данные клиента в свою базу.

При этом предполагается, что файл с данными клиента содержит полный набор его объявлений, а значит объявления клиента, которые уже есть на сайте Доски.ру и которые не вошли в обрабатываемый файл удаляются.

Обмен с помощью файловой (фид) выгрузки не предполагает автоматическое получение и обработку информационной системой клиента результатов импорта данных из фида. При желании клиент может посмотреть результаты обработки в интерфейсе управления XML-обменом на сайте Доски.ру.

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

Таким образом файл, передающий данные о двух объявлениях, рассматриваемых в предыдущем разделе, будет выглядеть так:

<?xml version="1.0" encoding="UTF-8" ?>
<Request Type="SendOffer">
	<Offers>
		<Offer>
			<InternalID>123456</InternalID>
			<CategoryID>385</CategoryID>
			<Locations>
				<Location LocationID="1"/>
			</Locations>
			<Title>Удалённая разработка и продвижение сайтов</Title>
			<Description>Создаю недорогие сайты для малого и среднего бизнеса.
			Полный спектр услуг: разработка, дизайн, вёрстка, продвижение.
			Без предоплаты, оплата по факту.</Description>
			<UserType>1</UserType>
			<ContactName>Анатолий Ефремович</ContactName>
			<ContactMail>novoselcev@site.my</ContactMail>
		</Offer>
		<Offer>
			<InternalID>654321</InternalID>
			<CategoryID>22</CategoryID>
			<Locations>
				<Location>
					<LocationID>325</LocationID>
					<Country>Россия</Country>
					<Locality>Москва</Locality>
					<SubLocality>Западный округ</SubLocality>
					<Metro>Славянский бульвар</Metro>
					<Address>Кутузовский проспект, 52</Address>
					<Latitude>55.730944</Latitude>
					<Longitude>37.483443</Longitude>
				</Location>
			</Locations>
			<OfferType>
				<TypeID>1</TypeID>
				<TypeName>Продам</TypeName>
			</OfferType>
			<Title>Продается трехкомнатная квартира, Кутузовский проспект</Title>
			<Description>Продается трехкомнатная квартира на 5 этаже 17 этажного кирпичного дома.
	Общая площадь 74м, жилая 52м, кухня 9м, с/у совмещенный, балкон, в зале два окна.
	Стеклопакеты, теплые и толстые стены. Приличные соседи. Уютный двор.
	Более 3 лет в собственности. Оперативный показ.</Description>
			<UserType>2</UserType>
			<CompanyName>МИАНЭЛЬ</CompanyName>
			<ContactName>Светлана</ContactName>
			<ContactMail>2345683@mianel.mi</ContactMail>
			<Phone>+7(495)2345683</Phone>
			<Price Value="17000000.00" Currency="RUR"/>
			<Pass>qwerty123</Pass>
			<Images>
				<Image>https://www.doski.ru/xmlpict1.png</Image>
				<Image>https://www.doski.ru/xmlpict2.png</Image>
				<Video>https://youtu.be/IpBjJ0dp2mc</Video>
				<Video>https://rutube.ru/video/105ab2437eda642af56912c5ec173332/?r=wd</Video>
			</Images>
			<DaysPromote>30</DaysPromote>
			<PublicDate>2024-05-13 23:00:59</PublicDate>
			<ExpireDate>2024-06-12 23:00:59</ExpireDate>
			<Parms>
				<Parm ParmName="NewFlat" Value="0"/>
				<Parm ParmName="Rooms" Value="3"/>
				<Parm ParmName="TotalArea" Value="74"/>
				<Parm ParmName="LivingArea" Value="52"/>
				<Parm ParmName="Floor" Value="5"/>
				<Parm ParmName="Condition" Value="После ремонта"/>
			</Parms>
		</Offer>
	</Offers>
</Request>

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

Если файл был успешно обработан, и из него удалось получить код клиента, подтвердить его через UserHash, и получить список объектов, то дальнейшие результаты обработки, включающие статус обработки, найденные критичные и некритичные ошибки, записываются в лог, получить который в XML-формате можно GET-запросом следующего вида: https://www.doski.ru/xmlinfo.xml?type=ShowFidLog&UserID=23&UserHash=90823996. В ответе на данный запрос можно увидеть информацию об обработке фида за последние несколько дней. Для каждого объявления может быть несколько строк, строки с полностью повторяющимися результатами обработки опускаются.

<?xml version="1.0" encoding="UTF-8" ?> 
<Response Status="Success">
	<Logs>
		<Log InternalID="5237" Status="Approved" DateTime="2014-10-29 18:52:02" OfferID="1127753" Link="https://www.doski.ru/uchastki-5000-sotka-98km-v-dp-raduzhnaya-dolina-msg1127753.htm" />
		<Log InternalID="5247" Status="Approved" DateTime="2014-10-29 18:52:04" OfferID="1127755" Link="https://www.doski.ru/10-sotok-39-000-pyblei-sotka-u-mozhaiskogo-morya-msg1127755.htm" />
		<Log InternalID="9930" Status="Rejected" DateTime="2014-10-29 18:43:18">
			<CriticalError>Отсутствует обязательный для выбранной рубрики и типа объявления параметр: "Состояние" (ParmID="33" ParmName="HouseCondition").</CriticalError>
		</Log>
		<Log InternalID="9932" Status="Rejected" DateTime="2014-10-29 18:43:18">
			<CriticalError>Отсутствует обязательный для выбранной рубрики и типа объявления параметр: "Количество этажей" (ParmID="25" ParmName="FloorsTotal").
				Отсутствует обязательный для выбранной рубрики и типа объявления параметр: "Состояние" (ParmID="33" ParmName="HouseCondition").
			</CriticalError>
		</Log>
		<Log InternalID="30491" Status="Approved" DateTime="2014-10-29 18:52:45" OfferID="1127820" Link="https://www.doski.ru/sdam-2-k-kv-posutochno-m-babushkinskaya-msg1127820.htm">
			<NonCriticalError>Параметр ParmName="TotalArea" не используется для выбранной рубрики и типа объявления, или отсутствует в списке дополнительных параметров. Значение будет проигнорировано.
			Параметр ParmName="LivingArea" не используется для выбранной рубрики и типа объявления, или отсутствует в списке дополнительных параметров. Значение будет проигнорировано.
			</NonCriticalError>
		</Log>
	</Logs>
</Response>

Объект CriticalError содержит текст критических ошибок, наличие которых приводит к отказу в публикации данного объявления. Объект NonCriticalError содержит текст НЕ критических ошибок, наличие которых не приводит к отказу в публикации данного объявления, однако исправление которых может быть полезно для полноты предоставления данных читателям объявления. Атрибут Link содержит ссылку на опубликованное объявление на сайте Доски.ру.

Дополнения и пояснения

1. При заданном значении необязательного элемента Pass (пароль для редактирования объявления) объявление можно редактировать как через аккаунт пользователя, залогинившись на сайте, так и непосредственно, введя пароль для доступа к объявлению. Пароль на редактирования объявления и пароль для аккаунта пользователя могут (рекомендуется) отличаться друг от друга. Данной возможностью можно пользоваться в случае, когда клиент, выгружающий объявления, является посредником для многих, подающих объявления в базу клиента частных лиц. Таким образом доступ к объявлению может получить как клиент, так и сам автор объявления независимо друг от друга.

2. Действие тега DaysPromote при любом типе запросов (добавление или обновление объявления) следующее: из кошелька пользователя на сайте на счёт объявления переводится сумма, необходимая для продвижения объявления в течение указанного тегом DaysPromote количества дней. Если на счету пользователя находится сумма меньше необходимой, то переводится сумма, равная остатку средств на кошельке пользователя. Если на счету объявления уже находится сумма, которая больше суммы, необходимой для продвижения объявления на указанное количество дней, то разница между этими суммами возвращается на кошелёк пользователя. При нулевом значении тега DaysPromote на кошелёк пользователя возвращается вся сумма, за вычетом суммы за продвижение в текущем дне, когда услуга по продвижению уже оказывалась. Отсутствие тега DaysPromote не меняет состояние счёта объявления.

3. Для обеспечения возможности сокращения объёма передаваемой в фид-файлах и POST-запросах информации XML-гейт разбирает передаваемые ему данные по следующему правилу: дочерние элементы, вложенные в родительские, считаются эквивалентными одноимённым атрибутам родительских элементов. Таким образом:

<Price>
	<Value>10000</Value>
	<Currency>RUR</Currency>
</Price>

<Price Value="1" Currency="RUR"/>

<Parm>
	<ParmID>1</ParmID>
	<Value>34.3</Value>
	<Unit>кв.м</Unit>
</Parm>

<Parm ParmID="1" Value="34.3"/>

Данная возможность не обеспечивается стандартами XML, а является полезной особенностью нашего XML-гейта.

Описание Excel формата, используемого для ручной выгрузки

Для работы со списком объявлений через личный кабинет пользователя (ручная не автоматическая выгрузка) наряду с XML-файлами могут использоваться табличные форматы файлов, такие как файлы MS Office Excel (.XLS, .XLSX) и текстовые файлы с разделителями .CSV. Ограничение на использование их только в ручном режиме определяется тем, что при всей простоте работы с ними, они имеют существенные недостатки по гибкости, и объёму передаваемых данных.

Для файлов Excel обрабатывается только один активный лист, данные на листе должны быть расположены вначале, с первой строчки.

Первая строка файла Excel и файла с разделителями должна содержать названия полей. Вся поля кроме поля "Код объявления" могут следовать в любом порядке, хотя рекомендуется порядок, определённый в приведённом ниже перечислении полей. Поле "Код объявления" должно располагаться в начале строки, перед остальными импортируемыми полями, в противном случае не гарантируется правильно определение идентификатора объявления (разные форматы и разные информационные системы используют разные поля в качестве идентификатора). Для названий полей можно выбрать русский или нерусский вариант. Регистр названий полей не важен.

В зависимости от категории, в которой публикуется объявление, необходимо указывать дополнительные параметры объявления, из списка дополнительных параметров.

Ниже Вы можете скачать шаблон Excel-файла для импорта, и использовать его либо для заполнения, либо в качестве примера, для создания файла аналогичного формата. Обращаем внимание, что в файле несколько закладок:

• Таблица для заполнения с колонками на русском языке;
• Таблица для заполнения с колонками на нерусском языке;
• Лист с подсказками и комментариями.
• справочники используемых рубрик и регионов.

Данные с объявлениями для загрузки необходимо заполнить на одном из двух первых листов, оставив его активным на момент сохранения файла. Поскольку набор дополнительных полей-параметров, зависит от рубрики, в которую импортируются объявления, и типа объявления, для скачивания Excel-шаблона необходимо выбрать рубрику и тип объявления. Если в одном файле предполагается подавать объявления в несколько различных рубрик, набор дополнительных полей-параметров содержит объединение полей-параметров используемых рубрик.

Выберите рубрику для скачивания Excel-шаблона

Вопросы, возникающие при подключении Вашей организации к нашей системе обмена объявлениями, Вы можете задавать по E-mail: fs7doski.ru и через форму обратной связи.