מדריך מעשי לחיבור חנות קונימבו ל-ERP, למערכת חשבוניות או לחברת שליחויות: נקודות הקצה של v1 להזמנות ולמוצרים, ה-webhook של order_created, איך באמת מתעדכנים סטטוסים ומלאי מורכב, ומגבלת הקריאות שעונה ב-401.
עיקרי הדברים
- כל קריאה ל-API של קונימבו נושאת פרמטר token שבעל החנות מנפיק, מול https://api.konimbo.co.il/v1.
- ה-webhook של order_created שולח רק את מספר ההזמנה, ולכן כל חיבור ממשיך ב-GET /v1/orders/{id}.
- ברירת המחדל היא 100 קריאות לטוקן ב-10 דקות, וטוקן חסום מקבל 401 - אותו קוד כמו טוקן שגוי.
- סטטוסים להזמנה אפשר רק להוסיף, עד 5 בקריאה, ומצב ההזמנה משתנה רק אם הכותרת כבר קיימת בממשק הניהול.
ה-API של קונימבו הוא ממשק REST בכתובת https://api.konimbo.co.il/v1, שמאפשר למערכת אחרת לקרוא את ההזמנות בחנות, ליצור ולעדכן מוצרים ומלאי, ולהוסיף סטטוסים להזמנות. כל קריאה נושאת פרמטר token שבעל החנות מנפיק. רוב החיבורים עובדים באותו מעגל: webhook מודיע על הזמנה חדשה, הקוד שולף אותה, מעביר אותה למערכת החשבוניות, ל-ERP או לחברת השליחויות, ורושם סטטוס בחזרה על ההזמנה.
קונימבו היא פלטפורמת מסחר מקוון ישראלית, והתיעוד שלה מתפרסם בעברית ב-GitHub. המדריך מיועד לבעלי עסקים ולמפתחים שמתכננים את החיבור, והוא מתמקד בפרטים שקובעים אם החיבור יחזיק כשמתחילות להגיע הזמנות אמיתיות.
מה אפשר לחבר לקונימבו דרך ה-API?
ב-v1 יש מודולים נפרדים למוצרים, להזמנות, ללקוחות, לעגלות, למערכת אינטגרציה בתוך ממשק הניהול ולהעלאת קבצים. בפועל, אלה החיבורים שעסקים מבקשים:
- הזמנות למערכת חשבוניות - כל הזמנה ששולמה מפיקה חשבונית מס קבלה במורנינג, ב-iCount, ב-Invoice4U או בהנהלת החשבונות.
- הזמנות ל-ERP - פריוריטי, SAP Business One או חשבשבת מקבלים את ההזמנה עם המק"טים.
- מלאי מה-ERP - רמות המלאי חוזרות לחנות, כך שהיא לא מוכרת מה שאין במחסן.
- הזמנות לחברת שליחויות - נוצר משלוח עם הכתובת והטלפון של הלקוח, וסטטוס המעקב חוזר להזמנה.
- מוצרים מקטלוג של ספק - יצירה ועדכון של פריטים לפי מק"ט, בכמויות.
נקודות הקצה שחשובות
| משימה | קריאה | הערה |
|---|---|---|
| רשימת הזמנות | GET /v1/orders | סינון: created_at_min, created_at_max, payment_status, status_option_title |
| הזמנה אחת | GET /v1/orders/{id} | attributes= מגביל את השדות שחוזרים |
| הוספת סטטוס | PUT /v1/orders/{id} | גוף: {"token": ..., "order": {"statuses": [...]}} |
| איתור מוצר לפי מק"ט | GET /v1/items/0?code={code} | גם לפי second_code |
| עדכון מוצר לפי מק"ט | PUT /v1/items/0?code={code} | מחיר, מלאי, הצגה בחנות |
| הרשמה לאירועים | POST /v1/webhooks | אירועים: order_created, עדכון מלאי של מוצר |
הזמנים בפורמט ISO-8601 (YYYY-MM-DDTHH:MM:SSZ), גוף הבקשה ב-JSON, והתשובה ב-JSON כברירת מחדל. רשימות חוזרות ב-20 רשומות לדף, עם הסך הכול בכותרת X-Pagination-Total והקישורים לדפים ב-X-Pagination-Links.
איך עובד מעגל ההזמנה, שלב אחר שלב
- בעל החנות מפעיל "Api" בהגדרות המתקדמות של החנות, יוצר משתמש API תחת "משתמשי API" ונותן לו הרשאה רק לנקודות הקצה שהחיבור צריך.
- רושמים webhook ב-
POST /v1/webhooks, עםeventשלorder_createdועם ה-callback_urlשלכם. - כשנוצרת הזמנה, קונימבו שולחת POST לכתובת עם מספר ההזמנה - לא עם ההזמנה המלאה.
- הקוד קורא ל-
GET /v1/orders/{id}עם רשימתattributesשל השדות שבאמת צריך. - יוצרים את המסמך או המשלוח במערכת השנייה ושומרים את המזהה שלו מול מספר ההזמנה בקונימבו, כדי ש-webhook כפול לא ייצור אותו פעמיים.
- מוסיפים סטטוס להזמנה ב-
PUT /v1/orders/{id}, למשל "הופקה חשבונית" עם מספר המסמך ב-comment. - משימה מתוזמנת שולפת הזמנות לפי
created_at_minפעם בשעה, כדי לתפוס כל מה ש-webhook שלא הגיע פספס.
לקונימבו יש גם מערכת אינטגרציה בתוך ממשק הניהול, שבה סקריפט רץ על כתובת טריגר בלי שרת משלכם. זה מתאים לחיבור קטן עם מטרה אחת. לכל דבר שדורש ניסיונות חוזרים, לוגים ויותר מיעד אחד, שירות קטן משלכם קל יותר לתחקר.
למה ה-API מחזיר 401 כשהטוקן נכון?
קונימבו עונה 401 Unauthorized בשני מצבים שונים: טוקן לא תקין, וטוקן שחרג ממגבלת הקריאות. ברירת המחדל היא 100 קריאות לטוקן ב-10 דקות, והספירה מתאפסת כל 10 דקות. חיבור שמתייחס לכל 401 כאל "המפתח שגוי" מתריע על הבעיה הלא נכונה, ולעתים קרובות ממשיך לנסות שוב ונכנס לחסימה ארוכה יותר.
קראו את כותרות המגבלה בכל תשובה: X-Rate-Limit-Current, X-Rate-Limit-Maximum ו-X-Rate-Limit-Reset. לפני ייבוא ראשוני או סנכרון מלאי מלא, בקשו מבעל החנות להעלות למשתמש ה-API את הגבלת הקריאות והגבלת הרשומות - תיעוד האינטגרציה ממליץ להעלות אותן למקסימום בזמן הבדיקות. הודעה אחרת, "You have reached the maximum amount of items", פירושה שהטוקן הגיע למגבלת הרשומות וצריך להגדיל אותה.
סטטוסים ומלאי מורכב: שתי המלכודות
סטטוסים רק מתווספים. דרך ה-API מוסיפים להזמנה סטטוסים, עד חמישה בקריאה, כל אחד עם status_option_title, username אופציונלי ו-comment. מצב ההזמנה משתנה רק אם בדיוק אותה כותרת כבר קיימת בממשק הניהול תחת הזמנות > מצבי הזמנה. כותרת שלא קיימת נרשמת כהערה והמצב נשאר כמו שהיה - שימושי לתיעוד ("הלקוח לא עונה"), ומבלבל כשציפיתם שההזמנה תעבור ל"נשלח".
מלאי מורכב צריך להיות קיים קודם. למוצר עם וריאציות - צבע, מידה - יש מערך inventory לכל מק"ט של וריאציה, עם code, price ו-free (יחידות במלאי). לפי התיעוד השדה הזה ניתן לעדכון בלבד: את שדרוג המלאי מקימים בממשק הניהול, ורק אז ה-API יכול לשנות אותו, עד 30 וריאציות בקריאה. מוצר פשוט עם אפשרות אחת משתמש בשדה quantity הרגיל.
מה משתבש בחיבור לקונימבו
- מחירים מגיעים כמחרוזות (
"799.0"). מפרשים אותם כמספר עשרוני מדויק, לא כ-float, לפני שהם מגיעים לחשבונית. - משלוח אינו שורת מוצר כברירת מחדל. אם מערכת החשבוניות צריכה אותו כשורה, נותנים לשיטת המשלוח מק"ט בממשק הניהול, ואז הוא מופיע ברשימת המוצרים.
- ההזמנה כוללת פרטי אשראי ב-
credit_card_details, כולל ת"ז של בעל הכרטיס וטוקן כרטיס. בקשו רק את השדות שצריך עםattributes, ואל תכתבו את הבלוק הזה ללוגים שלכם. - webhook בלי משימת התאמה מאבד הזמנות ביום שבו השרת שלכם לא זמין.
- מחיקת מוצרים לפי מק"ט אפשרית (
DELETE /v1/items/0?code=), כך שבאג בסנכרון יכול להסיר פריטים מהחנות החיה. השאירו מחיקה מחוץ לגרסה הראשונה.
חיבור ההזמנה לחשבונית מפורט בחיבור תוכנת החשבוניות לשאר המערכות, וסנכרון דומה בין חנות ל-ERP בסנכרון פריוריטי עם Shopify. לצד המשלוחים, ראו אוטומציה של תוויות משלוח בישראל.
מה להכין לפני שמתחילים
- משתמש API עם ההרשאות שהחיבור צריך בלבד, והטוקן שלו.
- רשימת מצבי ההזמנה בממשק הניהול, עם הכותרות המדויקות שהחיבור יגדיר.
- מק"ט לכל מוצר ולכל וריאציה - המק"ט הוא הדרך שבה החנות וה-ERP מזהים את אותו פריט.
- גישת API למערכת החשבוניות או ל-ERP, שנבדקה בנפרד.
- החלטה איזו מערכת היא מקור האמת למלאי, כדי ששתיהן לא ידרסו זו את זו.
מקורות
שאלות נפוצות
האם לקונימבו יש API?
כן. קונימבו מפרסמת API בגרסה v1 בכתובת https://api.konimbo.co.il/v1, מתועד בעברית ב-GitHub, עם מודולים למוצרים, להזמנות, ללקוחות, לעגלות ול-webhooks. בעל החנות מפעיל אותו בהגדרות המתקדמות של החנות ויוצר משתמש API, שהטוקן שלו מאשר כל קריאה.
איך מעבירים הזמנות חדשות מקונימבו למערכת החשבוניות אוטומטית?
רושמים webhook של order_created ב-POST /v1/webhooks. קונימבו שולחת לכתובת שלכם את מספר ההזמנה החדשה, הקוד שולף אותה ב-GET /v1/orders/{id}, מפיק חשבונית דרך ה-API של מערכת החשבוניות, ומוסיף להזמנה סטטוס עם מספר המסמך.
מה מגבלת הקריאות של ה-API של קונימבו?
כברירת מחדל, 100 קריאות לטוקן ב-10 דקות, ואחר כך הספירה מתאפסת. טוקן חסום מקבל 401 Unauthorized, אותו קוד כמו טוקן לא תקין. הכותרות X-Rate-Limit-Current, X-Rate-Limit-Maximum ו-X-Rate-Limit-Reset מראות איפה אתם עומדים, ובעל החנות יכול להעלות את המגבלה לכל משתמש API.
אפשר לעדכן מלאי בקונימבו לפי מק"ט מה-ERP?
כן. PUT /v1/items/0?code={code} מעדכן מוצר לפי המק"ט שלו, עם quantity למוצר פשוט. לוריאציות, מערך inventory מעדכן כל מק"ט של וריאציה עם price ו-free, עד 30 בקריאה, אבל את מלאי הווריאציות צריך קודם להקים בממשק הניהול של קונימבו.
למה מצב ההזמנה בקונימבו לא השתנה אחרי שהוספתי סטטוס?
מצב ההזמנה משתנה רק כשה-status_option_title ששלחתם כבר קיים בממשק הניהול תחת מצבי הזמנה. כל כותרת אחרת נשמרת כהערה על ההזמנה והמצב נשאר כמו שהיה. בדקו את האיות המדויק של המצב בממשק הניהול, כולל רווחים.
להמשך קריאה
שירות רלוונטי
מלאי ורכש
מלאי ברמת SKU, כללי הזמנה חוזרת ותהליך אישור מתועד.
על הכותב
יהונתן סעדיה
מפתח פרילנסר לאוטומציה, אתרים ו-MVP
אני יהונתן סעדיה, מפתח בכיר שבונה אוטומציה עסקית, אתרים מותאמים ומוצרי MVP לעסקים קטנים ובינוניים בארה"ב, אירופה וישראל. המדריכים האלה נכתבים מתוך עבודה אמיתית עם לקוחות, לא מתיאוריה.
בוא נעבוד יחדיש לך פרויקט דומה?
ספר לי מה אתה רוצה לבנות או איזה תהליך להפוך לאוטומטי. אני חוזר תוך 24 שעות עסקים עם כמה שאלות ממוקדות, ואז עוברים על זה יחד בשיחת היכרות חינמית של 30 דקות, בלי התחייבות. בסוף יש לך היקף עבודה, לוח זמנים ומחיר קבוע - או תשובה כנה שלא שווה לבנות את זה.