ה-API של רווחית - יהונתן סעדיה

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

עיקרי הדברים

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

מדובר בשירות בסגנון WCF ולא ב-REST API מודרני. הפעולות הן נקודות קצה בשם כמו Document.New ולא משאבים עם פעלים של HTTP, ולכן הרגלי REST יטעו אותך.

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

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

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

מה זה בעצם: לא REST מודרני

הבסיס הוא https://api.rivhit.co.il/online/RivhitOnlineAPI.svc, ויצירת מסמך היא הפעולה Document.New.

שים לב לצורה: זהו שירות בסגנון WCF - פעולות בשם, לא משאבים עם פעלים. אין POST /documents ואין DELETE /documents/123. יש נקודת קצה אחת לכל פעולה, וכולן מקבלות POST. אם אתה מגיע מ-REST, הציפייה הזו תבלבל אותך יותר מכל דבר אחר בממשק.

התיעוד הרשמי יושב ב-rivhit-api.readme.io, ורשימת הפעולות החיה זמינה ישירות בנתיב /help של השירות. זה המקור שכדאי לפתוח לפני שכותבים שורה - הוא מציג את הפעולות הקיימות ואת מבנה הבקשה של כל אחת, מול הגרסה שרצה בפועל.

ההחלטה שקובעת הכול: סוג המסמך

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

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

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

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

הבעיה שתופסת כל אינטגרציה ראשונה: ניסיון חוזר

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

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

שלוש הנחיות:

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

iCredit - הצד השני של רווחית

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

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

יש לבחור צד אחד ולתעד אותו.

מה לשמור אצלך

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

מה לסגור לפני שכותבים קוד

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

להשוואה בין המערכות הישראליות מבחינת קלות החיבור, ראה השוואת ה-API של מערכות החשבוניות בישראל.

שאלות נפוצות

האם לרווחית יש API?

כן. רווחית Online חושפת API למסמכים בכתובת https://api.rivhit.co.il/online/RivhitOnlineAPI.svc, שבו יצירת מסמך היא הפעולה Document.New. לרווחית יש גם iCredit, שער סליקה נפרד עם הרשאות משלו. התיעוד מפורסם ב-rivhit-api.readme.io, ורשימת הפעולות החיה נמצאת בנתיב ‎/help של השירות.

למה יצירת קבלה ברווחית נכשלת עם שדות חסרים?

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

האם ה-API של רווחית הוא REST?

לא במובן המודרני. זהו שירות בסגנון WCF שבנוי סביב פעולות בשם כמו Document.New, שכולן מופעלות ב-POST, ולא סביב משאבים עם פעלים של HTTP. אין DELETE על מסמך ואין מבנה כתובות של משאב לכל ישות, ולכן הנחות של REST יטעו אותך בקריאת התיעוד.

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

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

מי צריך להפיק את החשבונית - iCredit או המערכת שלי?

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

ה-API של רווחית: הפקת מסמכים וגביית תשלומים