API автосалона - maxposter/maxDealerAPI GitHub Wiki

Данное API является устаревшим и будет отключено начиная с 2021 года. 
Для получения подробной информации об иных способах интеграции с сервисом MaxPoster
следует написать запрос на [email protected].

Соглашение

Доступ предоставляется пользователям сервиса MaxPoster.
Данные предоставляются в формате XML.
Структура XML документов может изменяться MaxPoster в одностороннем порядке.
Экспортные данные обновляются с частотой раз в час. Период обновления данных может быть изменен MaxPoster в одностороннем порядке без дополнительного уведомления пользователей.
Полученные экспортные данные (как XML так и фотографии) должны кэшироваться на стороне автосалона до момента истечения их актуальности, при этом срок актуальности данных передается сервисом в заголовке ответа Expires.
Кэширование обеспечивает использование клиентских скриптов (см. далее), применение которых при запросах крайне желательно. За чрезмерное количество идентичных запросов, вызванное отсутствием кэширования данных на стороне автосалона, доступ к экспортным данным может быть приостановлен.

Получение доступа к экспортным данным

Интернет-сервис размещен на двух зеркалах, расположенных по адресам:

Доступ к Интернет-сервису защищен с помощью логина и пароля. Для получения пароля необходимо написать запрос на [email protected] с email пользователя, зарегистрированного в системе MaxPoster с темой «Доступ к экспортным данным автосалона». В ответ на запрос будет отправлено письмо содержащее:

логин
пароль для доступа
номер текущей версии API

Для получения доступа к ресурсам используйте базовую авторизацию. Пример на PHP:

   $curl = curl_init(); 
   curl_setopt($curl, CURLOPT_USERPWD, "$username:$password"); 
   //…
   $result = curl_exec($curl);

Порядок формирования URL

Интернет-сервис построен на базе архитектуры REST, и использует запросы типа GET и POST. URL формируется следующим образом:

