מדריך למפתחים ל-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 של השירות. זה המקור שכדאי לפתוח לפני שכותבים שורה - הוא מציג את הפעולות הקיימות ואת מבנה הבקשה של כל אחת, מול הגרסה שרצה בפועל.
Document.New: מה שולחים ומה חוזר
תיעוד ה-API של רווחית מסמן חמישה שדות חובה בפעולה Document.New: api_token, document_type, customer_id, last_name ו-items. הכול נשלח בגוף ה-JSON, כולל הטוקן - אין כותרת Authorization.
| שדה | מה הוא מכיל | שים לב |
|---|---|---|
api_token | טוקן ה-API של העסק | בריווחית אונליין הוא נמצא בהגדרות, הגדרות Online, לשונית API; בחשבונית אונליין בהגדרות, הגדרות מערכת |
document_type | סוג המסמך, כמספר שלם | את הקודים שהחשבון שלך משתמש בהם כדאי לקרוא מ-Document.TypeList ולא לקבע בקוד |
customer_id, last_name | מזהה הלקוח ברווחית, ושם המשפחה או שם החברה | last_name מוגבל ל-30 תווים, first_name ו-city ל-20 |
acc_ref | המזהה של הלקוח במערכת שלך | עד 9 תווים, כך שמזהה ארוך מה-CRM לא ייכנס |
items | שורות עם catalog_number, description, quantity, price_nis | הבקשה כולה מוגבלת ל-64KB; מעבר לזה חוזרת שגיאת HTTP 413 |
payments | חובה בקבלה ובחשבונית מס קבלה | payment_type 1 הוא המחאה, 2 מזומן, ו-4 עד 8 כרטיסי אשראי לפי הגדרות התשלום שלך |
send_mail | האם רווחית שולחת את המסמך ללקוח במייל | ברירת המחדל היא true, ולכן כדאי לקבוע אותו במפורש בזמן בדיקות |
תשובה מוצלחת מחזירה document_number, document_link ו-confirmation_number - מספר ההקצאה מרשות המסים, כשהוא נדרש. אם מסמך הופק בלעדיו כי החיבור לרשות המסים נכשל, התיעוד מפנה לפעולה Document.InvoiceApproval כדי לבקש את המספר בדיעבד.
ההחלטה שקובעת הכול: סוג המסמך
שדה סוג המסמך אינו פרט טכני - הוא קובע גם את המשמעות המשפטית וגם אילו שדות הבקשה חייבת להכיל.
הכלל המרכזי: מסמכים שמייצגים קבלת כסף דורשים אובייקט תשלום. קבלה, וכן חשבונית מס קבלה (סוג מסמך 2), לא ייווצרו בלי פירוט התשלום. יתרה מזו, לכל אמצעי תשלום יש שדות חובה משלו - מזומן, המחאה, כרטיס אשראי והעברה בנקאית אינם מקבלים את אותו מבנה. שליחת אובייקט תשלום גנרי תיכשל.
לעומת זאת, חשבונית שאינה מלווה בתשלום, תעודת משלוח או הזמנה אינן דורשות אובייקט כזה.
המסקנה התכנונית: אל תבנה פונקציה אחת גנרית שמקבלת "סוג מסמך" כפרמטר ומקווה לטוב. לכל סוג מסמך שהמערכת שלך מפיקה, בנה מסלול מפורש עם הוולידציה שלו. מסמך שנכשל בגלל שדה חסר עדיף בהרבה על מסמך שנוצר לא נכון.
הבעיה שתופסת כל אינטגרציה ראשונה: ניסיון חוזר
מסמך מס שהופק אינו ניתן לעריכה ואינו ניתן למחיקה. ביטול נעשה במסמך נגדי.
מכאן התרחיש שחוזר: שולחים בקשה ליצירת מסמך, השרת מפיק אותו, והחיבור נופל לפני שהתשובה הגיעה. הקוד רואה timeout, מפרש ככישלון, ומנסה שוב - וכעת יש שני מסמכי מס עם שני מספרים רצים, ואחד מהם דורש ביטול ידני בהנהלת החשבונות.
שלוש הנחיות:
- אל תנסה שוב אוטומטית אחרי timeout. timeout אינו כישלון - הוא חוסר ידיעה.
- שמור מזהה ייחודי משלך על ההזמנה או העסקה, ולפני כל ניסיון חוזר בדוק אם כבר קיים מסמך שמתאים לו.
- מסמך חסר עדיף על מסמך כפול. הראשון מטופל בדקה, השני דורש ביטול ותיעוד.
לרווחית יש מנגנון מובנה בדיוק לזה. המדריך "Prevent Duplicates" בתיעוד שלה מתאר שני פרמטרים בבקשות Document.New ו-Receipt.New: request_reference, מפתח ייחודי שאתה מייצר לכל פעולה (מספר הזמנה או UUID), ו-prevent_duplicates: true. כששולחים את שניהם, בקשה חוזרת עם אותו מפתח ואותו תוכן מפיקה את המסמך פעם אחת בלבד. אם המפתח הוא מזהה ההזמנה שלך, ניסיון חוזר אחרי timeout מפסיק להיות מסוכן - אבל כלל הבדיקה לפני ניסיון חוזר נשאר בתוקף למסמכים שהופקו לפני שהפעלת את המנגנון.
iCredit - הצד השני של רווחית
iCredit הוא שער הסליקה. הוא מכסה דפי תשלום דינמיים, טוקניזציה של אמצעי תשלום, חיובים חוזרים והפקת מסמכים אוטומטית בעקבות תשלום.
ההחלטה שצריך לקבל מוקדם: מי מפיק את המסמך? אם הסליקה מוגדרת להפיק מסמך אוטומטית בעקבות תשלום מוצלח, והמערכת שלך גם מפיקה מסמך משלה - יהיו שני מסמכים על אותה עסקה. זו לא תקלה נדירה; זו טעות התכנון הנפוצה כשמחברים סליקה והנהלת חשבונות באותו פרויקט.
יש לבחור צד אחד ולתעד אותו.
אם iCredit מדווחת לשרת שלך על תשלומים, להודעה הזו (IPN) יש כלל זמנים משלה: השרת חייב להחזיר 200 OK תוך 1.25 שניות, אחרת iCredit שולחת את ההודעה שוב. לכן נכון לשמור את ההודעה, לענות מיד ולעבד אחר כך, ולהתייחס ל-IPN שני על אותה עסקה ככפילות. לפני שמסמנים הזמנה כשולמה, התיעוד מורה לאמת את ההודעה בפעולה Verify עם GroupPrivateToken, TotalAmount ו-SaleId.
האם יש סביבת בדיקות ל-API של ריווחית?
כן, אבל לא בשרת נפרד. לפי עמוד סביבת הבדיקות של רווחית, ה-API משתמש בכתובת הייצור בכל הסביבות, ובדיקה פירושה קריאה עם פרטי הגישה של חשבון הדגמה משותף שהתיעוד מפרסם. ארבע נקודות מאותו עמוד חשוב להכיר לפני שסומכים עליו:
- חשבון ההדגמה משותף, וכל מה שנמצא בו גלוי לכל מי שבודק בו, ולכן נתוני לקוחות אמיתיים לא נכנסים אליו.
- אסור להשתמש בחשבונות הבדיקה להפקת מסמכים חוקיים אמיתיים.
- חשבון ההדגמה לא מחובר ל-iCredit, כך שאי אפשר לבדוק דרכו סליקת אשראי.
- מגבלת הקצב של ה-API היא 200 בקשות בדקה. סנכרון לילי שמושך מסמכים אחד אחד צריך האטה.
באותו עמוד מצוין שה-API קיים רק לרווחית Online ולחשבונית אונליין. לגרסה המקומית (השולחנית) של רווחית אין API, ולכן עסק שעדיין עובד בה צריך לעבור למוצר המקוון לפני שאפשר לחבר אליו משהו.
איך נראות שגיאות ב-API של רווחית?
רווחית מדווחת על שגיאה בשתי שכבות: סטטוס ה-HTTP, וגוף JSON עם error_code, client_message (בדרך כלל בעברית), debug_message (מזהה באנגלית) ו-data. כדאי לרשום בלוג את ארבעתם; ההודעה בעברית מיועדת לאדם, ועל קוד ה-debug הקוד שלך צריך להסתעף.
| קוד | debug_message | הסיבה הנפוצה |
|---|---|---|
| -20 | CUSTOMER_NOT_EXISTS | customer_id שלא קיים בעסק הזה |
| -23 | HENTYPE_NOT_EXISTS | קוד סוג מסמך שלא קיים בחשבון |
| -28 | INVALID_ID_NUMBER | מספר ת"ז לא תקין |
| -29 | INVALID_VAT_NUMBER | מספר עוסק (ע"מ) לא תקין |
| -94 | INVALID_AMOUNT | סכום שהשירות דוחה |
שגיאת 400 שחוזרת כדף HTML בכותרת "Request Error" היא בעיה אחרת: שכבת ה-WCF לא הצליחה לפענח את הבקשה בכלל. הסיבות הנפוצות הן JSON פגום, כותרת Content-Type חסרה, או JSON שנשלח לנקודת קצה שמצפה ל-SOAP.
מה לשמור אצלך
- מזהה המסמך ומספרו הרץ
- הקישור למסמך, כדי לא לייצר אותו מחדש
- סוג המסמך והחותמת
- תשובת ה-API המלאה, גם בהצלחה - זו הראיה היחידה במקרה של מחלוקת או בירור מול הנהלת החשבונות
מה צריך לסגור לפני שכותבים קוד?
- סוגי המסמכים. אילו מסמכים המערכת מפיקה, ובאיזה רגע בתהליך. זו החלטה של רואה החשבון של העסק ולא של המפתח, כי היא קובעת מתי מוכרת ההכנסה.
- מע"מ. האם הסכומים שאתה שולח כוללים מע"מ או לא. לאמת מול מסמך אמיתי, לא להניח.
- עוסק פטור. עסק פטור אינו מפיק חשבונית מס. אם המערכת משרתת יותר מסוג עוסק אחד, זה משנה את סוג המסמך.
- מספר הקצאה. לוודא שהתהליך מטפל בדרישת רשות המסים לפני העלייה לאוויר. ראה מספר הקצאה למפתחים.
- סודות. פרטי הגישה מאפשרים הפקת מסמכי מס בשם העסק. משתני סביבה או מנהל סודות בלבד - לא בקוד המקור, לא בלוגים, ולא בצד הלקוח.
להשוואה בין המערכות הישראליות מבחינת קלות החיבור, ראה השוואת ה-API של מערכות החשבוניות בישראל, ולצד של סנכרון הלקוחות - חיבור תוכנת חשבוניות ל-CRM.
מקורות
שאלות נפוצות
האם לרווחית יש 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 של ריווחית?
לא בשרת נפרד. ה-API של רווחית משתמש בכתובת הייצור בכל הסביבות, והבדיקות נעשות בחשבון הדגמה משותף שפרטי הגישה אליו מפורסמים בתיעוד. הנתונים בו גלויים לכל מי שבודק, אסור להפיק בו מסמכים חוקיים אמיתיים, והוא לא מחובר ל-iCredit, כך שאי אפשר לבדוק בו סליקת אשראי.
מהי מגבלת הקצב של ה-API של רווחית?
רווחית מתעדת תקרה של 200 בקשות בדקה, וגודל בקשה מרבי של 64KB - גוף גדול יותר מחזיר שגיאת HTTP 413, בדרך כלל כי מסמך אחד מכיל יותר מדי שורות או תיאורים ארוכים מאוד. תהליך סנכרון שקורא מסמכים אחד אחד צריך האטה כדי להישאר מתחת לתקרה לדקה.
איפה מוצאים את טוקן ה-API של רווחית?
בריווחית אונליין הוא נמצא בהגדרות, הגדרות Online, בלשונית API; בחשבונית אונליין הוא נמצא בהגדרות, הגדרות מערכת. הטוקן נשלח בשדה api_token בגוף ה-JSON של כל קריאה, לא בכותרת, והוא מאפשר להפיק מסמכי מס בשם העסק - ולכן הוא נשמר בצד השרת בלבד.
להמשך קריאה
שירות רלוונטי
אינטגרציה בין מערכות
לגרום למערכות שאתם כבר משלמים עליהן לדבר זו עם זו.
יש לך פרויקט דומה?
ספר לי מה אתה רוצה לבנות או איזה תהליך להפוך לאוטומטי. אני חוזר תוך 24 שעות עסקים עם כמה שאלות ממוקדות, ואז עוברים על זה יחד בשיחת היכרות חינמית של 30 דקות, בלי התחייבות. בסוף יש לך היקף עבודה, לוח זמנים ומחיר קבוע - או תשובה כנה שלא שווה לבנות את זה.