Переход на 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 в Битрикс
Синхронизация охватывает три группы данных:
- Основные атрибуты — название, описание, характеристики, GTIN, вес, цвет, страна происхождения.
- Медиафайлы — изображения, документы, видео. Поддерживаются два режима: полная загрузка на сервер или использование CDN-ссылок.
- Связи между продуктами — иерархии переносятся в структуру разделов и связей инфоблоков.
Цены обычно не синхронизируются — они поступают из 1С. Маппинг настраивается под конкретный каталог.
Как выбрать способ хранения медиа?
Есть два подхода: загружать файлы на сервер или хранить внешние CDN-ссылки. Сравним их:
| Критерий | Загрузка на сервер | Внешние CDN-ссылки |
|---|---|---|
| Контроль над файлами | Полный | Зависит от провайдера |
| Дисковое пространство | Требуется | Не требуется |
| Скорость загрузки страниц | Зависит от сервера | Быстрее (CDN) |
| Риск битых ссылок | Минимальный | Возможен при изменении URL |
| Нагрузка на сервер | Высокая (скачивание) | Низкая |
Для каталогов до 10 000 SKU часто выбирают загрузку, для крупных проектов — CDN.
Как настроить маппинг атрибутов?
Маппинг — ключевой этап. Для каждого атрибута Salsify мы указываем, в какое поле или свойство инфоблока он должен попасть. Поддерживаются множественные значения, справочники и привязки к highload-блокам. Мы предоставляем конфигурационный файл, который легко редактировать без изменения кода. Если атрибут Salsify имеет сложный тип (например, enum с вложенными полями), его нужно предварительно преобразовать — для этого используются кастомные функции-конвертеры.
Пример маппинга сложного атрибута
Допустим, в Salsify есть атрибут "Specifications" с вложенными полями: "Weight", "Dimensions", "Material". Маппинг преобразует его в несколько свойств инфоблока: WEIGHT, DIMENSIONS, MATERIAL. Кастомный конвертер парсит JSON-структуру и записывает значения в соответствующие поля.
Процесс работы
- Анализ структуры данных — изучение маппинга, выявление сложных атрибутов.
- Разработка клиента Salsify — с учётом пагинации, обработки ошибок и лимитов API.
- Настройка маппинга — для полей и свойств инфоблоков, включая множественные и справочники.
- Реализация агента синхронизации — с поддержкой дельты и вебхуков (опционально).
- Перенос медиафайлов — с выбором стратегии (скачивание или внешние ссылки).
- Тестирование и отладка — на тестовом каталоге, затем на боевом.
- Документация и передача — описание архитектуры, инструкция по эксплуатации.
Состав работ
- Архитектурная документация и схема интеграции.
- Исходный код с комментариями в репозитории.
- Настройка мониторинга агентов и алертов.
- Обучение вашей команды (1-2 сессии).
- Гарантийная поддержка в течение 1 месяца после запуска.
Сроки реализации
| Объём | Состав | Срок |
|---|---|---|
| До 5 000 SKU, базовый контент | Клиент + маппинг + агент | 1–2 недели |
| 10 000–100 000 SKU + медиа + вебхуки | + обработка сложных атрибутов + оптимизация | 3–4 недели |
| Мультирегиональный каталог (разные цены, контент по регионам) | + логика каналов Salsify + мультисайт Битрикс | 5–7 недель |
Типовые ошибки при интеграции
- Игнорирование сложных атрибутов (enum с вложенной структурой) — приводит к потере данных.
- Отсутствие обработки дубликатов по SKU — создаются дубли элементов.
- Синхронизация цен из Salsify без согласования — Salsify не рассчитан на цены, лучше брать их из 1С.
- Полное скачивание медиафайлов — перегружает сервер. Рекомендуем внешние URL.
Мы — сертифицированные специалисты по Битрикс с опытом более 7 лет. За это время реализовали 50+ проектов интеграции с внешними системами, включая PIM, ERP и маркетплейсы. Наши решения стабильно работают с каталогами до 100 000 SKU. Свяжитесь с нами для предварительной оценки сложности и сроков. Закажите бесплатную консультацию — мы подробно расскажем о процессе интеграции и ответим на ваши вопросы.
Подробнее о возможностях Salsify API читайте в официальной документации: Salsify API Guide.