ה-API של EZcount (איזיקאונט)

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

עיקרי הדברים

יש סביבת דמו אמיתית ב-demo.ezcount.co.il עם מפתח API נפרד. פתחו ובדקו מולה - מסמך מס שהופק בטעות בסביבת הייצור הוא בעיה הנהלת-חשבונות, לא באג שמוחקים.

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

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

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

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

נקודת הקצה והאימות

יצירת מסמך נעשית בבקשת POST עם גוף JSON אל /api/createDoc:

ייצור: https://www.ezcount.co.il/api/createDoc
דמו: https://demo.ezcount.co.il/api/createDoc

האימות אינו מבוסס OAuth ואין תהליך התחברות נפרד. שולחים בגוף הבקשה את api_key ואת developer_email בכל קריאה. את המפתח מפיקים בממשק המערכת, ולסביבת הדמו יש מפתח משלה.

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

סביבת הדמו היא לא נחמדות, היא הכרח

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

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

קודי סוגי מסמכים

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

320 - חשבונית מס קבלה, המסמך הנפוץ ביותר בעסקאות שבהן התשלום מתבצע במעמד ההזמנה
333 - חשבונית זיכוי
400 - קבלה
405 - מופיע בדוגמאות שימוש

חשוב: הרשימה המלאה והמדויקת נמצאת בתיעוד ה-API החי של EZcount, והיא עשויה להשתנות. אל תקבעו קוד בקוד המקור בלי לאמת אותו מול התיעוד העדכני, ואל תסיקו קוד מהיגיון - ההבדל בין חשבונית לחשבונית-מס-קבלה הוא הבדל במועד ההכרה בהכנסה.

הבעיה האמיתית: ביטול וניסיון חוזר

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

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

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

מה לשמור אצלכם

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

מזהה המסמך ומספרו הרץ
הקישור למסמך (ל-PDF), כדי שלא תצטרכו לייצר אותו מחדש
חותמת זמן וסוג המסמך
תשובת ה-API המלאה, גם כשהיא הצליחה - היא הראיה היחידה שלכם אם תתעורר מחלוקת

שיקולים לפני שמתחילים

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

ה-EZcount מספקת קוד לדוגמה בכמה שפות, כולל PHP, C#, Java, Python, Node.js ו-Ruby, מה שמקצר משמעותית את החיבור הראשון. אבל הקוד הוא החלק הקל - ההחלטות שלמעלה הן מה שקובע אם האינטגרציה תחזיק מעמד.

שאלות נפוצות

האם ל-EZcount יש API?

כן. ל-EZcount (איזיקאונט) יש API מסמכים בסגנון REST. יצירת מסמך היא בקשת POST בפורמט JSON אל /api/createDoc, עם אימות באמצעות api_key ו-developer_email בגוף הבקשה. מפורסמות ערכות קוד לדוגמה ל-PHP, C#, Java, Python, Node.js, Ruby ואחרות.

האם יש סביבת בדיקות לאינטגרציה עם EZcount?

כן - סביבת דמו ב-demo.ezcount.co.il עם מפתח API משלה, באותו נתיב נקודת קצה. יש להשתמש בה לכל הפיתוח והבדיקות האוטומטיות. מסמך מס שהופק בטעות בסביבת הייצור לא ניתן למחיקה וצריך לבטל אותו במסמך נגדי.

איך מבטלים חשבונית שנוצרה דרך ה-API של EZcount?

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

מה זה סוג מסמך 320 ב-EZcount?

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

איך צריך לשמור את מפתח ה-API של EZcount?

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

ה-API של EZcount (איזיקאונט): הפקת חשבוניות מהמערכת שלך