+7 (812) 600-76-17
+7 (499) 649-38-38

Описание формата данных CarCopy.ru

Разработчики: Константин Денисов, Павел Светлов, Роман Хоничев

Обновлено:

Содержание

  1. Комментарий
    1. Документация
    2. Изменения в документации
    3. Версия документации
  2. Передача данных
    1. Набор данных
      1. XML файл
      2. ZIP архив
    2. Импорт данных
      1. Через FTP сервер
      2. Через веб-интерфейс
    3. Экспорт данных
      1. Выгрузка файла на FTP сервер
      2. Через веб-интерфейс
  3. Общие сведения о формате CarCopy
    1. Обязательные и рекомендуемые данные
    2. Требование к кодировке
    3. Требование к изображениям
    4. Содержание главной секции
    5. Структура XML файла в формате CarCopy
  4. Описание данных
    1. Таблица: структура секции <seller>...</seller>
    2. Таблица: структура секции <offer>...</offer>
      1. Таблица: структура секции <offer><badges>...<badges></offer>
      2. Таблица: структура секции <offer><equipment-id>...<equipment-id></offer>
      3. Таблица: структура секции <offer><publications>...<publications></offer>
      4. Таблица: структура секции <offer><photos>...<photos></offer>
    3. Справочные данные
      1. Справочные данные category, color, body-type, engine-type, transmission, equipment
      2. Справочные данные make
      3. Справочные данные country, city
      4. Справочные данные equipment-code
      5. Справочные данные interior-code
  5. Пример данных
  6. История изменений

Комментарий

Документация

Настоящая документация описывает все принципы обмена данными с системой CarCopy.ru в формате CarCopy. Документация предназначена для разработчиков и включает в себя все необходимые наборы данных, а также необходимые ссылки на специальную справочную информацию. Все правила, описанные в настоящей документации, вступают в силу, начиная с 20 марта 2009 года.

Изменения в документации

Все изменения и дополнения содержатся в §6. История изменений настоящей документации.

Версия документации

ВАЖНО: Убедитесь, что работаете с последней версией документации.
Актуальная версия документации доступна по адресу: http://docs.carcopy.ru/format.html

Передача данных

Набор данных

Файл в формате XML со ссылками на изображения. Набор данных может быть в двух видах:

XML файл

Файл со ссылками на изображения на внешнем источнике. Например: file.xml (имя файла произвольное).

ZIP архив

Архив, состоящий из XML файла и набора изображений. Например, simple.zip, состоящий из: file.xml, image_1.jpg, image_2.jpg, image_3.jpg.
Имя ZIP архива, имя XML файла, имена изображений — произвольные.

Импорт данных

Вне зависимости от типа данных в файле содержатся данные по одному дилеру.

Через FTP сервер

Через веб-интерфейс

Экспорт данных

Выгрузка файла на FTP сервер

Через веб-интерфейс

Общие сведения о формате CarCopy

Обязательные и рекомендуемые данные

В настоящей документации все ОБЯЗАТЕЛЬНЫЕ для передачи данные выделены красным жирным шрифтом.
Если для дальнейшей передачи на какой-либо сайт, подключенный к системе CarCopy, данных в объявлении будет недостаточно, такое объявление передаваться не будет.

Требование к кодировке

Файл simple.xml должен быть ОБЯЗАТЕЛЬНО в кодировке UTF-8.

Требование к изображениям

Изображения должны быть в формате jpg, gif или png.
Размер изображений должен быть не менее 920 пикселей по ширине и не менее 700 пикселей по высоте.

Содержание главной секции

Структура XML файла в формате CarCopy


