ל-iCount יש API בגרסה 3 עם אימות מבוסס טוקן, אבל רוב מה שקובע את הפרויקט אינו קריאת ה-HTTP. המלכודת של v3 מול הממשק הישן, למה דוגמאות קוד ותיקות יטעו אותך, וההחלטות שבאמת עולות זמן.
עיקרי הדברים
- ה-API של iCount הוא v3: POST עם JSON לכתובת api.icount.co.il/api/v3.php/ ואחריה מודול ופעולה, עם טוקן API בכותרת Bearer. קוד מהרשת שקורא לכתובת אחרת נכתב לממשק הישן.
- בכל doc/create שולחים sanity_string. iCount דוחה מסמך שני עם אותו ערך, וכך ניסיון חוזר הופך לשגיאה במקום למסמך מס כפול.
- טוקן ה-API הוא הרשאה מלאה - הוא מאפשר הפקת מסמכי מס בשם העסק. סודות בצד השרת בלבד, ולעולם לא בדפדפן.
- ההחלטות היקרות זהות לכל אינטגרציית חשבוניות אחרת: סוג המסמך, טיפול במע"מ, בטיחות ניסיון חוזר, ומי מפיק את המסמך. אף אחת מהן אינה טכנית.
ה-API של iCount הוא בגרסה 3: כל קריאה היא POST עם גוף JSON לכתובת https://api.icount.co.il/api/v3.php/ ואחריה מודול ופעולה, למשל doc/create, והאימות המומלץ הוא טוקן API בכותרת Authorization: Bearer. דרכו iCount, מערכת ענן לחשבוניות ולניהול עסק, חושפת מסמכים, לקוחות, תשלומים ו-webhooks. המדריך מכסה את הקריאות שחשובות ואת ההחלטות שעולות יותר מהקוד.
איך מתחברים ל-API של iCount?
התיעוד של iCount עצמה, בכתובת apiv3.icount.co.il, מפרט שלוש שיטות אימות וממליץ על הראשונה לכל אינטגרציה:
| שיטה | איך היא עובדת | תוקף | מתי משתמשים בה |
|---|---|---|---|
| טוקן API (מומלץ) | נוצר בעמוד הגדרות טוקני ה-API ונשלח כ-Authorization: Bearer <token> | ללא - תקף עד שמבטלים אותו | חיבור בין שרתים, משימות רקע, webhooks |
מזהה סשן (sid) | קריאה אחת ל-auth/login עם cid, user ו-pass; ה-sid שחוזר נשלח בגוף הבקשות הבאות | 20 דקות מהבקשה האחרונה | כלים אינטראקטיביים שמבצעים הרבה קריאות בזמן קצר |
| פרטי גישה בכל בקשה | cid, user ו-pass בגוף כל בקשה | לא רלוונטי | סקריפטים מהירים ובדיקות |
שני פרטים מאותו עמוד קובעים את התכנון. טוקן יורש בדיוק את ההרשאות של המשתמש שתחתיו נוצר, ולכן הדרך הנקייה להגביל אינטגרציה היא משתמש ייעודי ב-iCount עם הרשאות מצומצמות וטוקן שנוצר תחתיו. ומשימת רקע שבנויה על sid תתחיל להיכשל אחרי 20 דקות בלי פעילות אם היא לא מתחברת מחדש - עוד סיבה לעבוד עם טוקן.
מלכודת הקוד הישן
חיפוש "iCount API" עדיין מחזיר קוד שנכתב לדור ישן של הממשק, חלקו בן למעלה מעשור. הוא נראה סביר, הוא רץ, והוא נכשל. מכיוון ש-v3 עצמו עדיין מקבל מזהה חברה, שם משתמש וסיסמה, סיסמה בגוף הבקשה כבר לא מעידה לאיזה דור שייכת הדוגמה. הכתובת כן: דוגמה שלא קוראת ל-api.icount.co.il/api/v3.php/ לא נכתבה ל-v3. הרכיב הקהילתי של iCount ל-n8n, למשל, מבקש טוקן API, וזה סימן טוב שהוא מכוון לממשק הנוכחי.
רשימת הפעולות המלאה זמינה לעיון ב-apiv3.icount.co.il, מחולקת למודולים כמו doc, client, webhook, paypage ו-reports. את מבנה הבקשה המדויק לוקחים משם, מול הגרסה שרצה עכשיו, ואת ההחלטות שבהמשך מכינים מראש, כי הן העלות האמיתית.
doc/create: השדות שחשובים
יצירת מסמך היא קריאת POST ל-doc/create. השדה היחיד שמסומן כחובה הוא doctype, מחרוזת. התיעוד מונה את invoice, receipt, invrec (חשבונית מס קבלה), refund, deal, offer, order, trec ו-delcert, ומציין שהרשימה משתנה לפי סוג העסק, ולכן את הרשימה שלך קוראים מ-doc/types.
| שדה | תפקיד |
|---|---|
client_id, custom_client_id, vat_id, email, client_name | עבור מי המסמך. iCount מחפשת את הלקוח בדיוק בסדר הזה, ויוצרת לקוח חדש אם אף אחד לא מתאים |
items | שורות המסמך; אופציונליות רק בקבלה, בקבלה על תרומה ובזיכוי |
cash, cheques, banktransfer, cc, payments | פירוט התשלום; קבלה או חשבונית מס קבלה צריכות לפחות אמצעי אחד |
sanity_string | מחרוזת ייחודית של עד 30 תווים; מסמך שני עם אותו ערך נדחה |
send_email | האם iCount שולחת את המקור ללקוח במייל (ברירת מחדל false) |
קריאה מוצלחת מחזירה docnum, doc_url, doc_copy_url, וכשזה רלוונטי גם invoice_reference_number - המספר שמנפיקה רשות המסים. כדאי לשמור את כולם. כישלון חוזר כ-JSON עם "status": false ו-reason קריא למכונה, כמו auth_required, bad_doctype או client_not_found; הקוד מסתעף לפי reason, ואת error_description מציגים לאדם.
כלל הלקוח מצדיק אזהרה נפרדת. אם המערכת שלך שולחת vat_id עם שגיאת הקלדה ובלי client_id, החיפוש לא מוצא כלום ו-iCount פותחת לקוח שני לאותו עסק. בכל קריאה כדאי לשלוח את ה-client_id של iCount ששמרת, או את המזהה שלך בשדה custom_client_id.
ההחלטות שבאמת עולות זמן
אחרי שהקריאה הראשונה עובדת, ההבדלים בין מערכות החשבוניות כמעט נעלמים. מה שנשאר הוא זהה בכולן - וזה מה שמפיל פרויקטים.
1. איזה מסמך, ומתי
חשבונית מס, חשבונית מס קבלה, קבלה וחשבונית זיכוי אינם ניתנים להחלפה. הבחירה קובעת מתי מוכרת ההכנסה, וזו שאלה חשבונאית ולא טכנית.
זו החלטה של רואה החשבון של העסק. אם המערכת שלך מחליטה לבד איזה מסמך להפיק ובאיזה רגע בתהליך, ההחלטה הזו צריכה לעבור אישור בכתב. מפתח שבוחר סוג מסמך לפי היגיון הוא סיכון.
2. בעיית הניסיון החוזר
זו הבעיה שתופסת כמעט כל אינטגרציית חשבוניות ראשונה, בכל מערכת.
שולחים בקשה, השרת מפיק את המסמך, והחיבור נופל לפני שהתשובה חוזרת. הקוד רואה timeout, מפרש ככישלון, ומנסה שוב - וכעת יש שני מסמכי מס עם שני מספרים רצים. מסמך מס אינו ניתן למחיקה; ביטול נעשה במסמך נגדי, ומישהו צריך לטפל בזה ידנית.
שלוש הנחיות:
- timeout אינו כישלון - הוא חוסר ידיעה. אל תנסה שוב אוטומטית.
- שמור מזהה ייחודי משלך על ההזמנה, ולפני כל ניסיון חוזר בדוק אם כבר קיים מסמך שמתאים לו.
- מסמך חסר עדיף על מסמך כפול. הראשון מתוקן בדקה; השני דורש ביטול, תיעוד ושיחה עם הנהלת החשבונות.
ב-iCount ההגנה מפני זה היא sanity_string. שמים בו את מזהה ההזמנה שלך (עד 30 תווים), ו-doc/create חוזר על אותה הזמנה נדחה עם doc_exists_based_on_sanity_string במקום להפיק מסמך מס שני. את השגיאה הזו מפרשים כ"כבר הופק", מאתרים את המסמך הקיים עם doc/search, וממשיכים.
3. מע"מ ועוסק פטור
האם הסכומים שאתה שולח כוללים מע"מ או לא - לאמת מול מסמך אמיתי, לא להניח. זו בדיקה של חמש דקות שמונעת תיקון של חודש.
ועוסק פטור אינו מפיק חשבונית מס כלל. אם המערכת שלך משרתת יותר מסוג עוסק אחד, זה משנה את סוג המסמך שהיא מפיקה.
4. מי מפיק את המסמך
אם יש בתמונה גם סולק שמוגדר להפיק מסמך אוטומטית בעקבות תשלום, והמערכת שלך גם מפיקה - נוצרים שני מסמכי מס על עסקה אחת. זו טעות התכנון הנפוצה ביותר כשסליקה והנהלת חשבונות נוגעות באותו פרויקט, והיא מתגלה בסוף החודש. יש לבחור צד אחד ולתעד אותו לפני שכותבים שורה.
5. מספר הקצאה
דרישת רשות המסים חלה בלי קשר למערכת שבחרת. יש לוודא שהתהליך מטפל בה לפני העלייה לאוויר - ראה מספר הקצאה למפתחים.
האם iCount תומכת ב-webhooks?
כן, והם מנוהלים דרך ה-API עצמו. webhook/add מקבלת action, url ו-method אופציונלי - GET, POST, JSON או XML, כשברירת המחדל היא JSON - ומחזירה webhook_id. את רשימת הפעולות שאפשר להירשם אליהן מחזירה webhook/valid_actions, ו-webhook/get_list מראה מה כבר רשום. כדאי לוודא שהאירוע שאתה צריך נמצא ברשימה לפני שבונים סביבו.
כשאין דחיפה לאירוע מסוים, משיכה עושה את העבודה: doc/search מסננת לפי start_date ו-end_date, doctype ו-status, ו-client/get_open_docs ו-client/get_balance עונות על השאלה ש-CRM שואל הכי הרבה - כמה הלקוח הזה עוד חייב.
אבטחה
טוקן ה-API של iCount מאפשר הפקת מסמכי מס בשם העסק. הוא לא פג בפרק זמן קבוע. לכן:
- משתני סביבה או מנהל סודות בלבד
- נוצר תחת משתמש ייעודי עם ההרשאות שהאינטגרציה צריכה בלבד, כי הטוקן יורש את ההרשאות של המשתמש
- לא בקוד המקור, לא בלוגים, ולא בשום קוד שרץ בדפדפן
- אם טוקן דלף - להחליף אותו בממשק, לא "לעקוב ולראות"
ולשמור את תשובת ה-API המלאה גם בהצלחה: מזהה המסמך, מספרו הרץ והקישור אליו. זו הראיה היחידה שלך כשמגיעה שאלה מהנהלת החשבונות בעוד חצי שנה.
סביבת בדיקות
מסמך מס שהופק בטעות אינו רשומה שמוחקים - הוא קיים לצורכי מס. לכן לברר מפורשות מול התמיכה של iCount האם יש סביבת בדיקות ואיך מקבלים אליה גישה. זו שאלה לגיטימית לחלוטין, וכדאי לשאול אותה לפני שמתחייבים ללקוח על לוח זמנים - לא אחרי.
בכל מקרה: להחזיק את כתובת הבסיס ואת הטוקן כשני משתני סביבה נפרדים, כדי שמעבר בין סביבות יהיה שינוי תצורה ולא שינוי קוד.
צ'קליסט
- לפתוח את התיעוד הרשמי הנוכחי ולעבוד מולו - לא מדוגמה שמצאת.
- לוודא שאתה על v3, לפי הכתובת:
api.icount.co.il/api/v3.php/. - לברר סביבת בדיקות לפני שמתחילים.
- לקבל מרואה החשבון בכתב אילו מסמכים מופקים ובאיזה רגע.
- לאמת מע"מ מול מסמך אמיתי.
- לבנות הגנה מפני כפילות לפני שמפיקים מסמך ראשון בייצור, עם
sanity_stringבכלdoc/create.
להשוואה בין המערכות הישראליות, ראה השוואת ה-API של מערכות החשבוניות בישראל; לחיבור iCount למערכת מכירות, ראה חיבור תוכנת חשבוניות ל-CRM.
מקורות
שאלות נפוצות
האם ל-iCount יש API?
כן. ל-iCount יש API בגרסה 3 בכתובת https://api.icount.co.il/api/v3.php/, שבו כל קריאה היא POST עם גוף JSON למודול ולפעולה, למשל doc/create. האימות המומלץ הוא טוקן API בכותרת Authorization: Bearer, ורשימת הפעולות המלאה מפורסמת ב-apiv3.icount.co.il.
למה קוד דוגמה ותיק של iCount מפסיק לעבוד?
כי הוא נכתב לדור ישן של הממשק שקורא לכתובת אחרת. הממשק הנוכחי הוא v3 בכתובת api.icount.co.il/api/v3.php/, וטוקן API הוא שיטת האימות המומלצת. גם v3 עדיין מקבל מזהה חברה, שם משתמש וסיסמה, ולכן כדי לזהות לאיזה דור שייכת דוגמה בודקים את הכתובת, לא את הסיסמה.
מהו הבאג הנפוץ ביותר באינטגרציה מול API של חשבוניות?
ניסיון חוזר אחרי timeout. בקשה שקיבלה timeout ייתכן מאוד שהצליחה בשרת, ולכן ניסיון חוזר אוטומטי מפיק שני מסמכי מס עם שני מספרים רצים - ומסמך מס לא ניתן למחיקה, רק לקיזוז במסמך נגדי. יש לשמור מזהה ייחודי על ההזמנה ולבדוק אם כבר קיים מסמך לפני כל ניסיון חוזר.
מי מחליט איזה סוג מסמך המערכת מפיקה?
רואה החשבון של העסק, לא המפתח. הבחירה בין חשבונית מס, חשבונית מס קבלה וקבלה קובעת מתי מוכרת ההכנסה, וזו החלטה חשבונאית עם השלכות אמיתיות. יש לקבל אותה בכתב לפני שבונים לוגיקה שבוחרת סוג מסמך אוטומטית.
איך צריך לשמור טוקן API של iCount?
כסוד בצד השרת במשתנה סביבה או במנהל סודות. הוא מאפשר הפקת מסמכי מס בשם העסק ואינו פג בפרק זמן קבוע, ולכן אסור שיופיע בקוד המקור, בלוגים או בכל דבר שרץ בדפדפן. אם הוא דולף, יש להחליף אותו בממשק מיד ולא לעקוב אחרי שימוש לרעה.
האם טוקן ה-API של iCount פג?
לא. לפי התיעוד של iCount, לטוקן API אין תוקף והוא עובד עד שמבטלים אותו, והוא נושא בדיוק את ההרשאות של המשתמש שתחתיו נוצר. מזהה סשן מ-auth/login שונה: הוא תקף 20 דקות מהבקשה האחרונה, ואחר כך צריך להתחבר מחדש.
איך מונעים מה-API של iCount להפיק מסמך כפול?
שולחים sanity_string עם doc/create - ערך ייחודי של עד 30 תווים, למשל מזהה ההזמנה שלך. אם כבר קיים מסמך עם אותו ערך, iCount דוחה את הבקשה עם doc_exists_based_on_sanity_string, וכך ניסיון חוזר אחרי timeout לא יכול להפיק מסמך מס שני.
למה ה-API של iCount יוצר לקוחות כפולים?
כי doc/create מחפשת את הלקוח לפי client_id, ואחריו custom_client_id, vat_id, email ו-client_name, ויוצרת לקוח חדש כשאין התאמה. מספר עוסק עם שגיאת הקלדה או מייל שהשתנה מספיקים כדי לפתוח רשומה שנייה. כדאי לשמור את ה-client_id של iCount, או לשלוח את המזהה שלך ב-custom_client_id, בכל קריאה.
להמשך קריאה
שירות רלוונטי
אינטגרציה בין מערכות
לגרום למערכות שאתם כבר משלמים עליהן לדבר זו עם זו.
יש לך פרויקט דומה?
ספר לי מה אתה רוצה לבנות או איזה תהליך להפוך לאוטומטי. אני חוזר תוך 24 שעות עסקים עם כמה שאלות ממוקדות, ואז עוברים על זה יחד בשיחת היכרות חינמית של 30 דקות, בלי התחייבות. בסוף יש לך היקף עבודה, לוח זמנים ומחיר קבוע - או תשובה כנה שלא שווה לבנות את זה.