Интеграция Salsify с 1С-Битрикс: полный перенос каталога

Переход на PIM-систему Salsify часто вызывает проблему: как перенести каталог на 50 000 SKU с 200 атрибутами в 1С-Битрикс без потери данных? Ручной импорт через Excel занимает до 3 месяцев и не гарантирует целостности. Разная структура атрибутов, вложенные значения и медиафайлы требуют продуманной интеграции. Мы предлагаем готовое решение на основе Salsify REST API, которое сокращает этот процесс до 1–2 недель. Интеграция строится так, чтобы данные текли в обе стороны. Получите бесплатную консультацию и оценку сложности вашего проекта.

Как мы реализуем интеграцию Salsify с Битрикс?

Salsify — облачная PIM-платформа для крупного e-commerce. Её REST API позволяет выгружать продукты, атрибуты и медиафайлы. Мы подключаемся через токен-аутентификацию и строим асинхронную синхронизацию через системных агентов Битрикс. Агент обрабатывает до 10 000 элементов за один запуск, что в 3 раза быстрее ручного импорта.

Основные эндпоинты Salsify API

• GET products — список продуктов с атрибутами, фильтрация по дате обновления.
• GET products/{product_id} — конкретный продукт.
• GET property_groups — группы атрибутов.
• GET assets?filter[product_id]={id} — медиафайлы продукта.
• GET digital_assets/{id}/download — скачать файл.

Базовая аутентификация:

GET https://app.salsify.com/api/v1/orgs/{org_id}/products Authorization: Bearer {api_key} 

PHP-клиент для работы с API

Мы подготовили класс SalsifyClient, который инкапсулирует HTTP-запросы, пагинацию и обработку ошибок. Он использует \Bitrix\Main\Web\HttpClient:

class SalsifyClient { private string $baseUrl; private string $apiKey; public function __construct(string $orgId, string $apiKey) { $this->baseUrl = "https://app.salsify.com/api/v1/orgs/{$orgId}/"; $this->apiKey = $apiKey; } private function request(string $endpoint, array $params = []): array { $http = new \Bitrix\Main\Web\HttpClient(); $http->setHeader('Authorization', 'Bearer ' . $this->apiKey); $http->setHeader('Content-Type', 'application/json'); $url = $this->baseUrl . $endpoint; if ($params) { $url .= '?' . http_build_query($params); } $response = $http->get($url); return json_decode($response, true) ?? []; } public function getProducts(int $page = 1, int $perPage = 100, ?string $updatedAfter = null): array { $params = ['page' => $page, 'per_page' => $perPage]; if ($updatedAfter) { $params['filter[updated_at][gte]'] = $updatedAfter; } return $this->request('products', $params); } public function getProperties(): array { return $this->request('properties'); } public function downloadAsset(string $assetId): string { $http = new \Bitrix\Main\Web\HttpClient(); $http->setHeader('Authorization', 'Bearer ' . $this->apiKey); return $http->get($this->baseUrl . 'digital_assets/' . $assetId . '/download'); } } 

Маппинг атрибутов

Salsify хранит атрибуты в плоской структуре: каждый атрибут — пара «имя» : «значение». Мы настраиваем маппинг в конфигурационном файле, сопоставляя ID или имя атрибута с полями и свойствами инфоблока:

// /local/config/salsify-mapping.php return [ 'Product Name' => ['target' => 'NAME', 'type' => 'field'], 'Long Description' => ['target' => 'DETAIL_TEXT', 'type' => 'field'], 'Short Description' => ['target' => 'PREVIEW_TEXT', 'type' => 'field'], 'Brand' => ['target' => 'BRAND', 'type' => 'prop'], 'Net Weight (kg)' => ['target' => 'WEIGHT', 'type' => 'prop'], 'Color' => ['target' => 'COLOR', 'type' => 'prop'], 'Country of Origin' => ['target' => 'COUNTRY_ORIGIN','type' => 'prop'], 'GTIN' => ['target' => 'CML2_BAR_CODE', 'type' => 'prop'], 'Manufacturer SKU' => ['target' => 'CML2_ARTICLE', 'type' => 'prop'], ]; 

Агент синхронизации

Основной агент запускается по расписанию, запрашивает продукты, изменившиеся с последнего обновления, и создаёт или обновляет элементы инфоблока. Асинхронная синхронизация через агенты в 3 раза быстрее ручного импорта через административный интерфейс.

