לעתים קרובות אנו נתקלים במצב שבו חנות מקוונת על 1С-Битрикс משתמשת ב-МойСклад לניהול מסחר, אך אין מודול אינטגרציה סטנדרטי. פתרונות מוכנים מהמרקטפלייס מכסים 60–70% מהתרחישים. השאר — מיפוי מאפיינים לא סטנדרטי, סנכרון מלאי לפי מחסן וטיפול בתכונות — דורש פיתוח מותאם אישית. הניסיון שלנו מראה שאינטגרציה מוגדרת כראוי מחזירה את עצמה בכך שהיא מבטלת הזנה ידנית ושגיאות. בואו נצלול לארכיטקטורה, ל-API של МойСklad ולבעיות טיפוסיות. במאמר זה נתאר בפירוט את תהליך ההגדרה לסנכרון מוצרים, מלאי והזמנות באמצעות МойСклад JSON API 1.2. תלמדו כיצד להימנע מטעויות נפוצות ואילו כלים להשתמש בהם לפעולה אמינה.
מה אנו מסנכרנים
אינטגרציית Битрикс ↔ МойСклад כוללת בדרך כלל ארבעה זרמי נתונים:
| זרם | כיוון | תדירות | עדיפות |
|---|---|---|---|
| מוצרים ומחירים | МойСклад → Битрикс | כל 15–60 דקות | גבוהה |
| מלאי לפי מחסן | МойСклад → Битрикс | כל 5–15 דקות | קריטית |
| הזמנות | Битрикс → МойСклад | בעת אירוע (כשמוזמן) | קריטית |
| סטטוסי הזמנות | МойСклад → Битрикс | כל 5–15 דקות | בינונית |
הכיוון "МойСклад כמקור ראשי" למוצרים הוא טיפוסי. מנהל תוכן עובד ב-МойСклад, והאתר מקבל נתונים עדכניים. סנכרון הפוך (Битрикс → МойСклад) נדיר ומייצר סיכון להתנגשויות.
כיצד עובד ה-API של МойСклад Remap 1.2
МойСклад מספק REST API (JSON API 1.2) בכתובת Remap API 1.2. האימות הוא באמצעות Basic Auth או Bearer Token.
נקודות קצה מרכזיות:
-
GET /entity/product— רשימת מוצרים. תומך בסינון (filter=updated>${lastSyncTime}), דפדוף (limit,offset) והרחבת ישויות מקוננות (expand=group,productFolder). -
GET /entity/assortment— רשימה משולבת של מוצרים, שינויים, ערכות ושירותים. נוח יותר מ-productאם צריך הכל בבת אחת. -
GET /report/stock/all— יתרות מלאי לכל המוצרים. ניתן לסנן לפי מחסן (stockstore). -
POST /entity/customerorder— יצירת הזמנת לקוח. -
GET /entity/customerorder/{id}— קבלת הזמנה עם סטטוסים.
מגבלות API:
מידע נוסף על מגבלות
- מגבלת קצב: 45 בקשות לכל 3 שניות לכל חשבון. חריגה מחזירה HTTP 429. הניתוח חייב לקחת בחשבון השהיות. - מקסימום 1000 אובייקטים לתגובה. לייצוא קטלוג מלא נדרש דפדוף. - התראות Webhook (МойСклад → השרת שלך) זמינות אך לא אמינות: אין ערובה למסירה, אין ניסיונות חוזרים. לנתונים קריטיים (מלאי), השתמשו ב-polling.מדוע מיפוי שדות נכון חשוב
סנכרון מוצרים הוא לב האינטגרציה. אלגוריתם לסנכרון מצטבר:
- בקש
GET /entity/assortment?filter=updated>${lastSyncTime}&limit=1000. - עבור כל מוצר, מצא את האלמנט המתאים בבלוק המידע של Битрикс לפי קוד חיצוני (
XML_ID= UUID של המוצר ב-МойСклад). - אם נמצא —
CIBlockElement::Update()עם שדות מעודכנים. - אם לא נמצא —
CIBlockElement::Add(). - שמור
lastSyncTime = now()ב-b_option.
מיפוי שדות — הליבה של האינטגרציה. טבלת התאמה:
| МойСклад | Битрикс (בלוק מידע) | הערות |
|---|---|---|
name |
NAME |
— |
description |
DETAIL_TEXT |
HTML או טקסט פשוט |
article |
PROPERTY_ARTICLE |
קוד המאפיין תלוי בבלוק |
salePrices[0].value |
CATALOG_PRICE_1 |
מחיר בקופיקות → חלקו ב-100 |
buyPrice.value |
CATALOG_PRICE_2 (רכישה) |
אם נעשה שימוש |
images[].filename |
DETAIL_PICTURE / MORE_PHOTO |
הורד מ-URL של miniature.href |
productFolder.name |
סעיף בלוק מידע | צור סעיף אם אינו קיים |
מאפיינים (שינויים) ב-МойСклад הם variant בתוך מוצר. ב-Битрикс הם תואמים להצעות מסחר (SKU) בבלוק מידע נפרד. כל variant → אלמנט בבלוק מידע של SKU המקושר למוצר האב דרך CHL_LINK (מאפיין CML2_LINK).
סנכרון מלאי
המלאי הוא הזרם הרגיש ביותר. מכירת מוצר עם אפס מלאי היא הפסד ישיר. אנו קוראים ל-GET /report/stock/all עם פילטר למחסנים שמשתתפים במכירות מקוונות. התוצאה מכילה assortmentId ו-quantity. אנו מעדכנים את השדה CATALOG_QUANTITY ב-b_catalog_product או דרך \Bitrix\Catalog\ProductTable::update().
כדי להציג מלאי לפי מחסן באתר (למשל, "במלאי בחנות לנין"), השתמשו בניהול מלאי של Битрикс: מודול catalog, טבלה b_catalog_store_product. כל מחסן של МойСклад ממופה למחסן Битрикс (b_catalog_store). תדירות: כל 5 דקות באמצעות סקריפט cron. סוכני Битрикс אינם מתאימים למשימה זו — הם קשורים ל-hits ואינם מבטיחים את המרווח.
העברת הזמנות
כאשר מוזמנת הזמנה ב-Битрикс (אירוע OnSaleOrderSaved או OnSaleComponentOrderComplete), אנו יוצרים הזמנה ב-МойСклад דרך POST /entity/customerorder. מבנה גוף הבקשה:
{ "organization": {"meta": {"href": "...entity/organization/{id}"}}, "agent": {"meta": {"href": "...entity/counterparty/{id}"}}, "positions": [ { "assortment": {"meta": {"href": "...entity/product/{id}"}}, "quantity": 2, "price": 150000 } ] } הצד שכנגד ({ "organization": {"meta": {"href": "...entity/organization/{id}"}}, "agent": {"meta": {"href": "...entity/counterparty/{id}"}}, "positions": [ { "assortment": {"meta": {"href": "...entity/product/{id}"}}, "quantity": 2, "price": 150000 } ] } ) הוא הקונה. להזמנה ראשונה, צור דרך agent; להזמנות חוזרות, חפש לפי אימייל/טלפון. ה-UUID של הצד שכנגד נשמר במאפיין משתמש של הזמנת Битрикс או בשדה POST /entity/counterparty של המשתמש.
טיפול בשגיאות ותור
הרשת אינה אמינה; ה-API של МойСклад לפעמים מגיב עם 500. להזמנות, השתמשו בתור: בשגיאת שליחה, שמרו את ההזמנה בטבלת UF_ (או parser_queue עם דגל "לא נשלח ל-МойСклад"), וסוכן ינסה שוב כל 5 דקות. מקסימום 5 ניסיונות, ולאחר מכן הודעו למנהל. למוצרים ומלאי, תור אינו נחוץ — מחזור הסנכרון הבא יקלוט את השינויים.
מה כלול בעבודה
- ניתוח מבנה הקטלוג ויצירת מפת מיפוי
- פיתוח סקריפטים לסנכרון מוצרים, מחירים ומלאי
- הגדרת העברת הזמנות וצדדים שכנגד
- יצירת תיעוד אינטגרציה
- הדרכת צוות על תפעול המערכת
- תמיכה טכנית לאחר ההשקה
לצוות שלנו יש ניסיון של למעלה מ-10 שנים ו-50+ אינטגרציות מוצלחות. להערכת זמן ועלות מדויקת, צרו קשר.
לוח זמנים
| שלב | זמן |
|---|---|
| ניתוח מבנה קטלוג + מיפוי שדות | 1–2 ימים |
| סנכרון מוצרים + קטגוריות | 3–4 ימים |
| סנכרון מלאי לפי מחסן | 1–2 ימים |
| העברת הזמנות וצדדים שכנגד | 2–3 ימים |
| סנכרון סטטוסים הפוך | יום אחד |
| בדיקות, ניפוי שגיאות, מקרי קצה | 2–3 ימים |
| סה"כ | 1–2 שבועות |
הזמינו ייעוץ בנושא אינטגרציה, ואנו נעריך את הפרויקט שלכם.