Спецификация AML-файла для автоматической загрузки объявлений


1. ОБЩИЕ ДАННЫЕ

AML —это стандарт, разработанный для автоматического импорта объявлений о продаже катеров и яхт с веб-сайта продавца и последующей публикации в базе данных объявлений о продаже судов на интернет-портале AllYachts.Ru.

AML основан на стандарте XML. Для работы с ним необходимо создать AML-файл, с помощью которого реализуется экспорт объявлений о судах для продажи из вашей базы данных или с вашего веб-сайта в базу данных AllYachts.Ru.

Созданный AML-файл размещается на сайте вашей компании, и далее его URL указывается в Клиентском разделе вашей компании на AllYachts.Ru в процессе перехода на AML-режим работы с базой объявлений (при этом возможность вручную редактировать и добавлять объявления отключается).

AML-файл проверяется и скачивается роботом ежедневно и обновленные данные импортируются в базу объявлений о продаже интернет-портала AllYachts.Ru.

ВНИМАНИЕ! При включении режима AML, указании ссылки на ваш AML-файл и нажатии на кнопку "Сохранить" (после проверки файла роботом), список объявлений будет синхронизирован с AML-файлом. ВСЕ ДОБАВЛЕННЫЕ ВРУЧНУЮ ДО ЭТОГО МОМЕНТА ОБЪЯВЛЕНИЯ БУДУТ УДАЛЕНЫ! См. также примечания # 5, 6, 7, 8.

Первое обновление данных из AML-файла происходит не сразу при добавении ссылки, прохождении проверки и нажатии кнопки "Сохранить", а только в очередное время запуска процесса синхронизации на сервере AllYachts.Ru. См. примечание #5.


2. Описание элементов и атрибутов AML-файла