<?xml version="1.0" encoding="utf-8"?>
<carcopy version="2">
  <!-- Дата создания файла -->
  <creation-date>25 Mar 2011 06:03:58 GMT+0</creation-date>

  <!-- Список объявлений -->
  <offers>
    <offer>
      <id>4454645</id>
      <seller-id>116</seller-id>
      <seller-key>250</seller-key>
      <date/>
      <valid-thru-date/>
      <type>Легковой</type>
      <category>подержанный</category>
      <body-type>Седан</body-type>
      <engine-type>Турбодизель</engine-type>
      <make-id>66</make-id>
      <make>Toyota</make>
      <model>Corolla</model>
      <version>1.4 D-4D (90 Hp)</version>
      <year>2008</year>
      <price>1500000</price>
      <currency-type>RUR</currency-type>
      <haggle>no</haggle>
      <run>123456</run>
      <run-metric>km</run-metric>
      <vin>XWF0AHL48A0003925</vin>
      <body-number>TD62WYMZR-G2</body-number>
      <color>черный</color>
      <color-metallic>yes</color-metallic>
      <doors>4</doors>
      <power>90</power>
      <power-metric>hp</power-metric>
      <transmission>Автомат вариатор</transmission>
      <transmission-steps/>
      <cubic-capacity>1364</cubic-capacity>
      <drive>Передний</drive>
      <custom-clean>yes</custom-clean>
      <steering-wheel>L</steering-wheel>
      <seller-phone/>
      <seller-contact/>
      <accident>no</accident>
      <condition/>
      <presence>На заказ</presence>
      <comment>Автомобиль в наличии в Томске!</comment>

      <equipment>Антиблокировочная система (ABS)</equipment>
      <equipment-id>
        <item>1</item>
      </equipment-id>

      <photos root="http://carcopy.ru/">
        <photo>image.php?seller_id=116&vehicle_id=4454645&orig=1&image=1</photo>
        <photo>image.php?seller_id=116&vehicle_id=4454645&orig=1&image=2</photo>
        <photo>image.php?seller_id=116&vehicle_id=4454645&orig=1&image=3</photo>
        <photo>image.php?seller_id=116&vehicle_id=4454645&orig=1&image=4</photo>
        <photo>image.php?seller_id=116&vehicle_id=4454645&orig=1&image=5</photo>
        <photo>image.php?seller_id=116&vehicle_id=4454645&orig=1&image=65</photo>
      </photos>

      <publications>
        <publication for="auto.ru" name="special"/>
        <publication for="auto.ru" name="export"/>
        <publication for="auto.ru" name="premium"/>
        <publication for="auto.ru" name="premium_offer"/>
        <publication for="auto.ru" name="disable_upload"/>
      </publications>

      <badges>
        <badge>Камера заднего вида</badge>
      </badges>

      <warranty-expire>12-2020</warranty-expire>
    </offer>
  </offers>

  <!-- Список продавцов -->
  <sellers>
    <seller>
      <id>116</id>
      <login/>
      <password/>
      <name>"Digiboo Ltd."</name>
      <country-id>335</country-id>
      <country>Албания</country>
      <city-id>no city</city-id>
      <city/>
      <address>Babkin st.</address>
      <phone>+7 (911) 5555555</phone>
      <phone>+7 (921) 6666666</phone>
      <fax>+7 (000) 000</fax>
      <contact>Digiboo</contact>
      <email>info@carcopy.ru</email>
      <url/>
    </seller>
  </sellers>
</carcopy>
      

Примечания:

  • Данные о разных продавцах могут содержаться в наборе данных <sellers> (в данный момент не используется)
  • Каждый из наборов данных <seller>...</seller> соответствует отдельному продавцу. Не является обязательным, если существует другой механизм идентификации продавца в системе CarCopy

Описание данных

Таблица: структура секции <seller>...</seller>

