שילוב Salsify-1C-Bitrix: העברת קטלוג מלאה באמצעות REST API

מעבר ל-Salsify PIM מעלה לא פעם שאלה: איך מעבירים קטלוג של 50,000 פריטי SKU עם 200 מאפיינים ל-1C-Bitrix ללא אובדן נתונים? ייבוא ידני דרך Excel אורך עד 3 חודשים ואינו מבטיח שלמות. מבני מאפיינים שונים, ערכים מקוננים וקבצי מדיה דורשים אינטגרציה מחושבת היטב. אנו מציעים פתרון מוכן המבוסס על Salsify REST API, שמקצר תהליך זה לשבוע–שבועיים. האינטגרציה מיועדת לזרימת נתונים דו-כיוונית. קבלו ייעוץ והערכת מורכבות לפרויקט שלכם.

כיצד אנו מיישמים אינטגרציית Salsify-Bitrix

Salsify היא פלטפורמת PIM עננית למסחר אלקטרוני בקנה מידה גדול. ה-REST API שלה מאפשר ייצוא של מוצרים, מאפיינים וקבצי מדיה. אנו מתחברים באמצעות אימות טוקן ובונים סנכרון אסינכרוני דרך סוכני מערכת של Bitrix. הסוכן מעבד עד 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

הכנו מחלקת GET https://app.salsify.com/api/v1/orgs/{org_id}/products Authorization: Bearer {api_key} שמכילה בקשות HTTP, פגינציה וטיפול בשגיאות. היא משתמשת ב-SalsifyClient:

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 מאחסנת מאפיינים במבנה שטוח: כל מאפיין הוא זוג "שם": "ערך". אנו מגדירים מיפוי בקובץ תצורה, וממפים מזהה מאפיין או שם לשדות ומאפיינים של בלוק מידע:

// /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 ל-Bitrix

הסנכרון מכסה שלוש קבוצות נתונים:

1. מאפיינים ליבה — שם, תיאור, מאפיינים, GTIN, משקל, צבע, ארץ מקור.
2. קבצי מדיה — תמונות, מסמכים, סרטונים. שני מצבים נתמכים: העלאה מלאה לשרת או קישורי CDN.
3. קשרי מוצרים — היררכיות המועברות למבנה סעיפי בלוק המידע וקישורים.

מחירים בדרך כלל אינם מסונכרנים — הם מגיעים מ-1C. המיפוי מותאם אישית לכל קטלוג.

כיצד לבחור שיטת אחסון מדיה?

שתי גישות: העלאת קבצים לשרת או אחסון קישורי CDN חיצוניים. השוואה:

עבור קטלוגים עד 10,000 פריטי SKU, לרוב בוחרים בהעלאה; עבור פרויקטים גדולים, CDN.

כיצד להגדיר מיפוי מאפיינים?

המיפוי הוא המפתח. עבור כל מאפיין Salsify, אנו מציינים לאיזה שדה או מאפיין של בלוק מידע הוא צריך להגיע. נתמכים ערכים מרובים, ספריות וקשירות ל-highload-block. אנו מספקים קובץ תצורה שניתן לערוך בקלות ללא שינוי קוד. אם למאפיין Salsify יש סוג מורכב (למשל, enum עם שדות מקוננים), הוא מעובד מראש באמצעות פונקציות ממיר מותאמות אישית.

סקירת תהליך

1. ניתוח מבנה נתונים — בחינת מיפוי, זיהוי מאפיינים מורכבים.
2. פיתוח לקוח Salsify — טיפול בפגינציה, טיפול בשגיאות, מגבלות API.
3. הגדרת מיפוי — עבור שדות ומאפיינים של בלוק מידע, כולל סוגי ריבוי וספריות.
4. הטמעת סוכן סנכרון — תמיכה בדלתא ו-webhooks (אופציונלי).
5. העברת מדיה — בחירת אסטרטגיה (הורדה או קישורים חיצוניים).
6. בדיקות וניפוי — על קטלוג בדיקה, ולאחר מכן ייצור.
7. תיעוד ומסירה — תיאור ארכיטקטורה, מדריך תפעול.

תוצרי עבודה

• תיעוד ארכיטקטורה ודיאגרמת אינטגרציה.
• קוד מקור עם הערות במאגר.
• הגדרת ניטור והתראות לסוכן.
• הדרכת צוות (1–2 מפגשים).
• תמיכה באחריות למשך חודש לאחר ההשקה.

לוחות זמנים ליישום

טעויות נפוצות באינטגרציה

• התעלמות ממאפיינים מורכבים (enum עם מבנה מקונן) — מובילה לאובדן נתונים.
• ללא טיפול בכפילויות SKU — יוצר פריטים כפולים.
• סנכרון מחירים מ-Salsify ללא תיאום — Salsify אינה מיועדת למחירים; עדיף למקור מ-1C.
• הורדת מדיה מלאה — מעמיסה על השרת. אנו ממליצים על כתובות URL חיצוניות.

אנו מומחי Bitrix מוסמכים עם ניסיון של למעלה מ-7 שנים. בתקופה זו, השלמנו למעלה מ-50 פרויקטי אינטגרציה עם מערכות חיצוניות, כולל PIM, ERP ומרקטפלייסים. הפתרונות שלנו פועלים ביציבות עם קטלוגים של עד 100,000 פריטי SKU. צרו קשר להערכה מקדימה של מורכבות ולוחות זמנים. הזמינו ייעוץ — נפרט את תהליך האינטגרציה ונענה על שאלותיכם.

למידע נוסף על יכולות Salsify API בתיעוד הרשמי: מדריך Salsify API.