ה-API של סאמיט - יהונתן סעדיה

לסאמיט יש REST API שמכסה גם הפקת מסמכים וגם סליקה, מה שהופך אותה לחריגה בשוק הישראלי - ומייצר החלטה תכנונית אחת שחייבים לפתור לפני שכותבים קוד.

עיקרי הדברים

סאמיט מכסה חשבוניות וסליקה במערכת אחת. זה מבטל את התפר הרגיל בין סולק למערכת חשבוניות - המקור הנפוץ ביותר למסמכי מס כפולים.

יכולות האינטגרציה תלויות באילו מודולים מותקנים ומוגדרים. יש לוודא שהמודול הנדרש מופעל בחשבון לפני התמחור, כי זו החלטת רכש ולא בעיה בקוד.

את מבנה הבקשה המדויק יש לקחת מהתיעוד הרשמי בפורטל המפתחים. כל מתודה מתעדת את המבנה שלה, וזה המקור המחייב ולא מאמר כלשהו.

כלל הניסיון החוזר זהה לכל מערכת חשבוניות: timeout אינו כישלון. יש לבדוק אם המסמך כבר קיים לפני ניסיון חוזר, אחרת מפיקים שני מסמכי מס שדורשים ביטול ידני.

סאמיט (SUMIT) חושפת REST API שמכסה שני תחומים שבדרך כלל חיים בשתי מערכות נפרדות: הפקת מסמכים וסליקת אשראי. זה הופך אותה לחריגה בשוק הישראלי, ומשנה את אופי האינטגרציה - לטובה, אם מתכננים נכון.

התיעוד הרשמי יושב בפורטל המפתחים ב-app.sumit.co.il/developers/api/, וכל מתודה מתעדת שם את המבנה המדויק של הקריאה. זה המקור המחייב - המאמר הזה עוסק בהחלטות, לא במבנה השדות.

מה ה-API מכסה

מסמכים - חשבונית מס, קבלה, דרישת תשלום, חשבון עסקה ומסמכים נוספים.
סליקה והוראות קבע - יצירת עסקת אשראי, הקמת הוראת קבע, והפעלת תהליך Redirect לסליקה מאובטחת מתוך אתר.

הצירוף הזה הוא הנקודה המעניינת. ברוב הפרויקטים הישראליים הסולק ומערכת החשבוניות הם שני ספקים נפרדים, ואת התפר ביניהם צריך לבנות ולתחזק.

היתרון האמיתי: תפר אחד פחות

הטעות התכנונית הנפוצה ביותר כשמחברים סליקה והנהלת חשבונות היא הפקה כפולה: הסולק מוגדר להפיק מסמך אוטומטית בעקבות תשלום, והמערכת שלך גם מפיקה - ונוצרים שני מסמכי מס על עסקה אחת. זה מתגלה בסוף החודש, אצל רואה החשבון.

כשהסליקה והמסמכים חיים באותה מערכת, התפר הזה פשוט לא קיים. זה יתרון אמיתי, במיוחד לעסקים שגובים באתר ומפיקים מסמך מיד.

אבל הוא לא מבטל את ההחלטה - הוא מזיז אותה. עדיין צריך להחליט מפורשות: האם המסמך נוצר כחלק מזרימת הסליקה, או בקריאה נפרדת מהמערכת שלך אחרי שהתשלום אושר? שתי הדרכים לגיטימיות. מה שלא לגיטימי הוא לא להחליט, ואז לגלות שיש שתיים.

מודולים - לברר לפני שמתמחרים

יכולות האינטגרציה בסאמיט תלויות באילו מודולים מותקנים בחשבון ובהגדרת מפתחות ה-API. תהליך ההקמה כולל התקנת המודול הרלוונטי לפני שהממשק זמין.

המשמעות המעשית: אם החשבון של הלקוח לא כולל את המודול שהתכנון שלך מסתמך עליו, זו החלטת רכש ולא בעיה טכנית. יש להעלות אותה למי שמחליט על תקציב מיד, ולא לנסות לעקוף אותה בקוד.

לברר לפני התמחור, בכתב: אילו מודולים פעילים, ומה נדרש עבור התרחיש הספציפי.

ההחלטות שנשארות - זהות לכל מערכת חשבוניות

בעיית הניסיון החוזר

שולחים בקשה, השרת מפיק את המסמך, החיבור נופל לפני שהתשובה חוזרת. הקוד רואה timeout, מפרש ככישלון, מנסה שוב - וכעת יש שני מסמכי מס עם שני מספרים רצים. מסמך מס אינו ניתן למחיקה; ביטול נעשה במסמך נגדי.

timeout אינו כישלון - הוא חוסר ידיעה. אל תנסה שוב אוטומטית.
שמור מזהה ייחודי משלך על ההזמנה, ולפני כל ניסיון חוזר בדוק אם כבר קיים מסמך שמתאים לו.
מסמך חסר עדיף על מסמך כפול.

איזה מסמך, ומתי

חשבונית מס, קבלה, דרישת תשלום וחשבון עסקה אינם ניתנים להחלפה - הבחירה קובעת מתי מוכרת ההכנסה. זו החלטה של רואה החשבון של העסק, ואם המערכת שלך בוחרת אוטומטית, ההיגיון צריך אישור בכתב.

