חשבונית ירוקה (מורנינג) היא מערכת החשבוניות הישראלית הקלה ביותר לאוטומציה, ולכן היא האינטגרציה הראשונה הנכונה לרוב העסקים הקטנים. כאן נמצאת הארכיטקטורה שעובדת, מלכודת סוג המסמך שכולם נופלים בה, ולמה מניעת כפילויות חשובה כאן יותר מבכל מקום אחר.
עיקרי הדברים
- אוטומציה של הפקת חשבוניות היא האינטגרציה הראשונה עם ההחזר הגבוה ביותר לרוב העסקים הקטנים בישראל - היא קטנה, רצה יומית, והפקה ידנית היא המקום שבו טעויות הכי יקרות.
- בחרו את סוג המסמך הנכון לפני שכותבים קוד. הפקת חשבונית מס במקום קבלה או הצעת מחיר היא בעיה חשבונאית, לא באג שפשוט מתקנים.
- כל קריאת הפקה חייבת להיות אידמפוטנטית וממופתחת על מזהה ההזמנה שלכם. בקשה שנשלחת שוב ומפיקה חשבונית שנייה יוצרת מסמך שאי אפשר פשוט למחוק.
- הריצו קודם במצב טיוטה. הפיקו מסמכים אוטומטית אבל שאדם יאשר את ההנפקה בשבועות הראשונים - הבאגים שתמצאו יהיו בנתונים שלכם, לא ב-API.
מכל המערכות הפיננסיות הישראליות שעסק קטן עשוי לרצות לעשות להן אוטומציה, מורנינג (לשעבר חשבונית ירוקה) היא הידידותית ביותר. היא ענן-נייטיב, יש לה REST API מודרני עם אימות מבוסס טוקנים, והיא נבנתה בתקופה שבה אינטגרציה הייתה ציפייה ולא תוספת. השילוב הזה הופך אותה לפרויקט האוטומציה הראשון הטבעי להרבה עסקים.
המדריך הזה מכסה מה כדאי להפוך לאוטומטי, איזו ארכיטקטורה שורדת מגע עם פרודקשן, ואילו טעויות ספציפיות הופכות פרויקט של שבועיים לניקוי חשבונאי.
איך מחברים את חשבונית ירוקה (מורנינג) ל-CRM או לאתר של העסק?
דרך ה-API של מורנינג: יוצרים מפתח API בהגדרות המפתחים של מורנינג, מחליפים אותו בטוקן גישה שתקף לשעה, והאתר או ה-CRM שולחים POST /documents עם סוג המסמך, הלקוח ושורות ההכנסה. בכיוון ההפוך, webhook של payment/received או document/created מעדכן את ה-CRM. אנחנו בונים חיבורים כאלה; אוטומציה של תהליך אחד כזה מתומחרת ב-כ-900 - 5,400 ₪.
מה שווה להפוך לאוטומטי
בסדר ערך גס:
- הפקת מסמך כשהזמנה משולמת. קופה בחנות, קישור תשלום או אישור פגישה מפעילים את המסמך. זה מסיר את הכי הרבה עבודה ידנית יומית.
- חשבוניות חודשיות חוזרות. ריטיינרים ומנויים שמופקים לפי לוח זמנים מרשימה, במקום ידנית באחד לחודש.
- מהצעת מחיר לחשבונית. כשהצעה מתקבלת, המירו אותה במקום להקליד מחדש את השורות.
- התאמת תשלומים. משכו סטטוס מסמך ותשלום בחזרה למערכת שלכם כדי לדעת מה פתוח בלי להתחבר.
- סנכרון לקוחות. שמרו על רשימת הלקוחות מיושרת מול ה-CRM כדי שאף אחד לא ייווצר פעמיים עם פרטים מעט שונים.
לרוב העסקים מספיק הראשון כדי להצדיק את כל הפרויקט.
ה-API של מורנינג במבט אחד: כתובות, טוקן וקודי מסמכים
הערכים כאן לקוחים מתיעוד המפתחים של מורנינג ב-developers.morning.co; הכתובת הישנה greeninvoice.co.il/api-docs מפנה לשם היום.
| פריט | ערך |
|---|---|
| כתובת בסיס בייצור | https://api.greeninvoice.co.il/api/v1 |
| כתובת בסיס בסביבת הבדיקות | https://sandbox.d.greeninvoice.co.il/api/v1, עם מפתחות API נפרדים |
| טוקן גישה | POST https://api.morning.co/idp/v1/oauth/token עם grant_type: client_credentials, client_id ו-client_secret; בסביבת הבדיקות הכתובת היא https://api.sandbox.morning.dev |
| תוקף הטוקן | ה-accessToken שחוזר תקף לשעה ונשלח בכותרת Authorization: Bearer |
| יצירת מסמך | POST /documents; שדות חובה: type, lang, currency, vatType, income |
| שורת הכנסה | חובה: description, quantity, price, currency, vatType |
| קבלה על חשבונית קיימת | מעבירים את מזהה החשבונית ב-linkedDocumentIds, ומורנינג סוגרת את החשבונית המקורית |
סוג המסמך הוא מספר. הקודים שרוב האינטגרציות משתמשות בהם:
10- הצעת מחיר300- חשבון עסקה305- חשבונית מס320- חשבונית מס / קבלה330- חשבונית זיכוי400- קבלה
הגישה ל-API תלויה גם במסלול. נקודת הקצה של הטוקן מחזירה unauthorized_client כשהמסלול לא כולל גישת API, ונכון לזמן הכתיבה עמוד המחירים של מורנינג מציג API, אינטגרציות ו-Webhooks החל ממסלול Best.
מלכודת סוג המסמך
כאן כמעט כל אינטגרציה ראשונה נכשלת. החשבוניות בישראל מבחינות בין כמה סוגי מסמכים - הצעות מחיר, הזמנות, תעודות משלוח, חשבוניות מס, קבלות, וחשבונית-קבלה משולבת - והם לא ניתנים להחלפה. יש להם משמעויות משפטיות וחשבונאיות שונות, רצפי מספור שונים, ונהלי ביטול שונים.
לפני כתיבת קוד, שבו עם מי שמנהל לכם את הספרים וכתבו במפורש: לכל אירוע עסקי שיפעיל אוטומציה, איזה סוג מסמך צריך להיווצר. שימו את המיפוי הזה בקוד כקבוע עם שם, לא כמספר קסם קבור בגוף הבקשה.
טעות כאן היא לא באג שמטליאים. מסמך מס שהופק בטעות צריך להתבטל בתהליך זיכוי תקין, ואם הוא כבר נשלח ללקוח, יש גם שיחה לא נעימה.
ארכיטקטורה שעובדת
לעולם לא לקרוא ל-API ישירות מתוך מטפל ה-webhook
הדפוס שנכשל: webhook תשלום מגיע, המטפל קורא מיד ל-API החשבוניות, המטפל חוזר. כשה-API איטי או לא זמין לרגע, ה-webhook נכשל בפסק זמן, ספק הסליקה מנסה שוב, ואתם מפיקים שתי חשבוניות.
הדפוס שעובד: webhook מגיע, אתם כותבים משימת "הפק מסמך" למסד הנתונים שלכם עם מזהה ההזמנה, ומאשרים מיד. worker נפרד מרים את המשימה, קורא ל-API, רושם את מזהה המסמך שהתקבל, ומסמן את המשימה כהושלמה. ניסיונות חוזרים בטוחים כי המשימה ממופתחת על מזהה ההזמנה.
אידמפוטנטיות, ברצינות
לפני הפקה, בדקו במסד הנתונים שלכם אם כבר הופק מסמך כנגד מזהה ההזמנה הזה. אם קיים, החזירו אותו. הבדיקה הבודדת הזו היא מה שעומד בין תקלת רשת למסמך מס כפול.
שמרו את מזהה ומספר המסמך שהוחזרו מול ההזמנה. הרשומה הזו היא גם מה שתהליך התמיכה שלכם צריך כשלקוח מבקש את החשבונית שוב.
טיפול בטוקנים
ה-API של מורנינג משתמש בטוקנים קצרי-חיים שמתקבלים מאישורי גישה ארוכי-חיים. אל תמשכו טוקן חדש בכל בקשה ואל תשמרו אחד לנצח. שמרו במטמון עם תוקף, רעננו יזומה לפני שהוא פג, וטפלו ב-401 על ידי רענון אחד וניסיון חוזר. אישורי הגישה שייכים למאגר סודות, אף פעם לא לריפוזיטורי.
תור שגיאות עם טיוטת המסמך מצורפת
כשלים כאן הם בדרך כלל בעיות נתונים: לקוח עם מספר עוסק לא תקין, שורה בלי מחיר, סכום שלא מתאזן. המשימה שנכשלה צריכה להיות גלויה עם ה-payload המדויק וטקסט השגיאה מה-API, כדי שאפשר יהיה לתקן ולנסות שוב במקום ליצור מחדש ידנית.
ה-webhooks של מורנינג: מה הם שולחים ואיך מאמתים אותם
את ה-webhooks של מורנינג מגדירים בממשק של מורנינג, תחת כלי מפתחים ואז Webhooks, ולא דרך קריאת API. כל אירוע שנרשמתם אליו מגיע כבקשת HTTP POST עם גוף JSON. האירועים שחשובים ל-CRM או לאתר הם document/created, payment/received ו-client/created.
- אמתו את החתימה. כשמוגדר ל-webhook סוד, כל משלוח מגיע עם
x-webhook-signature: ה-HMAC-SHA256 של הגוף הגולמי, בקידוד hex. חשבו אותו על הבייטים הגולמיים לפני כל פענוח JSON, כי JSON שעבר סריאליזציה מחדש כבר לא יתאים. - סננו כפילויות לפי
x-webhook-delivery-id, המזהה הייחודי של כל משלוח. - אשרו מהר עם 200, 201, 202 או 204. כל סטטוס אחר, הפניה או timeout נחשבים משלוח שנכשל, ואחרי 15 כישלונות ה-webhook הופך ללא פעיל ומפסיק לשלוח.
הכלל האחרון הוא הסיבה שדפוס התור שתואר למעלה חשוב פעמיים. מטפל שמבצע עבודה איטית בתוך הבקשה מסכן מסמכים כפולים, ולאורך זמן הוא עלול לכבות את ה-webhook בלי שמשהו במערכת שלכם יגיד את זה. בדיקה לילית שמושכת את המסמכים האחרונים דרך POST /documents/search תופסת את מה ש-webhook מת פספס.
באילו שגיאות של ה-API של מורנינג נתקלים בפועל?
מורנינג מחזירה הודעות שגיאה בעברית לצד קוד מספרי, ולכן הקוד שלכם צריך להסתעף לפי המספר. אלה שעולות באינטגרציות של חשבוניות:
| קוד | משמעות |
|---|---|
| 401 | הגישה נדחתה - בדרך כלל טוקן של שעה שפג |
| 1007 | חסרה הרשאה מתאימה |
| 1010 | כבר קיימת בקשה עם נתונים זהים |
| 1108 | שיעור מע"מ לא תקין; הוא צריך להיות בין 0 ל-1, כלומר 0.18 ולא 18 |
| 1111 | מספר עוסק או ח"פ לא תקין |
| 1112 | החשבון הפיק החודש את כמות המסמכים המרבית |
| 1119 | גודל עמוד מעל 100 בחיפוש |
קוד 1112 מצדיק התראה משלו: אוטומציה שמפיקה פתאום יותר מסמכים מהרגיל עלולה להגיע אליו, ומאותו רגע לא מופקים מסמכים חדשים עד שמסדירים את החשבון.
הריצו קודם במצב טיוטה
בשבוע עד שבועיים הראשונים, שהאוטומציה תיצור מסמכים בטיוטה ותדרוש אישור אנושי להפקה. זו לא פחדנות - זו הדרך לגלות ש-3% מרשומות הלקוחות שלכם מכילות מספר עוסק עם רווח בסוף, או שהחנות שולחת את עלות המשלוח כשורה נפרדת שרואה החשבון רוצה ממוזגת.
ברגע ששלב האישור מפסיק לתפוס משהו, הסירו אותו.
לוח זמנים ועלות
| היקף | בנייה טיפוסית |
|---|---|
| הפקת מסמך בתשלום הזמנה, טריגר אחד, תור שגיאות | 1-2 שבועות |
| בתוספת חשבוניות חוזרות וסנכרון לקוחות | 2 - 3 שבועות |
| בתוספת התאמת תשלומים בחזרה ל-CRM או דשבורד | 3 - 4 שבועות |
זו אחת האינטגרציות הזולות שיש, ובדיוק לכן זה מקום טוב להתחיל בו: היא מוכיחה את התבנית, מייצרת ערך יומי גלוי, והצוות לומד בשביל מה תור שגיאות לפני שהסיכון עולה.
הסתייגות אחת
חשבוניות יושבות בשטח מס ורגולציה, והכללים שחלים על העסק שלכם הם שאלה לרואה החשבון, לא למפתח. קבעו את מיפוי המסמכים ואת מדיניות ההפקה יחד איתו, השאירו אדם בלולאת האישור עד שיש ביטחון, ובדקו את תיעוד ה-API העדכני במקום להסתמך על מדריך כלשהו - כולל זה - לפרטי שדות ונקודות קצה מדויקים.
לאפיון אוטומציית חשבוניות למערך שלכם, קבעו שיחה ללא עלות. קשור: איך לעשות אוטומציה לחשבוניות, הסטאק הישראלי ומה מתחבר למה, חיבור תוכנת חשבוניות ל-CRM, והשוואת ה-API של מערכות החשבוניות בישראל.
מקורות
שאלות נפוצות
האם למורנינג (חשבונית ירוקה) יש API?
כן. מורנינג מספקת REST API מודרני עם אימות מבוסס טוקנים שמכסה יצירת מסמכים, לקוחות וסטטוס מסמכים. זו אחת המערכות הפיננסיות הישראליות הפשוטות יותר לאינטגרציה, בעיקר כי היא תוכננה כמוצר ענן מלכתחילה. עבדו תמיד מול התיעוד הרשמי העדכני לנקודות קצה ושמות שדות מדויקים, כי אלה משתנים עם הזמן.
איזה סוג מסמך האוטומציה צריכה להפיק?
זו החלטה חשבונאית ולא טכנית, וצריך לקבל אותה עם רואה החשבון לפני שנכתב קוד. החשבוניות בישראל מבחינות בין הצעות מחיר, הזמנות, תעודות משלוח, חשבוניות מס, קבלות וחשבונית-קבלה, ולכל אחת משמעות משפטית, מספור ונוהל ביטול שונים. מפו כל טריגר עסקי לסוג מסמך במפורש וקודדו את המיפוי כקבוע עם שם ולא כערך קבור בבקשה.
מה קורה אם אותה חשבונית מופקת פעמיים?
יש לכם בעיה חשבונאית אמיתית, לא משימת ניקוי נתונים - מסמך מס כפול צריך להתבטל בתהליך זיכוי תקין, ואם הוא הגיע ללקוח יש גם בעיית שירות. לכן כל מסלול הפקה חייב להיות אידמפוטנטי: מפתחו את הפעולה על מזהה ההזמנה שלכם, בדקו אם כבר הופק מסמך לפני קריאה ל-API, ושמרו את מזהה המסמך שחזר. עם הבדיקה הזו, webhook שנשלח שוב הופך ללא-פעולה במקום לחשבונית שנייה.
כמה זמן לוקח לבנות את האינטגרציה הזו?
זרם יחיד - הפקת מסמך כשהזמנה משולמת, עם תור משימות תקין וטיפול בשגיאות - הוא בדרך כלל שבוע עד שבועיים. הוספת חשבוניות חוזרות וסנכרון לקוחות מביאה לשלושה-ארבעה שבועות. משיכת סטטוס תשלום בחזרה ל-CRM או דשבורד מוסיפה עוד כשבועיים. זו אחת האינטגרציות השימושיות הזולות שיש, ולכן היא פרויקט ראשון טוב.
צריך שאדם עדיין יאשר חשבוניות אחרי האוטומציה?
בשבועות הראשונים, כן. שהאוטומציה תיצור מסמכים בטיוטה ותדרוש אישור לפני הפקה. כך מוצאים את בעיות הנתונים שמופיעות רק בנפח - רשומות לקוח עם מספרי עוסק לא תקינים, דמי משלוח שצריך למזג לשורה, עיגול שלא תואם למה שרואה החשבון מצפה. ברגע ששלב האישור מפסיק לתפוס משהו לאורך זמן, הסירו אותו.
האם ל-API של חשבונית ירוקה (מורנינג) יש סביבת בדיקות?
כן. כתובת הבסיס של סביבת הבדיקות היא https://sandbox.d.greeninvoice.co.il/api/v1, והטוקנים אליה מתקבלים מ-https://api.sandbox.morning.dev. לכל סביבה נדרשים מפתחות API משלה, כך שמפתחות הייצור לא יעבדו בסביבת הבדיקות. מורנינג ממליצה לבנות ולבדוק שם את האינטגרציה לפני המעבר לייצור.
כמה זמן תקף טוקן הגישה של ה-API של מורנינג?
שעה. נקודת הקצה של הטוקן מחזירה accessToken, טוקן JWT חתום שמוגבל לעסק של מפתחות ה-API שלכם. אחרי שעה הקריאות מחזירות 401 Unauthorized, ומבקשים טוקן חדש עם אותם client_id ו-client_secret. כדאי לשמור את הטוקן במטמון עם זמן התפוגה שלו ולחדש אותו קצת לפני שהוא פג.
איזה מסלול של מורנינג כולל גישת API?
נכון לזמן הכתיבה, עמוד המחירים של מורנינג מציג אוטומציות באמצעות API, אינטגרציות ו-Webhooks במסלולי Best ו-Extra, ומסלול Prime כולל את כל מה שיש ב-Extra; במסלול Basic זה לא מופיע. כשהמסלול לא כולל גישת API, נקודת הקצה של הטוקן מחזירה את השגיאה unauthorized_client.
להמשך קריאה
שירות רלוונטי
אינטגרציה בין מערכות
לגרום למערכות שאתם כבר משלמים עליהן לדבר זו עם זו.
יש לך פרויקט דומה?
ספר לי מה אתה רוצה לבנות או איזה תהליך להפוך לאוטומטי. אני חוזר תוך 24 שעות עסקים עם כמה שאלות ממוקדות, ואז עוברים על זה יחד בשיחת היכרות חינמית של 30 דקות, בלי התחייבות. בסוף יש לך היקף עבודה, לוח זמנים ומחיר קבוע - או תשובה כנה שלא שווה לבנות את זה.