מדריך טכני ל-API של WizCloud: יצירת session, קבוצות ה-endpoints לייבוא, והוצאת נתונים דרך ExportDataApi לפי דוח שתוכנן מראש במחולל הדוחות ומה חוזר בתשובה.
עיקרי הדברים
- התיעוד הרשמי הוא docs.wizcloud.co.il, בגרסה 2.0.0. זה לא API סמוי שצריך לחלץ מתמיכה.
- ההזדהות דורשת שלושה ערכים מהגדרות החשבון: WizcloudApiServer, WizcloudApiPrivateKey ו-WizcloudApiDBName.
- קריאת GET אחת ל-createSession מחזירה wizAuthToken שתקף 24 שעות. כל השאר הן קריאות POST שנושאות את הטוקן.
- ייצוא נתונים אינו שאילתה. מתכננים דוח במחולל הדוחות, מייצאים אותו כקובץ External, ושולחים את תוכנו ל-ExportDataApi/exportData.
- קובץ ה-External מכיל datafile - מחרוזת מוצפנת שמתארת את מבנה הדוח - ומערך parameters שרק בו משנים ערכים בזמן ריצה.
ל-WizCloud יש API מתועד ציבורית בכתובת docs.wizcloud.co.il, וההפרדה שבו קובעת את כל תכנון האינטגרציה: ייבוא נעשה מול endpoints ייעודיים לפי סוג הרשומה, אבל הוצאת נתונים עוברת דרך endpoint יחיד שמריץ דוח שתכננתם מראש בתוך המערכת עצמה. אין שאילתה חופשית מול בסיס הנתונים.
מה זה WizCloud ומה היחס ל-WizCount ולחשבשבת
WizCloud היא סביבת הענן של חשבשבת, ו-WizCount הוא השם האנגלי של אותה משפחת מוצרים. מבחינת אינטגרציה זה מקשה אחת: אותו API, אותו תיעוד, אותה חלוקה לקבוצות endpoints. חיפוש אחרי "WizCount API" ואחרי "API חשבשבת בענן" מוביל לאותו מקום.
ההבחנה שכן חשובה היא בין הענן לבין חשבשבת בחלונות. ה-API שמתואר כאן מדבר עם בסיס הנתונים בענן, ומזהה אותו לפי קוד בסיס נתונים שמועבר בקריאת ההזדהות. התקנה מקומית של חשבשבת היא עולם אינטגרציה אחר לגמרי, ומי שמערבב ביניהם מגלה את זה רק אחרי שהאישורים לא עובדים.
איך עובדת ההזדהות מול WizCloud?
ההזדהות היא דו-שלבית, ואת שלב אחת מריצים פעם אחת בלבד לפני שאר הקריאות. שולפים מהגדרות החשבון שלושה ערכים - שם השרת, מפתח פרטי וקוד בסיס הנתונים - ושולחים קריאת GET לנתיב createSession שמורכב משלושתם. בתשובה מתקבל wizAuthToken.
הטוקן תקף 24 שעות, וזו נקודת התכנון האמיתית. תהליך שרץ פעם ביום יכול לייצר טוקן בכל הרצה. תהליך שרץ כל חמש דקות חייב לשמור את הטוקן במקום משותף ולחדש אותו רק כשהוא פג, אחרת אתם יוצרים sessions בקצב שאין לו שום סיבה. שמירת הטוקן בזיכרון של תהליך יחיד נשברת ברגע שמריצים שני workers.
שלושת ערכי ההזדהות הם סוד לכל דבר. מפתח פרטי שנשמר בקוד או בקובץ תצורה שנכנס ל-repository הוא גישה מלאה לספרים של הלקוח.
קבוצות ה-endpoints ומה כל אחת עושה
| קבוצה | דוגמאות לנתיבים | לאיזה שימוש |
|---|---|---|
| session | createSession | קבלת wizAuthToken מול בסיס נתונים מסוים |
| jtransApi | tmpBatch, chkBatch, newBatch, issueBatch | ייבוא תנועות יומן במנות, כולל בדיקת שגיאות לפני קליטה |
| IndexApi | importIndex | ייבוא או עדכון רשומות אינדקס |
| invApi | createDoc, getDoc, delDocument, issueDocument | מסמכים: יצירה, שליפה, מחיקה והפקה |
| docsApi | createRecipt, createInvRecipt | קבלות וחשבוניות מס-קבלה |
| BankPagesApi | importBankPage | ייבוא דפי בנק |
| SortCodeApi, TransTypesApi | importSortCodes, importTransTypes | ייבוא קודי מיון וסוגי תנועה |
| TriggersApi | setURL, deleteURL, updateURL, getURL | ניהול כתובות שאליהן המערכת פונה |
| ExportDataApi | exportData | הוצאת נתונים לפי דוח |
השורה האחרונה היא כל הצד היוצא. כל השאר נכנס.
מבנה ה-jtransApi ראוי לתשומת לב מיוחדת: הוא לא מקבל תנועה בודדת אלא עובד במנות, עם שלב זמני, שלב בדיקה ושלב קליטה. זה בדיוק הדפוס שמונע חצי-מנה קלוטה - ומי שמדלג על שלב הבדיקה מגלה את השגיאות אחרי שהן כבר בספרים. אותו רעיון של "בדיקה לפני קליטה" מופיע גם בשגיאות ייבוא והתאמות בחשבשבת.
למה אי אפשר פשוט לשלוח שאילתה ולקבל נתונים?
כי ExportDataApi לא מקבל שאילתה. הוא מקבל דוח. התהליך שהתיעוד מגדיר הוא:
- פותחים את מחולל הדוחות בתוך WizCloud ומתכננים דוח שמחזיר בדיוק את השדות שרוצים לייצא.
- מוסיפים לדוח פרמטרים אם צריך סינון שמשתנה בין הרצות.
- בוחרים באפשרות External. נוצר קובץ טקסט שיורד למחשב.
- מעתיקים מתוך הקובץ את datafile ואת מערך parameters אל גוף הבקשה.
- שולחים POST ל-ExportDataApi/exportData עם הטוקן, ומקבלים את הנתונים כ-JSON.
המשמעות המעשית: כל דוח חדש מחייב עבודה בממשק, לא רק בקוד. אם המערכת שלכם צריכה שלושה חתכים שונים, אלה שלושה דוחות ושלושה קבצי External. אין דרך לבנות סינון חדש רק מצד הלקוח.
התיעוד מציין גם שהוספת target=pdf לבקשה מחזירה את הדוח כ-PDF במקום בפורמט ברירת המחדל. זה שימושי לצירוף למייל, ולא לעיבוד.
מה יש בקובץ ה-External, שדה אחרי שדה
| שדה | מה הוא | האם משנים אותו בזמן ריצה |
|---|---|---|
| datafile | מחרוזת מוצפנת ארוכה שמתארת את מבנה הדוח | לא. מעתיקים כמו שהוא |
| p_name | שם הפרמטר כפי שהדוח מכיר אותו | לא |
| id | מזהה הפרמטר | לא |
| type | טיפוס הערך, למשל long או txt | רק אם שינו את הדוח |
| name | תווית הפרמטר בעברית, למשל קוד מיון | לא |
| defVal | הערך שבו הדוח ירוץ | כן. זה השדה היחיד שמשתנה בפועל |
| opName, opOrigin | האופרטור והכיוון שלו, למשל שווה או from | רק לפי הצורך |
הכלל שחוסך את רוב הבאגים: השדה היחיד שמשנים בין הרצה להרצה הוא defVal. כל שינוי אחר במערך הפרמטרים מנתק אותו מהדוח שנשמר בצד השרת.
התשובה חוזרת עם statusCode, שדה status שערכו repdata, שדה report שמכיל את הנתונים, ושדה errors. ערכי השגיאה שהתיעוד מפרט הם OK, Params not found or not match, Data not found ו-No Permission. שלושתם האחרונים אומרים דברים שונים לגמרי: הראשון הוא באג בבקשה שלכם, השני הוא דוח תקין בלי תוצאות, והשלישי הוא הרשאה חסרה למשתמש שמאחורי הטוקן.
מה נשבר בפועל בייצוא מתוזמן
- הדוח נערך בממשק. מישהו שינה עמודה או פרמטר בדוח, וה-datafile הישן שבקוד כבר לא מתאים. השגיאה שתקבלו היא Params not found or not match, ולא הודעה על שינוי בדוח.
- בלבול בין "אין נתונים" ל"נכשל". תהליך שמתייחס ל-Data not found ככישלון יתריע כל לילה שבו באמת לא היו תנועות.
- טוקן שפג באמצע ריצה ארוכה. ריצה שמתחילה ב-23:50 עם טוקן בן 23 שעות ו-58 דקות תיפול באמצע.
- הרשאות המשתמש שמאחורי המפתח. No Permission הוא לא באג בקוד, אלא הרשאה חסרה בחשבון עצמו.
- מספרים כטקסט. מספרי חשבון וקודי מיון עם אפסים מובילים מאבדים ספרה ברגע שהם עוברים דרך גיליון אלקטרוני בדרך ליעד.
- קוד בסיס נתונים לא נכון. אותו מפתח יכול לגשת לכמה חברות, ודוח שרץ על החברה הלא נכונה נראה תקין לחלוטין.
מה כדאי שיהיה מוכן לפני שמתחילים לפתח
- גישה להגדרות החשבון כדי לשלוף את שלושת ערכי ההזדהות, ומקום מאובטח לשמור אותם בו.
- החלטה מי בצד הלקוח אחראי על הדוחות שה-API מריץ, ומה קורה כשהוא עורך אותם.
- רשימה מדויקת של החתכים שהמערכת שלכם צריכה, כי כל חתך הוא דוח נפרד.
- סביבת בדיקה או חברת דמו, כדי לא לקלוט תנועות ניסיון לספרים אמיתיים.
- החלטה איך מזהים רשומה שכבר נשלחה, כדי שהרצה חוזרת לא תיצור מסמך כפול.
קשור: מדריך התממשקות ל-API של חשבשבת, אוטומציה של דוחות עסקיים.
מקורות
שאלות נפוצות
כמה זמן תקף ה-wizAuthToken של WizCloud?
לפי התיעוד הרשמי, הטוקן שמוחזר מקריאת createSession תקף 24 שעות. תהליך שרץ פעם ביום יכול לייצר טוקן חדש בכל הרצה, אבל תהליך תכוף צריך לשמור אותו בין הקריאות ולחדש רק כשהוא פג, ולא בכל בקשה.
אפשר לייצא נתונים מ-WizCloud בלי לתכנן דוח קודם?
לא. ה-endpoint לייצוא, ExportDataApi/exportData, מקבל מחרוזת datafile שנוצרת רק כשמתכננים דוח במחולל הדוחות ובוחרים באפשרות External. אין נתיב לשאילתה חופשית מול בסיס הנתונים, ולכן כל חתך חדש מתחיל בעבודה בממשק.
מה ההבדל בין tmpBatch ל-issueBatch בייבוא תנועות יומן?
אלה שלבים שונים באותו תהליך. tmpBatch מכניס את התנועות לאזור זמני, chkBatch בודק שגיאות, ו-issueBatch קולט אותן לצמיתות. הפרדה זו מאפשרת לעצור מנה שגויה לפני שהיא נכנסת לספרים, במקום לתקן אותה אחרי.
מה המשמעות של השגיאה No Permission בתשובה של exportData?
היא אומרת שהמשתמש שמאחורי המפתח הפרטי אינו מורשה לנתונים שהדוח מבקש. זו לא בעיה בקוד ולא ב-datafile, אלא בהרשאות בתוך החשבון עצמו, ולכן מתקנים אותה בהגדרות המשתמש ולא בבקשה.
להמשך קריאה
שירות רלוונטי
דשבורד ניהולי
מסך אחד עם המספרים המעטים שבאמת משנים החלטה.
על הכותב
יהונתן סעדיה
מפתח פרילנסר לאוטומציה, אתרים ו-MVP
אני יהונתן סעדיה, מפתח בכיר שבונה אוטומציה עסקית, אתרים מותאמים ומוצרי MVP לעסקים קטנים ובינוניים בארה"ב, אירופה וישראל. המדריכים האלה נכתבים מתוך עבודה אמיתית עם לקוחות, לא מתיאוריה.
בוא נעבוד יחדיש לך פרויקט דומה?
ספר לי מה אתה רוצה לבנות או איזה תהליך להפוך לאוטומטי. אני חוזר תוך 24 שעות עסקים עם כמה שאלות ממוקדות, ואז עוברים על זה יחד בשיחת היכרות חינמית של 30 דקות, בלי התחייבות. בסוף יש לך היקף עבודה, לוח זמנים ומחיר קבוע - או תשובה כנה שלא שווה לבנות את זה.