מע"מ ועוסק פטור

לאמת מול מסמך אמיתי איך המערכת מצפה לקבל סכומים - כולל או לא כולל מע"מ. ועוסק פטור אינו מפיק חשבונית מס כלל; אם המערכת משרתת יותר מסוג עוסק אחד, זה משנה את סוג המסמך.

מספר הקצאה

דרישת רשות המסים חלה בלי קשר למערכת. ראה מספר הקצאה למפתחים.

סליקה: מה שנכון בכל סולק

אם אתה משתמש בזרימת ה-Redirect לסליקה מתוך אתר, שלושת הכללים האלה חלים כאן בדיוק כמו בקארדקום או בPayPlus:

ההפניה בדפדפן אינה מקור אמת. לקוח שסוגר את הלשונית ברגע שהתשלום עבר לא יגיע לדף התודה, וההזמנה תישאר "ממתינה" למרות שהכסף נגבה. עדכון המצב מגיע מהודעת שרת-לשרת.
אידמפוטנטיות. אותה הודעה יכולה להגיע פעמיים.
להצליב סכום מול ההזמנה, בצד השרת, תמיד.

ולא לגעת בפרטי כרטיס. זה כל היתרון של Redirect, והוא מחזיק רק אם אתה לא שולח, מתעד או שומר אותם.

אבטחה

מפתחות ה-API מאפשרים הפקת מסמכי מס וגביית כספים בשם העסק. משתני סביבה או מנהל סודות בלבד - לא בקוד המקור, לא בלוגים, ולא בשום קוד שרץ בדפדפן.

ולשמור את תשובת ה-API המלאה גם בהצלחה: מזהה המסמך, מספרו והקישור אליו. זו הראיה היחידה כשמגיעה שאלה מהנהלת החשבונות בעוד חצי שנה.

צ'קליסט

לפתוח את התיעוד בפורטל המפתחים ולעבוד מולו - לא מדוגמה שמצאת.
לברר בכתב אילו מודולים פעילים בחשבון.
להחליט מפורשות מי מפיק את המסמך: זרימת הסליקה או המערכת שלך.
לקבל מרואה החשבון בכתב אילו מסמכים מופקים ובאיזה רגע.
לאמת מע"מ מול מסמך אמיתי.
לבנות הגנה מפני כפילות לפני שמפיקים מסמך ראשון בייצור.

שאלות נפוצות

האם לסאמיט יש API?

כן. לסאמיט יש REST API מתועד בפורטל המפתחים, app.sumit.co.il/developers/api/, שמכסה יצירת מסמכים - חשבוניות מס, קבלות, דרישות תשלום וחשבונות עסקה - וגם סליקת אשראי, הוראות קבע וזרימת Redirect לתשלום מאובטח מאתר. כל מתודה מתעדת שם את מבנה הבקשה שלה.

מה היתרון בכך שסאמיט מטפלת גם בסליקה וגם בחשבוניות?

זה מבטל את התפר שבו בדרך כלל מופיעים מסמכי מס כפולים. כשסולק נפרד מוגדר להפיק מסמך בתשלום וגם המערכת שלך מפיקה, עסקה אחת מייצרת שניים - טעות התכנון הנפוצה ביותר בפרויקטים ישראליים. כששניהם במערכת אחת התפר לא קיים, אם כי עדיין צריך להחליט מפורשות אם המסמך נוצר בזרימת הסליקה או בקריאה נפרדת.

האם יכולות ה-API של סאמיט תלויות במודולים?

כן. יכולת האינטגרציה תלויה באילו מודולים מותקנים בחשבון, לצד הגדרת מפתחות API - ההקמה כוללת התקנת המודול הרלוונטי לפני שהממשק נעשה זמין. יש לוודא בכתב אילו מודולים פעילים לפני התמחור, כי מודול חסר הוא החלטת רכש שצריך להעלות ולא בעיה טכנית לפתור בקוד.

איך נמנעים מחשבוניות כפולות כשקריאה לסאמיט מקבלת timeout?

לא לנסות שוב אוטומטית. timeout אומר שאינך יודע אם המסמך הופק, ומסמך מס שהופק לא ניתן למחיקה - רק לקיזוז במסמך נגדי. יש לשמור מזהה ייחודי משלך על ההזמנה ולבדוק אם כבר קיים מסמך לפני כל ניסיון חוזר. מסמך חסר מתוקן בדקה; מסמך כפול דורש ביטול ותיעוד.

האם אפשר לסמן הזמנה כמשולמת בדף ההפניה של סאמיט?

לא - להשתמש בהודעת שרת-לשרת במקום. ההפניה בדפדפן תלויה בכך שהלקוח יישאר בדף, וכל מי שסוגר את הלשונית ברגע שהתשלום עובר לעולם לא מגיע אליה, וההזמנה נשארת ממתינה בזמן שהכסף נגבה. ההפניה צריכה רק להציג מסך תודה, ונקודת הקצה המקבלת חייבת להיות אידמפוטנטית ולהצליב את הסכום.

ה-API של סאמיט: מסמכים וסליקה ממערכת אחת