Документация разработчика

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

• Изучить лучшие практики по оформлению товарного фида
• Познакомиться со структурой YML-файла
• Узнать больше о тегах и их атрибутах
• Посмотреть примеры фидов

Формирование YML фида

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

При этом в упрощённом типе производитель, тип и название товара указываются в одном элементе name. В произвольном типе эти данные надо указывать в отдельных элементах type, typePrefix, vendor, model.

Tip

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

Структура упрощённого формата

Подробное описание элементов

shop ── offers

Примеры фида

• Фид упрощённого формата
• Фид упрощённого формата с доставкой

Иерархия тегов

`yml_catalog`
└── `shop`
    ├── `name`
    ├── `company`
    ├── `url`
    ├── `currencies`
    │   └── `currency`
    │       ├── `id`
    │       └── `rate`
    ├── `categories`
    │   └── `category`
    │       ├── `id`
    │       ├── `parentId` (опционально)
    │       └── `name`
    ├── `delivery` (опционально)
    ├── `delivery-options` (опционально)
    │   └── `option`
    │       ├── `cost`
    │       └── `days`
    ├── `promos` (опционально)
    |   └── `promo`
    |       ├── `id`
    |       ├── `type`
    |       ├── `start-date`
    |       ├── `end-date`
    |       ├── `promo-code`
    |       ├── `discount`
    |       |   ├── `unit`
    |       |   └── `currency` (если unit не указан, скидка в рублях)
    |       ├── `url`
    |       └── `purchase`
    |           └── `product`
    |               └── `offer-id`
    └── `offers`
        └── `offer`
            ├── `id`
            ├── `name` (также влияет на попадание в Объединённую карточку товара)
            ├── `vendor` (также влияет на попадание в Объединённую карточку товара)
            ├── `vendorCode` (опционально, влияет на попадание в Объединённую карточку товара)
            ├── `url`
            ├── `price`
            ├── `oldprice` (опционально)
            ├── `enable_auto_discounts` (опционально)
            ├── `currencyId`
            ├── `categoryId`
            ├── `available`(опционально)
            ├── `picture` (может быть несколько, влияет на попадание в Объединённую карточку товара)
            ├── `delivery`(опционально)
            ├── `delivery-options` (обязательно при delivery со значением true)
            │   └── `option`
            │       ├── `cost`
            │       ├── `days`
            │       └── `order-before`
            ├── `pickup` (опционально)
            ├── `pickup-options` (обязательно при pickup со значением true)
            |   └── `option`
            |       ├── `cost`
            |       └── `days`
            ├── `description`(также влияет на попадание в Объединённую карточку товара)
            ├── `sales_notes` (опционально)
            ├── `adult` (опционально)
            ├── `manufacturer_warranty` (опционально)
            ├── `barcode` (опционально, влияет на попадание в Объединённую карточку товара)
            ├── `param` (может быть несколько, влияет на попадание в Объединённую карточку товара)
            │   ├── `name`
            │   └── `unit` (опционально)
            ├── `weight` (опционально)
            ├── `dimensions` (опционально)
            ├── `period-of-validity-days` (опционально)
            ├── `comment-validity-days` (опционально)
            ├── `service-life-days` (опционально)
            ├── `comment-life-days` (опционально)
            ├── `warranty-days` (опционально)
            ├── `comment-warranty` (опционально)
            ├── `certificate` (опционально)
            ├── `tn-ved-code` (опционально)
            └── `condition` (опционально)
                ├── `type`
                ├── `quality`
                └── `reason`

Структура произвольного формата

Подробное описание элементов

shop ── offers

Пример фида

• Фид произвольного формата

Иерархия тегов