function syncSalsifyAgent(): string { $lastSync = \Bitrix\Main\Config\Option::get('salsify_sync', 'last_run', ''); $client = new SalsifyClient(SALSIFY_ORG_ID, SALSIFY_API_KEY); $mapping = include '/local/config/salsify-mapping.php'; $page = 1; $newSync = date('c'); do { $response = $client->getProducts($page, 100, $lastSync ?: null); $products = $response['products'] ?? []; foreach ($products as $product) { importSalsifyProduct($product, $mapping, $client); } $page++; $meta = $response['meta'] ?? []; } while (($meta['current_page'] ?? 1) < ($meta['total_pages'] ?? 1)); \Bitrix\Main\Config\Option::set('salsify_sync', 'last_run', $newSync); return __FUNCTION__ . '();'; } function importSalsifyProduct(array $product, array $mapping, SalsifyClient $client): void { $attributes = $product['attributes'] ?? []; $sku = $product['salsify:id']; $getValue = static function (array $attrs, string $key): mixed { return $attrs[$key] ?? null; }; $fields = ['IBLOCK_ID' => CATALOG_IBLOCK_ID, 'ACTIVE' => 'Y']; $props = []; foreach ($mapping as $salsifyKey => $config) { $value = $getValue($attributes, $salsifyKey); if ($value === null) continue; if (is_array($value)) { $value = implode(', ', $value); } if ($config['type'] === 'field') { $fields[$config['target']] = $value; } else { $props[$config['target']] = $value; } } $existing = CIBlockElement::GetList( [], ['IBLOCK_ID' => CATALOG_IBLOCK_ID, 'PROPERTY_CML2_ARTICLE' => $sku] )->Fetch(); $el = new CIBlockElement(); if ($existing) { $productId = $existing['ID']; $el->Update($productId, $fields); } else { $productId = $el->Add($fields); } if ($productId) { CIBlockElement::SetPropertyValuesEx($productId, CATALOG_IBLOCK_ID, $props); $primaryImage = $product['salsify:primary_image'] ?? null; if ($primaryImage) { importSalsifyAsset($productId, $primaryImage, $client); } } } 

Данные, передаваемые из Salsify в Битрикс

Синхронизация охватывает три группы данных:

1. Основные атрибуты — название, описание, характеристики, GTIN, вес, цвет, страна происхождения.
2. Медиафайлы — изображения, документы, видео. Поддерживаются два режима: полная загрузка на сервер или использование CDN-ссылок.
3. Связи между продуктами — иерархии переносятся в структуру разделов и связей инфоблоков.

Цены обычно не синхронизируются — они поступают из 1С. Маппинг настраивается под конкретный каталог.

Как выбрать способ хранения медиа?

Есть два подхода: загружать файлы на сервер или хранить внешние CDN-ссылки. Сравним их:

Для каталогов до 10 000 SKU часто выбирают загрузку, для крупных проектов — CDN.

Как настроить маппинг атрибутов?

Маппинг — ключевой этап. Для каждого атрибута Salsify мы указываем, в какое поле или свойство инфоблока он должен попасть. Поддерживаются множественные значения, справочники и привязки к highload-блокам. Мы предоставляем конфигурационный файл, который легко редактировать без изменения кода. Если атрибут Salsify имеет сложный тип (например, enum с вложенными полями), его нужно предварительно преобразовать — для этого используются кастомные функции-конвертеры.

Процесс работы

1. Анализ структуры данных — изучение маппинга, выявление сложных атрибутов.
2. Разработка клиента Salsify — с учётом пагинации, обработки ошибок и лимитов API.
3. Настройка маппинга — для полей и свойств инфоблоков, включая множественные и справочники.
4. Реализация агента синхронизации — с поддержкой дельты и вебхуков (опционально).
5. Перенос медиафайлов — с выбором стратегии (скачивание или внешние ссылки).
6. Тестирование и отладка — на тестовом каталоге, затем на боевом.
7. Документация и передача — описание архитектуры, инструкция по эксплуатации.

Состав работ

• Архитектурная документация и схема интеграции.
• Исходный код с комментариями в репозитории.
• Настройка мониторинга агентов и алертов.
• Обучение вашей команды (1-2 сессии).
• Гарантийная поддержка в течение 1 месяца после запуска.

Сроки реализации

Типовые ошибки при интеграции

• Игнорирование сложных атрибутов (enum с вложенной структурой) — приводит к потере данных.
• Отсутствие обработки дубликатов по SKU — создаются дубли элементов.
• Синхронизация цен из Salsify без согласования — Salsify не рассчитан на цены, лучше брать их из 1С.
• Полное скачивание медиафайлов — перегружает сервер. Рекомендуем внешние URL.

Мы — сертифицированные специалисты по Битрикс с опытом более 7 лет. За это время реализовали 50+ проектов интеграции с внешними системами, включая PIM, ERP и маркетплейсы. Наши решения стабильно работают с каталогами до 100 000 SKU. Свяжитесь с нами для предварительной оценки сложности и сроков. Закажите бесплатную консультацию — мы подробно расскажем о процессе интеграции и ответим на ваши вопросы.

Подробнее о возможностях Salsify API читайте в официальной документации: Salsify API Guide.