קומקס חושפת ווב-שירותים ב-ws.comax.co.il עם אימות בזוג פרטי התחברות. מה הצורה הזו אומרת על הארכיטקטורה שלך, ארבעת הזרמים שאינטגרציה קמעונאית מתפרקת אליהם, ולמה הקופה היא האילוץ שאף אחד לא מתכנן סביבו.
עיקרי הדברים
- האימות הוא זוג LoginID ו-LoginPassword שנשלח בכל קריאה, לא טוקן. משמעות הדבר היא שההרשאה ארוכת חיים ויש להתייחס אליה כסוד בצד השרת עם תוכנית להחלפה.
- זהו ממשק ווב-שירותים עם פעולות בשם, לא REST עם משאב לכל ישות. יש לקרוא את ה-WSDL או רשימת הפעולות מההתקנה במקום להניח מוסכמות REST.
- בקמעונאות הקופה היא האילוץ האמיתי. המלאי שהחנות מוכרת חייב להביא בחשבון את מה שהקופות הפיזיות מתחייבות עליו, אחרת תמכור מלאי שאין ביום שישי עמוס.
- הברקוד הוא בדרך כלל מפתח החיבור, והוא בדרך כלל מלוכלך. יש לבדוק כפילויות ווריאציות שחולקות קוד אחד לפני שכותבים שורת קוד סנכרון.
קומקס היא מערכת ERP קמעונאית ישראלית, ורוב הפרויקטים סביבה הם אותו פרויקט: לחבר אותה לחנות מקוונת כך שהקטלוג, המלאי וההזמנות יזרמו בין השתיים. ה-API של קומקס חושף ווב-שירותים בכתובת ws.comax.co.il, עם אימות בזוג LoginID ו-LoginPassword.
המדריך הזה עוסק במה שנגזר מהצורה הזו ובהחלטות הקמעונאיות - לא במפרט שדות. את מבנה הבקשה המדויק יש לקחת מרשימת הפעולות של ההתקנה שלך, כי ווב-שירותים משתנים בין גרסאות והתקנות.
מה הצורה הזו אומרת
פעולות בשם, לא משאבים
זהו ממשק בסגנון ווב-שירותים: פעולות בשם - למשל שליפת פרטי לקוח לפי חיפוש - ולא משאבים עם פעלי HTTP. אין GET /customers/123 ואין DELETE.
אם אתה מגיע עם ציפיות REST, זו נקודת הבלבול הראשונה. הדרך הנכונה לגלות מה קיים היא לקרוא את רשימת הפעולות מההתקנה עצמה, לא לחפש דוגמאות ברשת - בממשקים כאלה, קוד שנכתב לגרסה אחרת נכשל באופן שנראה מבלבל.
אימות ארוך-חיים
זוג פרטי התחברות שנשלח בכל קריאה אינו טוקן שפג. שתי השלכות:
- אין תפוגה שתגלה לך שמשהו לא בסדר. ההרשאה תמשיך לעבוד עד שמישהו ישנה אותה ידנית, כולל אם היא דלפה.
- צריך תוכנית להחלפה. עובד שעוזב, ספק שמסיים - אלה רגעים שבהם צריך להחליף, ואם ההרשאה מקובעת בקוד זה הופך לפרויקט.
משתני סביבה או מנהל סודות בלבד. לא בקוד המקור, לא בלוגים, ולא בשום דבר שרץ בדפדפן.
איך נראית קריאה ל-API של קומקס?
קריאה ל-API של קומקס היא בקשה לאחת הפעולות של Comax_WebServices בכתובת ws.comax.co.il, והתשובה חוזרת כ-XML ולא כ-JSON. מדריך מחבר שפרסם צד שלישי (התיעוד של Fruxon לאינטגרציה מול קומקס) מוסיף פרטים שתואמים את מה שפוגשים בפועל:
- פרטי ההתחברות עוברים ב-query string.
LoginIDו-LoginPasswordנשלחים בכל בקשה כפרמטרים בכתובת. כל רכיב שרושם כתובות מלאות ללוג - reverse proxy, מעקב APM, כלי דיווח שגיאות - ישמור גם את הסיסמה, אלא אם מסירים את ה-query string מהלוגים האלה. - מנהל המערכת בקומקס מנפיק אותם, עם הרשאת ווב-שירותים פעילה למשתמש. תוצאה ריקה היא לעיתים קרובות הרשאה חסרה, לא נתונים חסרים.
- תאריכים בפורמט
dd/MM/yyyy. כך שולחים אותם בכל מסנן. - מלאי לפי חנות או סניף, מחירים לפי מחירון. אפשר לשלוף יתרות פריט לפי סניף, ומחירים לפי מחירון, חנות, מחלקה, קבוצה או ספק - בדיוק ההחלטה שהקופה מכריחה אותך לקבל, כפי שמפורט בהמשך.
| תסמין | מה לבדוק קודם |
|---|---|
| כל שליפה חוזרת ריקה | הרשאת ווב-שירותים למשתמש ה-API |
| מסנן תאריך מחזיר יותר מדי או כלום | פורמט התאריך, dd/MM/yyyy |
| המלאי באתר גבוה ממה שיש על המדף | אילו סניפים נסכמים |
| הסיסמה מופיעה בלוג | רישום ה-query string ב-proxy או בכלי ה-APM |
מה זה תוכנת קומקס, ואילו חלקים ממנה האינטגרציה נוגעת?
קומקס היא מערכת ERP ישראלית בענן לרשתות קמעונאות. באתר שלה היא מוצגת לענפי האלקטרוניקה, החשמל וכלי העבודה, עם מודולים לרכש, מלאי, מבצעים, מועדון לקוחות, קופות חכמות וקופות בשירות עצמי והנהלת חשבונות מהקופה ועד המאזן, וגם אפליקציות כמו COMAX2GO לסוכני שטח.
שתי נקודות חשובות לפני שכותבים קוד. ראשית, הקופה היא חלק מאותה מערכת, ולכן החנות המקוונת מתחרה על אותו מלאי בזמן אמת. שנית, קומקס מציגה פתרון מסחר מקוון משלה, עם מערכת אחת לחלוקת הזמנות בין הסניפים לחנות המקוונת. אם החנות נבנית מאפס, כדאי לשאול את קומקס מה המודול הזה מכסה לפני שמשלמים על אינטגרציה ייעודית; הדרך הייעודית מצדיקה את עלותה כשהחנות כבר רצה על Shopify או WooCommerce ונשארת שם.
ארבעת הזרמים
אינטגרציה קמעונאית מתפרקת לארבעה זרמים חד-כיווניים, ורק אחד דחוף:
| זרם | כיוון | עדכניות |
|---|---|---|
| קטלוג ומחירים | קומקס ← חנות | מתוזמן |
| מלאי | קומקס ← חנות | מתוזמן, תדיר |
| הזמנות | חנות ← קומקס | קרוב לזמן אמת |
| אספקה וסטטוס | קומקס ← חנות | מתוזמן |
הפירוט המלא של הדפוס נמצא בלחבר ERP ישראלי לכל מערכת אחרת. מה שייחודי לקמעונאות מופיע למטה.
מה שמייחד קמעונאות: הקופה
זה ההבדל המרכזי בין אינטגרציה קמעונאית לאינטגרציית ERP רגילה, והוא נופל על פרויקטים שלא תכננו סביבו.
בעסק קמעונאי, אותו מלאי נמכר בשני מקומות בו-זמנית - באתר ובקופה הפיזית. הקופה לא מחכה לסנכרון שלך.
שלוש שאלות שקובעות אם הסנכרון יעבוד:
- איזה מלאי החנות מוכרת? מלאי פיזי או מלאי זמין למכירה? למכירה מקוונת רוצים את הזמין - אחרת תמכור פריטים שכבר מוקצים.
- מאילו סניפים? סכימה עיוורת של כל הסניפים מייצרת התחייבות למלאי שנמצא במקום אחר.
- מה קורה בפריט אחרון? אם נשארה יחידה אחת והיא נמכרה בקופה, כמה זמן עובר עד שהאתר יודע? זה הפער שבו מוכרים מלאי שאין.
המסקנה המעשית: אין תדירות סנכרון שפותרת פריט אחרון בביקוש גבוה. אם העסק מוכר פריטים ייחודיים או מלאי קצה, הפתרון אינו סנכרון תכוף יותר אלא מלאי חוצץ - להציג באתר פחות ממה שיש - או הקצאה מפורשת. זו החלטה עסקית שצריכה לעלות באפיון.
מפתח החיבור: ברקוד
צריך מזהה יציב שקושר פריט בקומקס לפריט בחנות. הברקוד או המק"ט הם הבחירה הטבעית - אבל רק אם הם באמת ייחודיים.
בקמעונאות זה כמעט אף פעם לא נקי: אותו ברקוד על שתי וריאציות צבע, ברקוד פנימי שהוחלף לפני שלוש שנים, פריטים בלי ברקוד כלל.
שאילתה אחת שסופרת ברקודים כפולים לפני תחילת הפיתוח חוסכת שבוע. אם יש כפילויות, זו עבודת ניקוי שצריכה לקרות לפני האינטגרציה ולא במקומה.
מה שחייב להיות
- קישור דו-כיווני מתועד. מזהה ההזמנה של החנות על המסמך בקומקס, ומספר המסמך על ההזמנה. בלי זה כל בירור הופך להשוואה ידנית.
- אידמפוטנטיות. אותה הזמנה שמגיעה פעמיים חייבת ליצור מסמך אחד.
- תהליך התאמה יומי. להשוות הזמנות ומלאי בין שני הצדדים לטווח היממה. בקמעונאות פער מלאי הוא לקוח שהזמין משהו שאין, ולכן זה לא מותרות.
- תור שגיאות שאדם רואה. הזמנה שנכשלה בייבוא היא הזמנה אבודה אם היא נתקעה בלוג.
התאמת לקוחות
אחת הפעולות שהממשק חושף היא שליפת פרטי לקוח לפי חיפוש - וזה בדיוק המקום שדורש זהירות.
הכלל: אם אין התאמה ודאית, אל תיצור כרטיס לקוח חדש אוטומטית. לרשום את ההזמנה תחת לקוח מזדמן ולסמן לטיפול. כפילויות בכרטיסי לקוח לא נופלות בבדיקות - הן מצטברות ומתגלות חצי שנה אחר כך בדוח שלא מסתדר.
צ'קליסט לפני התמחור
- לקבל את רשימת הפעולות של ההתקנה - לא להסתמך על דוגמאות מהרשת.
- לבדוק ברקודים כפולים בקטלוג.
- להחליט איזה מלאי ומאילו סניפים החנות מוכרת - בכתב.
- להחליט מה קורה בפריט אחרון, כולל אם צריך מלאי חוצץ.
- לוודא שההרשאות מאוחסנות כסודות ושיש תוכנית להחלפה.
- לתקצב תהליך התאמה יומי - הוא לא תוספת.
מקורות
שאלות נפוצות
איך מתאמתים מול ה-API של קומקס?
בזוג LoginID ו-LoginPassword שנשלח עם הקריאה, מול ווב-שירותים ב-ws.comax.co.il. מכיוון שזו הרשאה ארוכת חיים ולא טוקן שפג, אין תפוגה שתאותת על בעיה - היא ממשיכה לעבוד עד שמישהו משנה אותה, כולל אחרי דליפה. יש לשמור אותה כסוד בצד השרת ולהחזיק תוכנית להחלפה.
האם ה-API של קומקס הוא REST?
לא במובן המודרני. זהו ממשק בסגנון ווב-שירותים שבנוי סביב פעולות בשם - למשל שליפת פרטי לקוח לפי חיפוש - ולא סביב משאבים עם פעלי HTTP. יש לגלות מה קיים בקריאת רשימת הפעולות של ההתקנה שלך ולא בחיפוש דוגמאות, כי קוד שנכתב לגרסה אחרת נכשל באופן מבלבל.
למה חנות קמעונאית מוכרת מלאי שאין למרות סנכרון תכוף?
כי הקופה הפיזית מוכרת את אותו מלאי ולא מחכה לסנכרון שלך. בפריט אחרון בביקוש גבוה, שום תדירות סנכרון לא סוגרת את הפער בין מכירה בדלפק לבין הרגע שהאתר יודע. הפתרון אינו סנכרון מהיר יותר אלא מלאי חוצץ - להציג באתר פחות ממה שיש - או הקצאה מפורשת, וזו החלטה עסקית.
מה לבדוק לפני שמתחילים אינטגרציית קומקס עם חנות?
ברקודים כפולים בקטלוג, שהוא מפתח החיבור וכמעט אף פעם לא נקי בקמעונאות - אותו קוד מופיע לעיתים קרובות על שתי וריאציות, או הוחלף בעבר. בנוסף להחליט בכתב איזה נתון מלאי ומאילו סניפים החנות מוכרת, ומה קורה בפריט אחרון. כל אחד מאלה משנה את האינטגרציה, וגילוי שלהם באמצע הפיתוח עולה שבועות.
האם האינטגרציה צריכה ליצור כרטיסי לקוח בקומקס אוטומטית?
רק בהתאמה ודאית. כשהחיפוש לא מחזיר משהו ודאי, יש לרשום את ההזמנה תחת לקוח מזדמן ולסמן לבדיקה אנושית במקום ליצור כרטיס חדש. כפילויות בכרטיסי לקוח עוברות כל בדיקה, מצטברות בשקט, ומתגלות חודשים אחר כך כדוחות שלא מסתדרים - ואז מישהו צריך למזג היסטוריה ידנית.
מה זה תוכנת קומקס?
קומקס היא מערכת ERP ישראלית בענן לרשתות קמעונאות. באתר שלה היא מוצגת לענפי האלקטרוניקה, החשמל וכלי העבודה, עם רכש, מלאי, מבצעים, מועדון לקוחות, קופות והנהלת חשבונות במערכת אחת. מבחינת אינטגרציה, העובדה החשובה היא שהקופה והחנות המקוונת מושכות מאותו מלאי.
ה-API של קומקס מחזיר JSON?
לא. הווב-שירותים של קומקס ב-ws.comax.co.il מחזירים XML, והפעולות הן קריאות בשם ולא משאבי REST. צריך לתכנן מפענח XML, ולקחת בחשבון שפרטי ההתחברות (LoginID ו-LoginPassword) עוברים בכל בקשה כפרמטרים ב-query string, כלומר צריך להסיר אותם מכל לוג שרושם כתובות מלאות.
למה קריאה לווב-שירות של קומקס מחזירה תוצאה ריקה?
הסיבה הנפוצה היא הרשאות: משתמש ה-API צריך גישת ווב-שירותים שמנהל המערכת בקומקס הפעיל, ובלעדיה שליפות יכולות לחזור ריקות במקום להיכשל. אחרי זה כדאי לבדוק שהתאריכים נשלחים בפורמט dd/MM/yyyy ושמסנן הסניף או המחירון תואם את מה שאתה מצפה לו.
להמשך קריאה
שירות רלוונטי
אינטגרציה בין מערכות
לגרום למערכות שאתם כבר משלמים עליהן לדבר זו עם זו.
יש לך פרויקט דומה?
ספר לי מה אתה רוצה לבנות או איזה תהליך להפוך לאוטומטי. אני חוזר תוך 24 שעות עסקים עם כמה שאלות ממוקדות, ואז עוברים על זה יחד בשיחת היכרות חינמית של 30 דקות, בלי התחייבות. בסוף יש לך היקף עבודה, לוח זמנים ומחיר קבוע - או תשובה כנה שלא שווה לבנות את זה.