Тег Тип Пример Описание
<login> Текст vasiliypoupkine Логин. Может использоваться для разных систем
<password> Текст Qwerty123 Пароль. Может использоваться для разных систем
<id> Целое число 12345 Идентификатор продавца
<name> Текст WorldWideCars Ltd. Название компании продавца
<country> Текст Россия Страна местонахождения продавца (если не указан <country-id>)
<city> Текст Санкт-Петербург Город местонахождения продавца (если не указан <city-id>)
<address> Текст ул. Ленина 21 Улица, номер дома и т.д., местонахождения продавца
<info> Текст Продажа авто с пробегом Дополнительное описание (информация) о продавце
<phone> Текст +7 (812) 111-0000 Основной номер телефона.
Допустимые символы: цифры 0–9, + - ( ). Может быть 2 основных номера
<fax> Текст +7 (812) 111-0001 Номер факса.
Допустимые символы: цифры 0–9, + - ( )
<contact> Текст Василий Пупкин Имя контактного лица компании
<email> Текст info@site.ru Адрес электронной почты компании в системе
<url> Текст site.ru Адрес сайта продавца в интернете

Таблица: структура секции <offer>...</offer>

Тег Тип Пример Описание
<id> Целое число 12345 Идентификатор объявления в системе
<date> Дата Дата объявления
<seller-id> Целое число 12345 Идентификатор продавца в системе CarCopy
<valid-thru-date> Дата Дата, до которой объявление действительно
<seller-key> Текст 123RRT Номер предложения в системе продавца
<seller-phone> Текст +7 (812) 222-0000 Номер телефона для конкретного объявления (если отличается от основного).
Допустимые символы: цифры 0–9, + - ( )
<seller-contact> Текст Иван Иванов Контактное лицо для конкретного объявления (если отличается от основного).
<type> Текст Легковой Тип транспортного средства (легковой, грузовой...)
<category> Текст Подержанный Категория транспортного средства
<make> Текст VW Общепринятое написание марки транспортного средства
<model> Текст Golf IV Общепринятое название модели транспортного средства
<version> Текст Highline 1,6 Версия транспортного средства (Модификация ТС)
<complectation> Текст Престиж Название комплектации ТС
<modification-code>** Текст ACC16K5RB Код модификации от производителя
<year> Целое число 2003 Год выпуска транспортного средства
<registration_year> Целое число 2015 Год регистрации транспортного средства
<price> Целое число 1000000 Цена транспортного средства
<currency-type> Одно из:
RUR
EUR
USD
RUR Валюта.
RUR — рубль РФ
EUR — Евро
USD — доллар США
<location-address> Текст Санкт-Петербург, Екатерининский пр., 3 Место осмотра транспортного средства
<haggle> yes или no yes Возможен торг:
yes — да
no — нет (по умолчанию)
<run> Целое число 120000 Пробег транспортного средства (для автомобилей с пробегом)
<run-metric> km или mile km km — километр
mile — миля (1609 km)
(для автомобилей с пробегом)
<steering-wheel> L или R L Рулевое колесо:

L — слева (по умолчанию)

R — справа
<owners> Целое число 2 Количество владельцев транспортного средства
<vin> Текст XWF0AHL48A0003925 Идентификационный номер транспортного средства
<body-number> Текст TD62WYMZR-G2 Номер кузова транспортного средства
<color> Текст Синий Цвет транспортного средства
<color-metallic> yes или no no Цвет металлик:
yes — да
no — нет (по умолчанию)
<color-code>** Текст Белый лед (369) Код цвета автомобиля по каталогу производителя
<body-code> Текст Хэтчбек Тип кузова транспортного средства
<doors> Целое число 3 Количество дверей
<interior> Текст Черная ткань Цвет и обшивка салона транспортного средства
<engine-type> Текст бензин Тип двигателя
<power> Целое число 101 Мощность двигателя
<power-metric> hp или kw hp Единицы измерения мощности:
hp — лошадиные силы (по умолчанию)
kw — киловатт (1.359 * hp)
<transmission> Текст механическая Коробка передач
<transmission-steps> Целое число 5 Количество передач в коробке
<cubic-capacity> Целое число 1599 Объем двигателя в см3
<exchange> Текст Обмен не интересует
Рассмотрю варианты обмена
Варианты обмена
<custom-clean> yes или no yes Растаможен:
yes — да
no — нет
Указывается, только если автомобиль ввезён
<accident> yes или no no Аварийный:
yes — да
no — нет (по умолчанию)
<comment> Текст Любой текст Дополнительное описание
<equipment> Текст центральный замок, гидроусилитель руля, ABS Опции транспортного средства через запятую
(если не указана секция <equipment-id>)
<equipment-code>** Текст PRUPTE Код опций автомобиля по каталогу производителя
<interior-code>** Текст ACCESS Код интерьера автомобиля по каталогу производителя
<drive> Текст передний Тип привода (если не указан <drive-id>):
передний
задний
полный
<condition> Одно из:
Отличное

