ל-iCount יש API בגרסה 3 עם אימות מבוסס טוקן, אבל רוב מה שקובע את הפרויקט אינו קריאת ה-HTTP. המלכודת של v3 מול הממשק הישן, למה דוגמאות קוד ותיקות יטעו אותך, וההחלטות שבאמת עולות זמן.
עיקרי הדברים
- יש שני דורות של ממשק ב-iCount. v3 מתאמת בטוקן API; ספריות ותיקות מעבירות מזהה חברה, שם משתמש וסיסמה. קוד שמוצאים ברשת הוא לעיתים קרובות הישן.
- יש לקרוא את מבנה הבקשה מהתיעוד הרשמי, לא ממאמר. נקודות קצה ושמות שדות בשוק הזה משתנים, ומדריך שמקבע אותם מתיישן רע ולוקח איתו את הפרויקט שלך.
- טוקן ה-API הוא הרשאה מלאה - הוא מאפשר הפקת מסמכי מס בשם העסק. סודות בצד השרת בלבד, ולעולם לא בדפדפן.
- ההחלטות היקרות זהות לכל אינטגרציית חשבוניות אחרת: סוג המסמך, טיפול במע"מ, בטיחות ניסיון חוזר, ומי מפיק את המסמך. אף אחת מהן אינה טכנית.
iCount היא מערכת לניהול עסק וחשבוניות בענן, והיא חושפת API שמאפשר להפיק מסמכים ולנהל לקוחות מתוך מערכת אחרת. המדריך הזה לא מנסה להיות תחליף לתיעוד הרשמי - ובכוונה לא מציג מבנה בקשה מדויק. הסיבה תכף.
למה המדריך הזה לא נותן לך endpoint להעתיק
אני כותב מדריכי אינטגרציה הרבה, ובשוק הישראלי יש דפוס חוזר: נקודות קצה, שמות שדות וקודי סוגי מסמכים משתנים בין גרסאות, וקוד שהועתק ממאמר בן שלוש שנים נכשל באופן שנראה מבלבל.
ב-iCount זה חריף במיוחד כי יש שני דורות של ממשק, והם נראים לגמרי אחרת:
| הדור הישן | v3 | |
|---|---|---|
| אימות | מזהה חברה, שם משתמש וסיסמה שנשלחים בגוף הבקשה | טוקן API בכותרת Authorization |
| איפה תמצא אותו | ספריות קוד פתוח ותיקות, דוגמאות בפורומים | התיעוד הרשמי הנוכחי |
זו המלכודת המרכזית. חיפוש "iCount API" מחזיר לא מעט קוד שנכתב לדור הישן - חלקו בן למעלה מעשור. הוא נראה סביר, הוא רץ, והוא נכשל.
אינדיקציה טובה: אם דוגמה שולחת שם משתמש וסיסמה בגוף הבקשה, היא מהדור הישן. אם היא שולחת טוקן בכותרת, היא מתאימה ל-v3. הרכיב הקהילתי של iCount ל-n8n, למשל, דורש טוקן API במפורש ולא צירוף של מזהה חברה, משתמש וסיסמה - זה סימן טוב לכיוון הנכון.
מאיפה לקחת את מבנה הבקשה
מהתיעוד הרשמי של iCount, שאותו פותחים בדפדפן. שם נמצא מבנה הבקשה המדויק לכל פעולה, כולל שדות חובה וקודי סוגי מסמכים - מול הגרסה שרצה עכשיו.
שווה לדעת שהתיעוד של iCount נבנה בכלים שמריצים JavaScript, ולכן הוא לא תמיד נגיש לכלים אוטומטיים או ל-fetch פשוט. זו לא מגבלה משמעותית - אבל היא אומרת שצריך אדם שפותח את הדף ומעתיק, ולא סקריפט. בפרויקט אמיתי זה חמש דקות.
הכלל שאני עובד לפיו: את מבנה הבקשה לוקחים מהתיעוד. את ההחלטות - שהן העלות האמיתית - מכינים מראש. כל השאר בהמשך המאמר עוסק בחלק השני.
ההחלטות שבאמת עולות זמן
אחרי שהקריאה הראשונה עובדת, ההבדלים בין מערכות החשבוניות כמעט נעלמים. מה שנשאר הוא זהה בכולן - וזה מה שמפיל פרויקטים.
1. איזה מסמך, ומתי
חשבונית מס, חשבונית מס קבלה, קבלה וחשבונית זיכוי אינם ניתנים להחלפה. הבחירה קובעת מתי מוכרת ההכנסה, וזו שאלה חשבונאית ולא טכנית.
זו החלטה של רואה החשבון של העסק. אם המערכת שלך מחליטה לבד איזה מסמך להפיק ובאיזה רגע בתהליך, ההחלטה הזו צריכה לעבור אישור בכתב. מפתח שבוחר סוג מסמך לפי היגיון הוא סיכון.
2. בעיית הניסיון החוזר
זו הבעיה שתופסת כמעט כל אינטגרציית חשבוניות ראשונה, בכל מערכת.
שולחים בקשה, השרת מפיק את המסמך, והחיבור נופל לפני שהתשובה חוזרת. הקוד רואה timeout, מפרש ככישלון, ומנסה שוב - וכעת יש שני מסמכי מס עם שני מספרים רצים. מסמך מס אינו ניתן למחיקה; ביטול נעשה במסמך נגדי, ומישהו צריך לטפל בזה ידנית.
שלוש הנחיות:
- timeout אינו כישלון - הוא חוסר ידיעה. אל תנסה שוב אוטומטית.
- שמור מזהה ייחודי משלך על ההזמנה, ולפני כל ניסיון חוזר בדוק אם כבר קיים מסמך שמתאים לו.
- מסמך חסר עדיף על מסמך כפול. הראשון מתוקן בדקה; השני דורש ביטול, תיעוד ושיחה עם הנהלת החשבונות.
3. מע"מ ועוסק פטור
האם הסכומים שאתה שולח כוללים מע"מ או לא - לאמת מול מסמך אמיתי, לא להניח. זו בדיקה של חמש דקות שמונעת תיקון של חודש.
ועוסק פטור אינו מפיק חשבונית מס כלל. אם המערכת שלך משרתת יותר מסוג עוסק אחד, זה משנה את סוג המסמך שהיא מפיקה.
4. מי מפיק את המסמך
אם יש בתמונה גם סולק שמוגדר להפיק מסמך אוטומטית בעקבות תשלום, והמערכת שלך גם מפיקה - נוצרים שני מסמכי מס על עסקה אחת. זו טעות התכנון הנפוצה ביותר כשסליקה והנהלת חשבונות נוגעות באותו פרויקט, והיא מתגלה בסוף החודש. יש לבחור צד אחד ולתעד אותו לפני שכותבים שורה.
5. מספר הקצאה
דרישת רשות המסים חלה בלי קשר למערכת שבחרת. יש לוודא שהתהליך מטפל בה לפני העלייה לאוויר - ראה מספר הקצאה למפתחים.
אבטחה
טוקן ה-API של iCount מאפשר הפקת מסמכי מס בשם העסק. הוא לא פג בפרק זמן קבוע. לכן:
- משתני סביבה או מנהל סודות בלבד
- לא בקוד המקור, לא בלוגים, ולא בשום קוד שרץ בדפדפן
- אם טוקן דלף - להחליף אותו בממשק, לא "לעקוב ולראות"
ולשמור את תשובת ה-API המלאה גם בהצלחה: מזהה המסמך, מספרו הרץ והקישור אליו. זו הראיה היחידה שלך כשמגיעה שאלה מהנהלת החשבונות בעוד חצי שנה.
סביבת בדיקות
מסמך מס שהופק בטעות אינו רשומה שמוחקים - הוא קיים לצורכי מס. לכן לברר מפורשות מול התמיכה של iCount האם יש סביבת בדיקות ואיך מקבלים אליה גישה. זו שאלה לגיטימית לחלוטין, וכדאי לשאול אותה לפני שמתחייבים ללקוח על לוח זמנים - לא אחרי.
בכל מקרה: להחזיק את כתובת הבסיס ואת הטוקן כשני משתני סביבה נפרדים, כדי שמעבר בין סביבות יהיה שינוי תצורה ולא שינוי קוד.
צ'קליסט
- לפתוח את התיעוד הרשמי הנוכחי ולעבוד מולו - לא מדוגמה שמצאת.
- לוודא שאתה על v3, לפי האימות: טוקן בכותרת ולא סיסמה בגוף.
- לברר סביבת בדיקות לפני שמתחילים.
- לקבל מרואה החשבון בכתב אילו מסמכים מופקים ובאיזה רגע.
- לאמת מע"מ מול מסמך אמיתי.
- לבנות הגנה מפני כפילות לפני שמפיקים מסמך ראשון בייצור.
להשוואה בין המערכות הישראליות, ראה השוואת ה-API של מערכות החשבוניות בישראל.
שאלות נפוצות
האם ל-iCount יש API?
כן. ל-iCount יש API בגרסה 3 שמתאמת באמצעות טוקן API שנשלח בכותרת Authorization, והוא מכסה הפקת מסמכים וניהול לקוחות. את מבנה הבקשה המדויק לכל פעולה יש לקחת מהתיעוד הרשמי של iCount ולא ממאמר, כי נקודות קצה ושמות שדות משתנים בין גרסאות.
למה קוד דוגמה ותיק של iCount מפסיק לעבוד?
כי הוא נכתב לדור הישן של הממשק, ששולח מזהה חברה, שם משתמש וסיסמה בגוף הבקשה. הממשק הנוכחי v3 משתמש בטוקן API בכותרת במקום. דרך מהירה לזהות לאיזה דור שייכת דוגמה: אם היא שמה סיסמה בגוף הבקשה, זה הישן.
מהו הבאג הנפוץ ביותר באינטגרציה מול API של חשבוניות?
ניסיון חוזר אחרי timeout. בקשה שקיבלה timeout ייתכן מאוד שהצליחה בשרת, ולכן ניסיון חוזר אוטומטי מפיק שני מסמכי מס עם שני מספרים רצים - ומסמך מס לא ניתן למחיקה, רק לקיזוז במסמך נגדי. יש לשמור מזהה ייחודי על ההזמנה ולבדוק אם כבר קיים מסמך לפני כל ניסיון חוזר.
מי מחליט איזה סוג מסמך המערכת מפיקה?
רואה החשבון של העסק, לא המפתח. הבחירה בין חשבונית מס, חשבונית מס קבלה וקבלה קובעת מתי מוכרת ההכנסה, וזו החלטה חשבונאית עם השלכות אמיתיות. יש לקבל אותה בכתב לפני שבונים לוגיקה שבוחרת סוג מסמך אוטומטית.
איך צריך לשמור טוקן API של iCount?
כסוד בצד השרת במשתנה סביבה או במנהל סודות. הוא מאפשר הפקת מסמכי מס בשם העסק ואינו פג בפרק זמן קבוע, ולכן אסור שיופיע בקוד המקור, בלוגים או בכל דבר שרץ בדפדפן. אם הוא דולף, יש להחליף אותו בממשק מיד ולא לעקוב אחרי שימוש לרעה.
להמשך קריאה
שירות רלוונטי
אינטגרציות
לגרום למערכות שאתם כבר משלמים עליהן לדבר זו עם זו.
על הכותב
יהונתן סעדיה
מהנדס פרילנסר לאוטומציה, אתרים ו-MVP
אני יהונתן סעדיה, מהנדס בכיר שבונה אוטומציה עסקית, אתרים מותאמים ומוצרי MVP לעסקים קטנים ובינוניים בארה"ב, אירופה וישראל. המדריכים האלה נכתבים מתוך עבודה אמיתית עם לקוחות, לא מתיאוריה.
בוא נעבוד יחדיש לך פרויקט דומה?
ספר לי מה אתה מנסה להפוך לאוטומטי או לבנות, ואומר לך מהי הדרך המהירה והאמינה ביותר ליישם את זה.