Адрес зеркала (http://export1.maxposter.ru или http://export2.maxposter.ru)
Версия API (например: /api1)
Код автосалона (например: /5)
Идентификатор запрашиваемых данных (например: /vehicles.xml)
Параметры запроса (например: ?page_size=20&page=1)

Пример URL:

http://export1.maxposter.ru/api1/5/vehicles.xml?page_size=20&page=1

Актуальность данных

Ответы Интернет-сервиса сопровождаются заголовками:

Last-Modified - указывается время обновления данных
Expires - указывается время, до которого данные можно помещать в кэш

Данные в формате XML

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

После обновления экспортных данных, время, указанное в заголовке Expires, равно времени обновления данных, указанному в Last-Modified, плюс период обновления данных (Expires = Last-Modified + 1 час). При очередном обновлении экспортных данных система проверит наличие изменений в данных автосалона. Если данные автосалона не изменились, то значение заголовка Last-Modified останется без изменений, но при этом заголовок Expires увеличится так, чтобы указывать на время следующего обновления (т.е. Expires = Last-Modified + 2 часа).

Фотографии

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

Форматы экспортных данных

Марки и модели транспортных средств (marks)

Содержание

XML содержит список марок и моделей автомобилей, продаваемых в настоящий момент автосалоном.

Способ получения

XML возвращается при запросе URL:

http://export1.maxposter.ru/[Код API]/[Код автосалона]/marks.xml

Описание XML

<?xml version="1.0" encoding="UTF-8" ?>
<response id="marks">
  <marks>
     <mark mark_id="[Код марки]">
       <name>[Название марки]</name>
       <count>[Количество активных авто]</count>
       <models>
         <model model_id="[Код модели]">
           <name>[Название модели]</name>
           <count>[Количество активных авто]</count>
         </model>
       </models>     
     </mark>
  </marks>
</response>

Форма поиска транспортного средства (search_form)

Содержание

XML содержит данные, для формирования формы поиска по транспортным средствам.

Способ получения

XML возвращается при запросе URL:

http://export1.maxposter.ru/[Код API]/[Код автосалона]/search_form.xml.

Данные формы установлены в значения по умолчанию.

Описание XML

<?xml version="1.0" encoding="UTF-8" ?>
<response id="search_form">
  <search_form>
    <list name="search[mark_id]" error="[Сообщение об ошибке]">
      <option value="[Код марки]" selected="1">[Название марки]</option>
      ...
    </list>
    <list name="search[model_id]" error="[Сообщение об ошибке]">
      <optgroup mark_id="[Код марки]" label="[Название марки]">
        <option value="[Код модели]" selected="1">[Название модели]</option>
        ...
      </optgroup>
      ...
    </list>
    <field name="search[year][from]" value="[Значение]" size="4" error="[Сообщение об ошибке]"/>
    <field name="search[year][to]" value="[Значение]" size="4" />
    <list name="search[steering_wheel]" error="[Сообщение об ошибке]">
      <option value="[Код расположения руля]" selected="1">[Название способа расположения руля]</option>
      ...
    </list>
    <list name="search[engine_type]" error="[Сообщение об ошибке]">
      <option value="[Код типа двигателя]" selected="1">[Название типа двигателя]</option>
      ...
    </list>
    <list name="search[drive_type]" error="[Сообщение об ошибке]">
      <option value="[Код типа привода]" selected="1">[Название типа привода]</option>
      ...
    </list>
    <list name="search[gearbox_type]" error="[Сообщение об ошибке]">
      <option value="[Код типа КПП]" selected="1">[Название типа КПП]</option>
      ...
    </list>
    <list name="search[body_type]" error="[Сообщение об ошибке]">
      <option value="[Код типа кузова]" selected="1">[Название типа кузова]</option>
      ...
    </list>
    <field name="search[price][from]" value="[Значение]" size="[Макс. количество знаков]" error="[Сообщение об ошибке]" />
    <field name="search[price][to]" value="[Значение]" size="[Макс. количество знаков]" />
    <list name="search[price][unit]" >
      <option value="[Код валюты]" selected="1">[Название валюты]</option>
      ...
    </list>
    <list name="search[availability]" error="[Сообщение об ошибке]">
      <option value="[Код наличия авто]" selected="1">[Наличие авто]</option>
      ...
    </list>
  </search_form>
</response>

Список транспортных средств (vehicles)

Содержание

XML содержит:

Критерии, по которым сформирован список транспортных средств
Перечень транспортных средств, соответствующих заданным критериям

Способ получения

XML возвращается при запросе URL:

http://export1.maxposter.ru/[Код API]/[Код автосалона]/vehicles.xml

Если в запросе методом POST передать параметры для фильтрации списка, то полученный в ответ XML будет cодержать отфильтрованный список транспортных средств. Перечень допустимых параметров и их значения определяется XML Форма поиска транспортного средства.

Параметры page_size (количество элементов на странице, значение по умолчанию 100) и page (страница, значение по умолчанию 1) необходимо передавать как GET, т.е. как часть URL в запросе.

Описание XML

<?xml version="1.0" encoding="UTF-8" ?>
<response id="vehicles">
  <search_form>
    <!—
      См. search_form. Вместо значений по умолчанию расставлены значения запроса.
    -->
  </search_form>
  <vehicles>
    <vehicle vehicle_id="[Код объявления]" dealer_id="[Код автосалона]" type="[Тип тр.средства]">
      <category category_id="[Код категории ТС]">[Категория ТС]</category>
      <mark mark_id="[Код марки]">[Название марки]</mark>
      <model model_id="[Код модели]">[Название модели]</model>
      <year>[Год выпуска]</year>
      <steering_wheel>
        <place steering_wheel_place_id="[Код расположения]">[Расположение руля]</place>
      </steering_wheel>
      <engine>
        <type engine_type_id="[Код типа двигатеся]">[Название типа двигателя]</type>
        <volume unit="cm3">[Объем двигателя в см3]</volume>
        <power unit="hp">[Мощность двигателя в л.с.]</power>
      </engine>
      <drive>
        <type drive_type_id="[Код типа привода]">[Название типа привода]</type>
      </drive>
      <gearbox>
        <type gearbox_type_id="[Код типа КПП]">[Название типа КПП]</type>
      </gearbox>
      <body>
        <type body_type_id="[Код типа кузова]">[Название типа кузова]</type>
        <color body_color_id="[Код цвета]" metallic="[Признак цвета металлик]" >[Название цвета]</color>
      </body>
      <mileage>
        <value unit="[Единица измерения пробега]">[Пробег]</value>
        <without_rus_mileage /><!-- Без пробега по России -->
      </mileage>
      <condition condition_id="[Код состояния автомобиля]">[Название состояния автомобиля]</condition>
      <price status="special"><!-- status="special" только у объявлений помеченных как специальное предложение -->
        <previous>[Предыдущая стоимость тр.средства.]</previous><!-- Может быть указанно, только у объявлений помеченных как специальное предложение -->
        <value unit="[Код валюты]" rub_price="[Стоимость в рублях]">[Стоимость тр.средства]</value>
        <with_discount unit="[Код валюты]" rub_price="[Стоимость в рублях]">[Стоимость тр.средства]</with_discount><!-- Цена со скидкой -->
        <without_customs /><!-- Цена указана без учета таможенных сборов -->
        <import_skip_update_price /><!-- Блок с ценой не изменяется импортом -->
        <updated_by user_id="[Идентификатор пользователя, изменившего цену]">
          <first_name>[Имя пользователя]</first_name><!-- Может отсутствовать -->
          <middle_name>[Имя пользователя]</middle_name><!-- Может отсутствовать -->
          <last_name>[Имя пользователя]</last_name><!-- Может отсутствовать -->
          <post>[Должность сотрудника]</post><!-- Может отсутствовать -->
        </updated_by>
      </price>
      <availability availability_id="[Код начилия]">[Название наличия тр.средства]</availability>
      <stickers>
        <sticker><![CDATA[Стикер]]></sticker>
        <sticker><![CDATA[Стикер]]></sticker>
      </stickers>
      <reserve><status>[true или false]</status></reserve>
      <photo photo_id="[Уникальный код фото]" file_name="[Уникальное имя файла]">
          <thumbnail>[Ссылка на уменьшенное изображение главной фотографии авто]</thumbnail>
      </photo>
      <video video_id="[id video на youtube]">[http ссылка на видео на youtube]</video>
      <vimeo_video video_id="[id video на vimeo]">[http ссылка на видео на vimeo]</video>
      <dates>
        <created_at>[Дата создания объявления в формате ГГГГ-ММ-ДД]</created_at>
        <updated_at>[Дата изменения объявления в формате ГГГГ-ММ-ДД]</updated_at>
        <expires_at>[Срок актуальности объявления в формате ГГГГ-ММ-ДД]</expires_at>
      </dates>
    </vehicle>
    ...
  </vehicles>
</response>

Описание транспортного средства (vehicle)

Содержание

XML содержит полное описание транспортного средства.

Способ получения XML возвращается при запросе URL:

http://export1.maxposter.ru/[Код API]/[Код автосалона]/[Код объявления].xml

Описание XML

<?xml version="1.0" encoding="UTF-8" ?>
<response id="vehicle">
  <vehicle vehicle_id="[Код объявления]" dealer_id="[Код автосалона]" type="[Тип тр.средства]">
    <category category_id="[Код категории ТС]">[Категория ТС]</category>
    <mark mark_id="[Код марки]">[Название марки]</mark>
    <model model_id="[Код модели]">[Название модели]</model>
    <modification modification_id="[Код модификации]">[Название модификации]</modification>
    <complectation complectation_id="[Код комплектации]">[Название комплектации]</complectation><!-- Может отсутствовать -->
    <year>[Год выпуска]</year>
    <brand_color_name>[Наименование цвета, отсутствует если не заполнено, только для "новых" авто]</brand_color_name>
    <brand_color_code>[Код цвета, отсутствует если не заполнено, только для "новых" авто]</brand_color_code>
    <brand_complectation_name>[Наименование комплектации, отсутствует если не заполнено, только для "новых" авто]</brand_complectation_name>
    <brand_complectation_code>[Код комплектации, отсутствует если не заполнено, только для "новых" авто]</brand_complectation_code>
    <steering_wheel>
      <place steering_wheel_palce_id="[Код расположения]">[Расположение руля]</place>
      <power steering_wheel_power_id="[Код типа]">[Название типа усилителя рулевого управления]</power>
      <adjustment steering_wheel_adjustment_id="[Код способа]">[Название способа регулировка руля]</adjustment>
      <heater /><!-- Обогрев руля -->
    </steering_wheel>
    <engine>
      <type engine_type_id="[Код типа двигатеся]">[Название типа двигателя]</type>
      <volume>[Объем двигателя в см3]</volume>
      <power>[Мощность двигателя в л.с.]</power>
      <gas_equipment /><!-- Установлено газоболонное оборудование -->
    </engine>
    <drive>
      <type drive_type_id="[Код типа привода]">[Название типа привода]</type>
    </drive>
    <gearbox>
      <type gearbox_type_id="[Код типа КПП]">[Название типа КПП]</type>
    </gearbox>
    <body>
      <type body_type_id="[Код типа кузова]">[Название типа кузова]</type>
      <color body_color_id="[Код цвета]" metallic="[Признак цвета металлик]" >[Название цвета]</color>
    </body>
    <mileage>
      <value unit="[Единица измерения пробега]">[Пробег]</value>
      <without_rus_mileage /><!-- Без пробега по России -->
    </mileage>
    <condition condition_id="[Код состояния автомобиля]">[Название состояния автомобиля]</condition>
    <vin>[VIN]</vin>
    <warranty>[Дата, по которую действует гарантия производителя на автомобиль, в формате Y-m-d]</warranty>
    <certification_program certification_program_id="[Код сертификационной программы]">
      <name>[Название сертификационной программы]</name>
      <period>[Количество месяцев на которое дается гарантия на данный автомобиль в рамках сертификационной программы]</period>
      <distance>[Пробег в километрах на который дается гарантия на данный автомобиль в рамках сертификационной программы]</distance>
    </certification_program>
    <price>
      <value unit="[Код валюты]" rub_price="[Стоимость в рублях]">[Стоимость тр.средства]</value>
      <with_discount unit="[Код валюты]" rub_price="[Стоимость в рублях]">[Стоимость тр.средства]</with_discount><!-- Цена со скидкой -->
      <without_customs /><!-- Цена указана без учета таможенных сборов -->
      <bargaining /><!-- По цене возможен торг -->
      <import_skip_update_price /><!-- Блок с ценой не изменяется импортом -->
      <updated_by user_id="[Идентификатор пользователя, изменившего цену]">
        <first_name>[Имя пользователя]</first_name><!-- Может отсутствовать -->
        <middle_name>[Имя пользователя]</middle_name><!-- Может отсутствовать -->
        <last_name>[Имя пользователя]</last_name><!-- Может отсутствовать -->
        <post>[Должность сотрудника]</post><!-- Может отсутствовать -->
      </updated_by>
    </price>
    <pts_owner_count value="[Количество владельцев по ПТС, число]">[Количества владельцев по ПТС]</pts_owner_count>
    <availability availability_id="[Код начилия]">[Название наличия тр.средства]</availability>
    <stickers>
      <sticker><![CDATA[Стикер]]></sticker>
      <sticker><![CDATA[Стикер]]></sticker>
    </stickers>
    <reserve>
      <status>[true или false]</status>
      <comment><![CDATA[Текст]]></comment><!-- Может отсутствовать -->
      <expires_at>[Дата завершения резерва в формате ГГГГ-ММ-ДД ЧЧ:ММ:СС]</expires_at><!-- Может отсутствовать -->
    </reserve>
    <armored /><!-- Бронированный автомобиль -->
    <abs /><!-- Есть антиблокировочная система -->
    <asr /><!-- Есть антипробуксовочная система -->
    <cruise_control /><!-- Есть круиз-контроль -->
    <trip_computer /><!-- Есть бортовой компьютер -->
    <parktronic /><!-- Есть парктроник -->
    <esp /><!-- Есть система курсовой стабилизации -->
    <light_alloy_wheels /><!-- Есть литые диски -->
    <sensors>
      <rain /><!-- Есть датчи дождя -->
      <light /><!-- Есть датчик света -->
    </sensors>
    <headlights>
      <xenon /><!-- Есть ксеноновые (или биксеноновые) фары-->
      <washer /><!-- Есть омыватель фар-->
      <adaptive_headlights /><!-- Есть адаптативные фары-->
    </headlights>
    <mirrors>
      <power /><!-- Есть электрозеркала -->
      <defroster /><!-- Есть обогрев зеркал -->
    </mirrors>
    <windows>
      <power window_power_id="[Код электропривода стекол]">[Название электропривода стекол]</power>
      <tinted /><!-- Есть тонированные стекла -->
    </windows>
    <seats>
      <count>[Количество мест, число]</count>
      <heater /><!-- Есть обогрев сидений-->
      <driver_adjustment>[Название способа регулировки сидения]</driver_adjustment>
      <passanger_adjustment>[Название способа регулировки сидения]</passanger_adjustment>
    </seats>
    <pneumosuspension/> <!-- Есть пневмоподвеска -->
    <alarm_system /><!-- Есть охранная сигнализация -->
    <central_lock /><!-- Есть центральный замок -->
    <airbag>[Количество подушек безопасности]</airbag>
    <climate_control>[Название способа управления климатом]</climate_control>
    <multimedia>[Название пакета мультимедиа]</multimedia>
    <compartment>
      <decoration>[Название отедлки салона]</decoration>
      <color>[Оттенок салона]</color>
    </compartment>
    <hatch /><!-- Есть люк -->
    <description>[Дополнительная информация]</description>
    <inspection_place>[Место, где можно осмотреть автомобиль]</inspection_place>
    <contact contact_id="[Код контакта]">
	<name>[Имя контакта]</name>
      <phone from="[Звонить с]" to="[Звонить по]">[Телефон]</phone>
      <phone from="[Звонить с]" to="[Звонить по]">[Телефон]</phone>
      <phone from="[Звонить с]" to="[Звонить по]">[Телефон]</phone>
    <contact>
    <uin>[Код автомобиля в учетной системе рекламодателя]</uin>
    <photos>
      <photo photo_id="[Уникальный код фото]" file_name="[Уникальное имя файла]">
        <thumbnail>[Ссылка на уменьшенное изображение размером 120х90 пикселей]</thumbnail>
        <original>[Ссылка на большое изображение размером 640х400 пикселей]</original>
        <bigsize>[Ссылка на большое изображение размером 2000х1500 пикселей]</bigsize>
      </photo>
      ...
    </photos>
    <video video_id="[id video на youtube]">[http ссылка на видео на youtube]</video>
    <vimeo_video video_id="[id video на vimeo]">[http ссылка на видео на vimeo]</video>
    <options>
      <option>[Название опции]</option>
      ...
    </options>
    <dates>
      <created_at>[Дата создания объявления в формате ГГГГ-ММ-ДД]</created_at>
      <updated_at>[Дата изменения объявления в формате ГГГГ-ММ-ДД]</updated_at>
      <expires_at>[Срок актуальности объявления в формате ГГГГ-ММ-ДД]</expires_at>
    </dates>
  </vehicle>
</response>

Список доступных опций в options

Антиблокировочная система
Антипробуксовочная система
Система курсовой устойчивости
Парктроники передние
Парктроники передние и задние
Парктроники задние
Передние и боковые подушки безопасности
Подушки безопасности водителя и пассажира
Подушки безопасности водителя
Сигнализация с обратной связью
Штатная сигнализация
Иммобилайзер
Дистанционный запуск двигателя
Центральный замок
Кондиционер
Климат-контроль
Климат-контроль 2-зонный
Климат-контроль 3-зонный
Обогрев сидений
Обогрев зеркал
Подогрев руля
Гидроучилитель руля
Электроусилитель руля
Круиз-контроль
Кассетный магнитофон
CD проигрыватель
Телевизор
Бортовой компьютер
Навигационная система
Газобаллонное оборудование
Датчик дождя
Датчик света
Омыватель фар
Электропривод зеркал
Передние электростеклоподъемники
Электростеклоподъемники
Электрорегулировка сиденья водителя
Электрорегулировка сиденья водителя с памятью положения
Электрорегулировка сиденья пассажира
Регулировка сиденья пассажира с памятью положения
Регулировка руля в двух плоскостях
Электрорегулировка руля
Тканевая обивка салона
Велюровая обивка салона
Кожаная обивка салона
Комбинированная обивка салона
Цвет салона: темный
Цвет салона: светлый
Количество мест: <количество мест: 2,4,5,6,7>
Люк на крыше
Тонированные стекла
Ксеноновые фары
Адаптивные фары
Пневмоподвеска
<количество дюймов, от 12 до 28>-дюймовые легкосплавные диски

Описание всех транспортных средств (full_vehicles)

Содержание

XML содержит перечень транспортных средств с полным их описанием.

Способ получения

XML возвращается при запросе URL:

http://export1.maxposter.ru/[Код API]/[Код автосалона]/full_vehicles.xml

Параметры и способ их передачи аналогичны списку транспортных средств (vehicles)

Описание XML

<?xml version="1.0" encoding="UTF-8" ?>
<response id="full_vehicles">
  <vehicles>
    <vehicle vehicle_id="[Код объявления]" dealer_id="[Код автосалона]" type="[Тип тр.средства]">
      <!-- Содержание аналогично содержанию `vehicle` из описания транспортного средства -->
    </vehicle>
  </vehicles>
</response>

Описание всех транспортных средств в архиве (full_vehicles)

Содержание

XML содержит перечень архивных транспортных средств с полным их описанием.

Способ получения

XML возвращается при запросе URL:

http://export1.maxposter.ru/api1/[Код автосалона]/archiv/full_vehicles.xml

Формат аналогичен full_vehicles.xml

Ошибка (error)

Содержание

XML содержит сообщение о возникшей ошибке.

Способ получения

Возвращается при возникновении сбоя при запросе к сервису.

Описание XML

<?xml version="1.0" encoding="UTF-8" ?>
<response id="error">
  <error error_id="[Код ошибки]">[Описание ошибки]</error>
</response>

API автосалона - maxposter/maxDealerAPI GitHub Wiki

Соглашение

Получение доступа к экспортным данным

Порядок формирования URL

Актуальность данных

Данные в формате XML

Фотографии

Форматы экспортных данных

Марки и модели транспортных средств (marks)

Форма поиска транспортного средства (search_form)

Список транспортных средств (vehicles)

Описание транспортного средства (vehicle)

Описание всех транспортных средств (full_vehicles)

Описание всех транспортных средств в архиве (full_vehicles)

Ошибка (error)

⚠️ **GitHub.com Fallback** ⚠️

⚠️ GitHub.com Fallback ⚠️