Хорошее

Среднее

Требует ремонта
Отличное Состояние транспортного средства
<presence> Одно из:
В наличии
В пути
На заказ
В наличии Наличие транспортного средства
<certified_used_car> yes или no
1 или 0
yes Сертифицированное производителем транспортное средство
<sts> Текст 00 АА 123456 Серия и номер свидетельства транспортного средства
(только кириллические символы!)
<pts> Текст Оригинал Данные о паспорте транспортного средства:
Оригинал
Дубликат
Не указано
<external_video_url> URL https://www.youtube.com/watch?v=QH2-TGUlwu4 Ссылка на видеоролик
<discount-price> Целое число 999000 Цена транспортного средства по акции
<credit-discount> Целое число > 1500 50000 Сумма скидки при покупке в кредит
<insurance-discount> Целое число > 1500 30000 Сумма скидки при покупке страховки
<tradein-discount> Целое число > 1500 70000 Сумма скидки при покупке по программе trade-in
<max-discount> Целое число > 1500 200000 Максимальная сумма скидки
<discount-price-reason> 350*
351*
352*
353*
354*
350 Причина скидки
<warranty-expire> мм-гггг 12-2020 Гарантия на транспортное средство

Примечания:

  • 350* — цена при продаже старого автомобиля по системе Trade-in
  • 351* — цена при покупке в кредит
  • 352* - цена по специальной акции импортера (скидка от представительства бренда)
  • 353* — скидка за лояльность (повторная покупка у дилера)
  • 354* — скидка по программе утилизации
  • ** — значения <modification-code>, <color-code>, <equipment-code>, <interior-code> обязательны для Легковых Новых

Таблица: структура секции <offer><badges>...<badges></offer>

Секция предназначена для передачи стикеров на сайт auto.ru. Максимум 3 стикера по 25 символов

Тег Тип Пример Описание
<badge> Текст Камера заднего вида Стикер для площадки auto.ru; до 25 символов

Таблица: структура секции <offer><equipment-id>...<equipment-id></offer>

Тег Тип Пример Описание
<item> Целое число 2 Опция транспортного средства.
Повторяется для каждой опции

Таблица: структура секции <offer><publications>...<publications></offer>

Секция предназначена для автоматического выделения конкретного объявления в общем списке.

Тег Атрибут for Атрибут name Описание
<publication> Тип площадки Значение для площадки
(см. Описание)
export — для обязательной выгрузки на сайт
premium — премиум-объявление
special — спецпредложение

exchange — обмен
fresh — поднятие в поиске
disable_upload — отключить отгрузку ТС на площадку

Примечания:

Например, ваш автосалон загружает в CarCopy 100 объявлений, а для выгрузки на auto.ru у вашего салона имеется аккаунт на 50 объявлений. Таким образом, если при передаче в CarCopy будут отмечены необходимые 50 объявлений из 100 для сайта auto.ru, то они и только они будут выгружены на площадку.
По умолчанию, будут переданы первые 50 объявлений из списка.

Таблица: структура секции <offer><photos>...<photos></offer>

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

Тег Атрибут root Пример Описание
<photos> URL https://site.ru/item_001/
 Ссылка на папку с изображениями.