`yml_catalog`
└── `shop`
    ├── `name`
    ├── `company`
    ├── `url`
    ├── `currencies`
    │   └── `currency`
    │       ├── `id`
    │       └── `rate`
    ├── `categories`
    │   └── `category`
    │       ├── `id`
    │       ├── `parentId` (опционально)
    │       └── `name`
    ├── `delivery-options` (опционально)
    │   └── `option`
    │       ├── `cost`
    │       └── `days`
    ├── `promos` (опционально)
    |   └── `promo`
    |       ├── `id`
    |       ├── `type`
    |       ├── `start-date`
    |       ├── `end-date`
    |       ├── `promo-code`
    |       ├── `discount`
    |       |   ├── `unit`
    |       |   └── `currency` (если unit не указан, скидка в рублях)
    |       ├── `url`
    |       └── `purchase`
    |           └── `product`
    |               └── `offer-id`
    └── `offers`
        └── `offer`
            ├── `id`
            ├── `type` (vendor.model)
            ├── `typePrefix`
            ├── `model`
            ├── `vendor` (также влияет на попадание в Объединённую карточку товара)
            ├── `vendorCode` (опционально, влияет на попадание в Объединённую карточку товара)
            ├── `url`
            ├── `price`
            ├── `oldprice` (опционально)
            ├── `enable_auto_discounts` (опционально)
            ├── `currencyId`
            ├── `categoryId`
            ├── `available`(опционально)
            ├── `picture` (может быть несколько, влияет на попадание в Объединённую карточку товара)
            ├── `delivery`(опционально)
            ├── `delivery-options` (обязательно при delivery со значением true)
            │   └── `option`
            │       ├── `cost`
            │       ├── `days`
            │       └── `order-before`
            ├── `pickup` (опционально)
            ├── `pickup-options` (обязательно при pickup со значением true)
            |   └── `option`
            |       ├── `cost`
            |       └── `days`
            ├── `description`(также влияет на попадание в Объединённую карточку товара)
            ├── `sales_notes` (опционально)
            ├── `adult` (опционально)
            ├── `manufacturer_warranty` (опционально)
            ├── `barcode` (опционально, влияет на попадание в Объединённую карточку товара)
            ├── `param` (может быть несколько, влияет на попадание в Объединённую карточку товара)
            │   ├── `name`
            │   └── `unit` (опционально)
            ├── `weight` (опционально)
            ├── `dimensions` (опционально)
            ├── `period-of-validity-days` (опционально)
            ├── `comment-validity-days` (опционально)
            ├── `service-life-days` (опционально)
            ├── `comment-life-days` (опционально)
            ├── `warranty-days` (опционально)
            ├── `comment-warranty` (опционально)
            ├── `certificate` (опционально)
            ├── `tn-ved-code` (опционально)
            └── `condition` (опционально)
                ├── `type`
                ├── `quality`
                └── `reason`

Информация о товарах (offers, offer)

В YML-файле список всех предложений магазина должен содержаться в элементе offers. Каждое предложение описывается в элементе offer, который может быть упрощённого или произвольного типа.

Упрощённый и Произвольный типы

В упрощённом и произвольном типе по-разному формируется название предложения, хотя остальной набор элементов совпадает.

Упрощённый тип: название предложения — name

• Полное название товара (тип, производитель и модель) указывается в элементе name.
• Полное описание упрощённого типа

Произвольный тип: название предложения — typePrefix + vendor + model

• Название товара составляется из трех элементов: typePrefix (тип товара), vendor (производитель) и model (модель).
• Для отличия произвольного типа от упрощённого, к элементу offer нужно добавить атрибут type="vendor.model".

Warning

В произвольном типе элементы vendor (производитель товара) и model (модель товара) обязательны. Если этих характеристик нет у вашего предложения, используйте Упрощённый тип.

Как выбрать между Упрощённым и Произвольным форматами?

Выбор между упрощённым и произвольным форматами зависит от особенностей вашей базы данных и ассортимента товаров. Если информация о типе, производителе и модели товара хранится раздельно или требуется более подробное описание каждого товара, Произвольный тип может быть более предпочтителен. Однако для большинства магазинов Упрощённый тип предоставляет достаточный уровень детализации при более простой подготовке данных.

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

Обратная Связь

Если у вас есть вопросы или предложения по улучшению документации, пожалуйста, создайте issue.

Если у вас есть вопросы по проверке фида, заполните, пожалуйста, форму обратной связи — ваше обращение попадёт к профильным специалистам.