Шаблон AML-файла вы найдете по ссылке: http://www.allyachts.ru/aml.xml. Кодировка ТОЛЬКО "windows-1251"!

  • Элемент (обязательный) aml_catalog - корневой элемент AML-документа.
    • Атрибут (обязательный) date - дата и время генерации AML-файла на стороне клиента в формате ГГГГ-ММ-ДД ЧЧ:ММ.

  • Элемент (обязательный) partner - содержит описание компании и объявлений (предложений о продаже судов).

  • Элемент (необязательный) name - название компании, для идентификации клиента.

  • Элемент (необязательный) email - e-mail технического специалиста клиента для отправки сообщений об ошибках при обработке AML-файла.

  • Элемент (необязательный) phone - телефон для связи по техническим вопросам.

  • Элемент (обязательный) lots - в элементе содержится список объявлений.

  • Элемент (обязательный, множественный) lot - объявление по продаже судна.
    • Атрибут (обязательный) id - УНИКАЛЬНЫЙ идентификатор объявления о продаже, передаваемый от клиента (например, уникальный ID из клиентской базы данных). Идентификатор объявления должен содержать только цифры без разделителей. Идентификатор объявления должен быть уникальным среди всех объявлений одного AML-файла. Если у двух и более объявлений указать одинаковые атрибуты id, то в каталог предложений на AllYachts.Ru будет добавлено только первое объявление, остальные будут проигнорированы.
    • Атрибут (необязательный) published [возможные значения: "true" | "false"; по-умолчанию: "true"] - отвечает за публикацию/снятие с публикации объявления (при этом объявление не удаляется из системы). Может не использоваться, тогда считается, что объявление опубликовано. Смотри также примечание #2.

  • Элемент (обязательный) brand_name - производитель (верфь) судна.

  • Элемент (обязательный) model_name - название модели судна.

  • Элемент (необязательный) boat_name - имя судна.

  • Элемент (обязательный) readiness [возможные значения: "stock" | "construction" | "order"] - определяет готовность судна. stock - В наличи/In Stock, construction - В постройке/Under Construction, order - На заказ/For Order.

  • Элемент (обязательный) state [возможные значения: "new" | "used"] - определяет состояние судна. new - Новое/New, used - Бывшее в употреблении/Used.

  • Элемент (обязательный) year_of_release - год выпуска судна в формате ГГГГ.

  • Элемент (обязательный) country_name - страна местонахождения судна.

  • Элемент (обязательный) city_name - город местонахождения судна.

  • Элемент (необязательный) price - цена судна в указанной валюте (число без пробелов и разделителей; копейки, центы и т.п. не указывать). При отсутствии элемента или его пустом значении цена подразумевается как "по запросу".

  • Элемент (обязательный, если указан элемент price) currency [возможные значения: RUR | EUR | USD | GBP | SEK] - валюта цены судна.

  • Элемент (необязательный) price_type [возможные значения: "in_RF" | "not_in_RF"; по-умолчанию "not_in_RF"] - территория действия цены. in_RF - в Росии, not_in_RF - не в России. Подробное описание http://www.allyachts.ru/client/cost.asp

  • Элемент (необязательный) price_delta [по-умолчанию: 38] - дельта в процентах, разница стоимости судна в России и за ее пределами. По-умолчанию устанавливается 38%. Подробное описание http://www.allyachts.ru/client/cost.asp

  • Элемент (необязательный) price_note_rus - примечание к цене для русской версии AllYachts.Ru, ограничение числа символов - 512.

  • Элемент (необязательный) price_note_eng - примечание к цене для английской версии AllYachts.Org, ограничение числа символов - 512.

  • Элемент (необязательный) discount_price - цена судна со скидкой в указанной валюте (число без пробелов и разделителей).

  • Элемент (необязательный) engine - двигатель судна и краткое описание (кол-во, марка, модель, мощность, наработка), ограничение числа символов - 255.

  • Элемент (необязательный) description_rus - описание судна для русской версии AllYachts.Ru, в этом элементе можно использовать html-код (при этом символы " & < > ' необходимо заменять на их символьные коды, смотри примечание #1).

  • Элемент (необязательный) description_eng - описание судна для английской версии AllYachts.Org, в этом элементе можно использовать html-код (при этом символы " & < > ' необходимо заменять на их символьные коды, смотри примечание #1).

  • Элемент (необязательный) url - http-ссылка web-страницы с подробными данными, ограничение числа символов - 500.

  • Элемент (необязательный) images - в элементе содержится список изображений для объявления. Если этот элемент отсутствует в объявлении, то используются изображения из каталога AllYachts.Ru. Смотри также примечание #8.
    • Атрибут (необязательный) use_ay_images [возможнные значения: "true" | "false"; по-умолчанию: "false"] - атрибут определяет какие изображения использовать. "false" - пользовательские из вложенных элементов image или "true" - изображения из каталога AllYachts.Ru.

  • Элемент (необязательный, множественный) image - URL-адрес изображения судна. Для каждого предложения о продаже в элементе можно указать до 20 (двадцати) URL-адресов изображений, соответствующих данному объявлению (если будет указано больше 20, то они будут отброшены). Максимальная длина URL-адреса — 512 символов. По указанным URL-адресам должны находиться изображения формата JPG, JPEG, BMP или PNG размером не менее 100 пикселей по любой из сторон. Для показа увеличенных изображений рекомендованный размер составляет не менее 600 пикселей по любой из сторон. Изображения на прозрачном фоне не поддерживаются. Ссылка на HTML-страницу, содержащую изображение, не допустима. Если в элементе нет ни одного элемента , то используются изображения из каталога AllYachts.Ru.
    • Атрибут (необязательный) main [возможнные значения: "true" | "false"; по-умолчанию: "false"] - атрибут определяет изображение, которое будет использоваться как главное для данного объявления. Если ни у одного из элементов данного объявления нет атрибута main="true", то как главное изображение будет использоваться заглавное изображение модели из каталога AllYachts.Ru. Если значение атрибута main будет установлено "true" для нескольких элементов одного объявления, то в качестве главного будет использоваться первое встретившееся в списке изображение с установленным main="true".

Примечания

  1. Стандарт AML не допускает использования в текстовых данных непечатаемых символов с ASCII-кодами в диапазоне значений от 0 до 31. Это требует обязательной замены некоторых символов на эквивалентные им символьные коды (Символ в тексте - Код для AML-файла):
    & - &amp;
    " - &quot;
    > - &gt;
    < - &lt;
    ' - &apos;
    В первую очередь надо заменять символ &, чтобы затем избежать замен уже в символьных кодах. Cимволы с кодами 9, 10, 13 — табуляция, перевод строки, возврат каретки - для AML заменять на пробел.

  2. Объявления, указанные в AML-файле в элементе lot с атрибутом published="true" публикуются в каталоге AllYachts.Ru. При установке published="false" объявление снимается с публикации, но не удаляется.

  3. Если какой либо Элемент или Атрибут, отмеченный как (обязательный) не заполнен, то объявление НЕ БУДЕТ опубликовано в базе AllYachts.Ru и на e-mail, указанный в AML-файле будет отправлено соответствующее сообщения об ошибке.

  4. Если какой либо Элемент или Атрибут, значение которого должно быть указано из приведенного фиксированного списка, будет содержать значение отличное от одного из указанных в списке, то возможны два варианта обработки. Если Элемент или Атрибут, отмечен как (обязательный), то объявление НЕ БУДЕТ опубликовано в базе AllYachts.Ru и на e-mail, указанный в AML-файле будет отправлено соответствующее сообщение об ошибке. Если Элемент или Атрибут, отмечен как (необязательный), то Элемент или Атрибут с некорректным значением будет воспринят как отсутсвующий, либо будет установлено значение по-умолчанию.

  5. Обновление списка объявлений (загрузка AML-файла по адресу указанному клиентом) происходит один раз в сутки в 7 утра по Московскому времени. Первоначальная загрузка соответственно происходит в 7 утра следующего дня, если режим был включен до 0 часов, или текущего дня, если режим был включен до 7 утра. При обновлении списка объявлений на AllYachts.Ru соответствие устанавливается по уникальному ID, передаваемому клиентом и указанной первоначально модели из каталога AllYachts.Ru.

  6. Объявления, элементы "brand_name", "model_name", "country_name" которого отсутствуют в базе данных AllYachts.Ru в данный момент определяются в обработку, которая в оперативном порядке будет проведена сотрудниками AllYachts.Ru. По мере добавления необходимых объектов в базу AllYachts.Ru предложения будут публиковаться.

  7. Объявления, которые присутствовали в AML-файле и исчезли из него помечаются в системе AllYachts.Ru как удаленные. Для удаленных объявлений в системе хранятся все запросы пользователей по ним.

  8. Если объявление с определенным ID будет убран из AML-файла, соответственно он будет удален из списка AllYachts.Ru, при появлении этого объявления снова (или объявления с таким же ID, как у удаленного) он НЕ будет восстановлен, а будет воспринят системой как новый).

  9. Каждый день синхронизируются все поля, вся текстовая информация, за исключеним изображений. Изображения через AML-файл загружаются для объявления только ОДИН раз при его первичном появлении в списке. При необходимости изменить изображения, следует воспользоваться web-интерфейсом клиентского раздела AllYachts.Ru http://www.allyachts.ru/client/