Если изображения прикладываются в ZIP архиве, то root=""

Тег Тип Пример Описание
<photo> Текст img1.jpg Имя изображения

Теги <category-id>, <make-id>, <color-id>, <body-type-id>, <engine-type-id>, <transmission-id>, <equipment-id>, <drive-id> используются для чтения при экспорте файла.

Пример данных

При необходимости запрашивайте по адресу: info@carcopy.ru

История изменений

[10.08.2018] Обновлен тег <complectation>, <max-discount> : Название комплектации, сумма скидки

[26.06.2018] Обновлены ссылки на каталоги, добавлен тег <interior> : Описание обшивки салона

[31.05.2018] Добавлен справочник по коду интерьера. §4.3.5

[18.04.2018] Добавлен справочник по коду комплектации. §4.3.4

[18.04.2018] Добавлен тег <warranty-expire> : Срок гарантии ТС

[19.03.2018] Добавлен тег <badges> : Стикеры для auto.ru

[19.03.2018] Добавлены теги <credit-discount>, <insurance-discount>, <tradein-discount> : Скидка при покупке

[07.02.2018] Добавлен тег <pts> : Данные о ПТС

[24.01.2018] Добавлен тег <body-number> : Номер кузова ТС

[30.11.2017] Добавлен тег <disable_upload> : Убрать ТС из выгрузки

[15.11.2017] Добавлены теги <modification-code>, <color-code>, <equipment-code>, <interior-code> : Коды по каталогу производителя для новых ТС

[07.09.2017] Удалены неиспользуемые теги <premium_offer>, <hcolor> : Дополнительные услуги

[17.02.2017] Добавлены теги <discount-price>, <discount-price-reason> : Цена по акции

[02.02.2017] Добавлен тег <exchange> : Вариант обмена

[17.10.2016] Добавлены теги <premium>, <premium_offer> : Дополнительные услуги для auto.ru

[25.08.2016] Добавлены теги <fresh>, <top> : Дополнительные услуги для auto.ru

[12.02.2016] Добавлены теги <external_video_url/>, <certified_used_car/>, <sts/>. Обновлены ссылки на справочники : Удалены дублирующие теги

[14.07.2015] Изменен пункт §4.3.4 : Удалены лишние справочники

[14.07.2015] Изменен пункт §4.3.2 : Справочники марок и моделей

[21.01.2013] Обязательные поля: <power> : Мощность

[12.04.2011] Добавлены возможности выделения цветом и спецпредложений на сайте cars.ru : Таблица SITE: допустимые значения

[06.04.2011] Добавлен тег <location-address> : Место осмотра ТС

[29.03.2011] Добавлен тег <owners> : Количество владельцев

[25.03.2011] Добавлена секция <offer> / <publications>

[25.03.2011] Удалена секция <offer> / <export> : Вместо нее сделана секция <offer> / <publications>

[25.03.2011] Добавлен тег <presence> в секции <offer>...</offer> : Наличие ТС

[25.03.2011] Добавлен тег <condition> в секции <offer>...</offer> : Состояние ТС

[25.03.2011] Добавлен тег <type> и <type-id> в секции <offer>...</offer> : Тип ТС (Легковой, грузовой...)

[25.03.2011] Изменено значение тега <category> и <category-id> : Категория транспортного средства

[25.03.2011] Дополнен тег <seller-id> в секции <offer>...</offer>

[10.05.2010] Добавлена секция <offer> / <export> и справочная таблица SITE

[10.05.2010] Установлен новый набор рекомендуемых наборов данных. §3.1

[07.05.2010] Добавлены обязательные теги, описывающие привод автомобиля: <drive-id> либо <drive> : Обязательные теги

[12.03.2009] Добавлены справочники: carcopy_ref.xml, make.xml, country.xml

[12.03.2009] Исправлена нумерация в оглавлении