Интеграция фида: XML, JSON и CSV

Что делает эта интеграция

Интеграция Feed (XML, JSON, CSV) позволяет IVO читать каталог товаров по публичному URL. Вы публикуете файл фида на сайте или сервере, а IVO скачивает его, показывает предпросмотр, сопоставляет ваши поля с полями IVO и синхронизирует каталог через обычный процесс импорта продавца.

Используйте этот вариант, если вы можете генерировать экспорт каталога, но не хотите устанавливать плагин платформы или самостоятельно вызывать Merchant API.

Где настроить

1. Откройте Merchant dashboard.
2. Перейдите в Products и Import history, либо в Settings и Integrations.
3. Нажмите Integrate a feed или New Integration.
4. Выберите Feed (XML, JSON, CSV).
5. Введите URL фида, запустите предпросмотр, проверьте сопоставленные товары и сохраните.

Требования

• Фид должен быть доступен по публичному URL http или https.
• URL должен возвращать содержимое фида напрямую, а не HTML-страницу, страницу входа или промежуточную страницу скачивания.
• IVO должен иметь доступ с User-Agent IVO.md (+https://ivo.md/help/merchant-integration/ivo-md-crawler).
• Желательна кодировка UTF-8. В CSV первая строка должна быть строкой заголовков.
• У каждого товара должны быть минимум название и корректная положительная цена.
• Используйте стабильный SKU или внутренний ID. Это позволяет IVO обновлять то же предложение при следующих синхронизациях.

Как IVO обрабатывает фид

1. IVO скачивает фид и определяет формат.
2. Для JSON и XML IVO ищет список товаров: products, product, offers, offer, RSS channel.item или самый большой вложенный массив товаров.
3. Для CSV IVO определяет разделитель: запятая, точка с запятой, табуляция или вертикальная черта.
4. Предпросмотр читает до 10 товаров и показывает найденные ключи источника.
5. IVO автоматически предлагает сопоставление полей по типовым названиям и значениям.
6. Вы можете изменить сопоставление вручную до сохранения.
7. При синхронизации товары отправляются партиями по 100 и обрабатываются системой импорта продавца.
8. Существующие предложения обновляются по внутреннему ID продавца; новые товары попадают в поток импорта и проверки.

Поддерживаемые форматы

JSON

JSON может быть массивом или объектом со списком товаров. Частые корневые ключи: products, product, offers, offer.

{
  "products": [
    {
      "sku": "SKU-1001",
      "name": "Laptop 14 Ultra",
      "price": "15999 MDL",
      "currency": "MDL",
      "availability": 7,
      "brand": "ExampleBrand",
      "ean": "5940000000011",
      "category": "Laptopuri",
      "description": "Laptop compact cu 16 GB RAM si SSD 512 GB.",
      "images": [
        "https://example.com/images/sku-1001-1.jpg",
        "https://example.com/images/sku-1001-2.jpg"
      ],
      "color": "Silver",
      "memory": "16 GB"
    }
  ]
}

XML

XML может быть простым каталогом или RSS / Google Shopping фидом. Пространства имен вроде g:title поддерживаются и нормализуются при чтении.

<products>
  <product>
    <id>SKU-1001</id>
    <name>Laptop 14 Ultra</name>
    <price>15999</price>
    <currency>MDL</currency>
    <availability>7</availability>
    <brand>ExampleBrand</brand>
    <ean>5940000000011</ean>
    <category>Laptopuri</category>
    <description>Laptop compact cu 16 GB RAM si SSD 512 GB.</description>
    <image>https://example.com/images/sku-1001-1.jpg</image>
    <image_2>https://example.com/images/sku-1001-2.jpg</image_2>
    <color>Silver</color>
  </product>
</products>

CSV

CSV должен содержать заголовки в первой строке. IVO определяет ,, ;, табуляцию и |. Изображения можно передавать в отдельных колонках image_1, image_2 или в одной колонке, разделяя URL пробелами или запятыми.

sku,name,price,currency,availability,brand,ean,category,image_1,image_2,color
SKU-1001,Laptop 14 Ultra,15999,MDL,7,ExampleBrand,5940000000011,Laptopuri,https://example.com/1.jpg,https://example.com/2.jpg,Silver

Рекомендуемые поля

Сопоставление полей

В предпросмотре IVO показывает исходные ключи фида и поля IVO. При стандартных названиях сопоставление обычно заполняется автоматически. Если названия нестандартные, выберите целевое поле вручную.

Несколько ключей можно сопоставить с одним полем IVO. Например, image_1, image_2 и gallery могут идти в image; color и size могут идти в variant_option.

Точки продаж и остатки

Для каждого предложения нужна стратегия остатков. Доступны варианты:

• Одна точка продаж по умолчанию: все товары фида относятся к одной выбранной точке.
• Определенные поля остатков: разные колонки остатков сопоставляются разным точкам, например stock_chisinau и stock_balti.
• Все товары доступны во всех точках: IVO создает наличие для каждой точки и использует значение по умолчанию.

Если включить Out of stock on missing, товары, ранее импортированные этим же фидом, но отсутствующие в последнем запуске, получат остаток 0. Включайте это только для полного фида.

Значения по умолчанию и модификатор цены

Значения по умолчанию заполняют отсутствующую валюту, наличие, бренд, категорию, описание или изображение. Модификатор цены меняет цены при импорте: 10 увеличивает на 10%, -5 уменьшает на 5%.

Правила проверки

• name обязательно.
• price обязательно и должно быть больше нуля.
• Если SKU отсутствует, IVO генерирует стабильный ID из названия, цены, бренда и EAN, но настоящий SKU надежнее.
• LEI, LEU и MDL нормализуются в MDL. Другие валюты должны быть трехбуквенными кодами.
• Есть защитный лимит 5000 сопоставленных товаров за один запуск.
• Изображения должны быть абсолютными URL, доступными для IVO.

Пример PHP: JSON-фид

<?php
header('Content-Type: application/json; charset=utf-8');

$products = [
    [
        'sku' => 'SKU-1001',
        'name' => 'Laptop 14 Ultra',
        'price' => 15999,
        'currency' => 'MDL',
        'availability' => 7,
        'brand' => 'ExampleBrand',
        'ean' => '5940000000011',
        'category' => 'Laptopuri',
        'description' => 'Laptop compact cu 16 GB RAM si SSD 512 GB.',
        'images' => ['https://example.com/images/sku-1001-1.jpg'],
        'color' => 'Silver',
        'memory' => '16 GB',
    ],
];

echo json_encode(['products' => $products], JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES);

Пример Node.js: JSON-фид

import express from 'express';

const app = express();

app.get('/ivo-feed.json', (req, res) => {
  res.type('application/json');
  res.json({
    products: [{
      sku: 'SKU-1001',
      name: 'Laptop 14 Ultra',
      price: 15999,
      currency: 'MDL',
      availability: 7,
      brand: 'ExampleBrand',
      ean: '5940000000011',
      category: 'Laptopuri',
      images: ['https://example.com/images/sku-1001-1.jpg'],
      color: 'Silver'
    }]
  });
});

app.listen(3000);

Пример Python: CSV-фид

from flask import Flask, Response
import csv
import io

app = Flask(__name__)

@app.get('/ivo-feed.csv')
def ivo_feed():
    rows = [{
        'sku': 'SKU-1001',
        'name': 'Laptop 14 Ultra',
        'price': '15999',
        'currency': 'MDL',
        'availability': '7',
        'brand': 'ExampleBrand',
        'ean': '5940000000011',
        'category': 'Laptopuri',
        'image_1': 'https://example.com/images/sku-1001-1.jpg',
        'color': 'Silver'
    }]
    output = io.StringIO()
    writer = csv.DictWriter(output, fieldnames=rows[0].keys())
    writer.writeheader()
    writer.writerows(rows)
    return Response(output.getvalue(), mimetype='text/csv; charset=utf-8')

Частые ошибки

• Слишком общие названия товаров, например Чехол или Кабель. Добавляйте бренд, модель и вариант.
• Изменение SKU между синхронизациями. Держите их стабильными.
• Относительные пути изображений вроде /image.jpg. Используйте полный URL.
• Фид защищен логином или блокирует crawler IVO.
• Включение Out of stock on missing при частичном фиде.
• Объединение разных товаров как вариантов. Объединяйте только настоящие варианты одного товара.

После сохранения

Первая синхронизация запускается после сохранения активной интеграции. Позже можно открыть Settings > Integrations и запустить синхронизацию вручную. Прогресс и ошибки отображаются в Products > Import history.