מדריך למפתחים לחיבור אתר, חנות או CRM ליש חשבונית: הנתיב createDocument, כותרת Authorization עם secret ו-userkey, קודי DocumentType ו-statusID, DocumentUniqueKey נגד כפילויות, מספרי הקצאה, ולמה קריאה שנכשלה עדיין מחזירה סטטוס 200.
עיקרי הדברים
- מסמכים מופקים ב-POST לכתובת https://api.yeshinvoice.co.il/api/v1.1/createDocument עם גוף JSON.
- האימות הוא כותרת Authorization שמכילה אובייקט JSON עם secret ו-userkey, ולא טוקן Bearer.
- קריאה שנכשלה מחזירה HTTP 200 עם Success: false ו-ErrorMessage בעברית, ולכן בודקים את Success ולא את קוד הסטטוס.
- DocumentType 1 הוא הצעת מחיר, 8 חשבונית מס ו-9 חשבונית מס/קבלה - מספור שונה משל ממשקי חשבוניות ישראליים אחרים.
ה-API של יש חשבונית מאפשר לאתר, לחנות מקוונת או ל-CRM להפיק ביש חשבונית הצעות מחיר, חשבוניות מס, קבלות וחשבוניות מס/קבלה בלי שמישהו ייכנס לממשק. זה REST API ב-JSON: שולחים POST לכתובת https://api.yeshinvoice.co.il/api/v1.1/createDocument עם כותרת Authorization שמכילה את המפתח הסודי ואת מפתח המשתמש, והתשובה מחזירה את מספר המסמך וקישורים ל-PDF.
יש חשבונית היא מערכת חשבוניות ישראלית. תיעוד המפתחים שלה בכתובת user.yeshinvoice.co.il/api/doc מוצג רק בדפדפן, ולכן המדריך נבנה מהעמוד הזה כפי שהוצג ב-30 בספטמבר 2026 (גרסת API v1.1, עדכון הנתיבים האחרון רשום 08/03/2026), ונבדק מול תשובות חיות של ה-API.
איך עובד ה-API של יש חשבונית?
כל קריאה היא POST עם גוף JSON לנתיב שמתחת לכתובת הבסיס. האימות אינו טוקן Bearer: כותרת Authorization מכילה אובייקט JSON קטן עם שני שדות, secret ו-userkey.
| מה | ערך |
|---|---|
| כתובת בסיס (v1.1) | https://api.yeshinvoice.co.il/api/v1.1/ |
| בסיס ישן (v1) | https://api.yeshinvoice.co.il/api/v1/, עדיין הנתיב המתועד של חלק מהפעולות, למשל shareDocument |
| Sandbox | אותה כתובת v1.1, עם המפתחות של חשבון Sandbox נפרד |
| כותרות | Content-Type: application/json ו-Authorization: {"secret":"...","userkey":"..."} |
| תשובה | {"Success": ..., "ErrorMessage": ..., "ReturnValue": ...} |
חשבון Sandbox נפתח מעמוד התיעוד, ולפי התיעוד הוא לא דורש מספר זהות או רישום חברה; הוא מיועד לפיתוח ולבדיקות בלבד. מעבר למסמכים, אותו API מכסה לקוחות, מוצרים, הוצאות, קישורי תשלום, טוקנים של כרטיסי אשראי, דוחות וניהול לידים. גם ב-Make.com יש אפליקציה של יש חשבונית, עם מודולים כמו "Creates an Invoice", "Add a Customer" ו-"Make an API Call", למי שמעדיף תרחיש בלי קוד.
למה קריאה שנכשלה ביש חשבונית מחזירה 200?
יש חשבונית מדווחת על שגיאות בתוך גוף התשובה, לא בסטטוס ה-HTTP. קריאה ל-createDocument בלי מפתחות מחזירה סטטוס 200 עם הגוף הזה:
{"Success":false,"ErrorMessage":"חסר מפתח SECRET KEY","ReturnValue":null}כשהמפתח קיים אבל שגוי, הסטטוס עדיין 200 וההודעה משתנה ל-מפתח SECRET KEY לא חוקי. טקסט השגיאה בעברית, אז שומרים ומתעדים אותו ב-UTF-8. חיבור שבודק רק את response.ok רושם כל כישלון כהצלחה, ומסמן הזמנה כ"הופקה חשבונית" כשאין שום חשבונית. הכלל: קוראים את Success, כל ערך שאינו true הוא כישלון, ואת ErrorMessage שומרים למי שמטפל בחריגה.
הפקת מסמך מהזמנה, שלב אחר שלב
- פותחים חשבון Sandbox ומפתחים מולו; עוברים למפתחות הייצור רק אחרי שסבב מלא עובד.
- ממלאים את כותרת המסמך.
DocumentType,statusID,CurrencyIDו-LangID(359 עברית, 139 אנגלית) הם שדות חובה, וגםDateCreatedו-MaxDateבתבניתyyyy-MM-dd HH:mm. - ממלאים את אובייקט
Customer. רקNameהוא חובה;NameInvoice,NumberID(ת"ז או ח"פ),EmailAddress,Phone,Cityו-CountryCodeהם רשות. את מזהה הלקוח שלכם שמים ב-CustomKey, ואתIDמעבירים כשמזהה הלקוח ביש חשבונית כבר ידוע לכם (בדוגמה בתיעוד נשלח -1). - מוסיפים את מערך
items:Quantityהוא חובה, ואחריוPrice,Name,Skuו-vatType, שברירת המחדל שלו היא 4. - לקבלה או לחשבונית מס/קבלה מוסיפים
payments. השדותPrice,TypeID(קוד אמצעי התשלום) ו-DueDateהם חובה; פרטי כרטיס ובנק נכנסים לשדות כמוCardLastDigits,BankNumberו-Reference. - מגדירים את
DocumentUniqueKeyלמספר ההזמנה ושולחים את הגוף ב-POST ל-createDocument. - בודקים את
Success. בהצלחה, שומרים על ההזמנה אתReturnValue.id, אתReturnValue.docNumberואתpdfurl.
המסמך מגיע ללקוח או כבר בזמן ההפקה, עם SendEmail (ועם IncludePDF כדי לצרף את הקובץ) או SendSMS, או מאוחר יותר דרך shareDocument, שמקבלת את id של המסמך. מלבד pdfurl (מקור), ReturnValue כולל את copypdfurl (העתק), loyalpdfurl (נאמן למקור), pdf80mm (מסמך 80 מ"מ לקופה), קישור שיתוף מקוצר ב-url וקישור לתשלום באשראי ב-paymenturl.
באילו קודי DocumentType ו-statusID משתמשת יש חשבונית?
DocumentType הוא מספר, והתיעוד מפרט את הערכים האלה:
| קוד | מסמך |
|---|---|
| 1 | הצעת מחיר |
| 2 | הזמנה |
| 3 | תעודת משלוח |
| 5 | חשבון עסקה |
| 6 | קבלה |
| 7 | הזמנת רכש |
| 8 | חשבונית מס |
| 9 | חשבונית מס/קבלה |
| 10 | חשבונית זיכוי |
| 11 | קבלה לתרומה |
אין קוד 4, והמספור לא תואם מערכות ישראליות אחרות: ב-API של Invoice4U חשבונית מס היא 1, ואילו ביש חשבונית 1 הוא הצעת מחיר. מיפוי שהועתק מחיבור אחר יפיק את המסמך הלא נכון. ל-statusID יש רשימה משלו: 1 פתוח, 2 סגור, 3 בוטל, 4 מבטל, 5 מסמך חיצוני.
מה משתבש בחיבור ליש חשבונית
- מסמכים כפולים. פסק זמן ב-
createDocumentלא אומר ששום דבר לא הופק. כש-DocumentUniqueKeyמוגדר, המערכת מסרבת להפיק מסמך שני עם אותו ערך ומחזירה שגיאה. השדה מוגבל ל-20 תווים, כך ש-UUID באורך 36 תווים צריך להתקצר למשהו שעדיין ייחודי. - שתי צורות תאריך. רשימת השדות מגדירה את
DateCreatedכ-yyyy-MM-dd HH:mm, ואילו גוף הדוגמה שולחyyyy-MM-dd. השתמשו בצורה המתועדת ואמתו אותה ב-Sandbox. - העתקת המע"מ מהדוגמה. ברירת המחדל של
vatPercentageהיא השיעור שקובע החוק בישראל, אבל גוף הדוגמה מקבע ערך. אל תשלחו את השדה אלא אם באמת צריך לעקוף את ברירת המחדל. - גרסאות API מעורבות.
createDocument,cancelDocumentו-approvalIsraelTaxמתועדות תחת v1.1, ו-shareDocumentתחת v1. שמרו את הנתיב המלא לכל פעולה במקום בסיס משותף אחד. - ביטול מסמך.
cancelDocumentמקבלת אתidשל המסמך, ולפי התיעוד עובדת רק על קבלה, קבלה לתרומה, חשבונית מס וחשבונית מס/קבלה. הצעות מחיר והזמנות עוברות דרך פעולת Update Document Status הנפרדת. - מספרי הקצאה.
DontCreateIsraelTaxNumberמונע מהמערכת לבקש מספר הקצאה,DoNotSendEmailWithoutIsraelTaxעוצר את המייל כשלמסמך אין מספר כזה, ו-approvalIsraelTaxעםdocidמבקשת מספר למסמך קיים. מתי נדרש מספר הקצאה נקבע על ידי רשות המסים, לא על ידי ה-API - ראו ה-API של מספרי הקצאה. - המפתחות בלוגים. שני המפתחות נוסעים בכותרת
Authorization, כך שלוג דיבאג של כותרות הבקשה חושף אותם.
אותו דפוס מול מערכת אחרת מופיע באוטומציה של מורנינג (חשבונית ירוקה) דרך ה-API, והשאלה הרחבה יותר של איזו מערכת מדברת עם איזו מופיעה בחיבור תוכנת חשבוניות ל-CRM.
מה להכין לפני שמתחילים
- חשבון Sandbox, ואת המפתח הסודי ומפתח המשתמש של הייצור מבעל החשבון.
- החלטה איזה מסמך כל מכירה מפיקה - חשבונית מס/קבלה בזמן התשלום, או חשבונית מס קודם וקבלה אחר כך.
- כרטיסי לקוח עם ת"ז או ח"פ, כשהעסק צריך אותם.
- מפתח הזמנה ייחודי של 20 תווים לכל היותר, ומקום לשמור מול כל הזמנה את
id, אתdocNumberואת קישור ה-PDF מיש חשבונית.
מקורות
שאלות נפוצות
האם ליש חשבונית יש API?
כן. יש חשבונית מפרסמת REST API ב-JSON, כרגע בגרסה v1.1, בכתובת api.yeshinvoice.co.il/api/v1.1/. הוא מכסה מסמכים, לקוחות, מוצרים, הוצאות, קישורי תשלום, טוקנים של כרטיסי אשראי, דוחות וניהול לידים. מסמכים מופקים ב-POST ל-createDocument, ויש חשבון Sandbox נפרד לבדיקות בלי עסק רשום.
איך מתבצע האימות מול ה-API של יש חשבונית?
שולחים כותרת Authorization שהערך שלה הוא אובייקט JSON עם שני שדות, secret ו-userkey, לצד Content-Type: application/json. זה לא טוקן Bearer. מפתח חסר מחזיר HTTP 200 עם Success false וההודעה "חסר מפתח SECRET KEY", כך שמפתח שגוי אף פעם לא מופיע כשגיאת 401.
איך מונעים מיש חשבונית להפיק את אותה חשבונית פעמיים?
מגדירים בכל קריאה ל-createDocument את DocumentUniqueKey לערך שקשור להזמנה, למשל מספר ההזמנה. כך המערכת מסרבת להפיק מסמך שני עם אותו ערך ומחזירה שגיאה במקום מספר חדש. השדה מוגבל ל-20 תווים, ולכן מקצרים מזהים ארוכים או UUID בצורה קבועה וצפויה.
איזה מספר DocumentType הוא חשבונית מס/קבלה ביש חשבונית?
9. חשבונית מס היא 8, קבלה 6, חשבונית זיכוי 10 וקבלה לתרומה 11, ואילו 1 הוא הצעת מחיר, 2 הזמנה, 3 תעודת משלוח, 5 חשבון עסקה ו-7 הזמנת רכש. אין קוד 4, והרשימה שונה מממשקי חשבוניות ישראליים אחרים, ולכן אל תעתיקו מיפוי מחיבור אחר.
אפשר לבדוק את ה-API של יש חשבונית בלי עסק אמיתי?
כן. עמוד התיעוד מציע חשבון Sandbox ייעודי שלפי יש חשבונית לא דורש מספר זהות או רישום חברה. הוא מיועד לפיתוח ולבדיקות בלבד. פונים אליו באותה כתובת בסיס v1.1, עם המפתח הסודי ומפתח המשתמש של חשבון ה-Sandbox, כך שהמעבר לייצור הוא החלפת מפתחות.
להמשך קריאה
שירות רלוונטי
אינטגרציות
לגרום למערכות שאתם כבר משלמים עליהן לדבר זו עם זו.
על הכותב
יהונתן סעדיה
מפתח פרילנסר לאוטומציה, אתרים ו-MVP
אני יהונתן סעדיה, מפתח בכיר שבונה אוטומציה עסקית, אתרים מותאמים ומוצרי MVP לעסקים קטנים ובינוניים בארה"ב, אירופה וישראל. המדריכים האלה נכתבים מתוך עבודה אמיתית עם לקוחות, לא מתיאוריה.
בוא נעבוד יחדיש לך פרויקט דומה?
ספר לי מה אתה רוצה לבנות או איזה תהליך להפוך לאוטומטי. אני חוזר תוך 24 שעות עסקים עם כמה שאלות ממוקדות, ואז עוברים על זה יחד בשיחת היכרות חינמית של 30 דקות, בלי התחייבות. בסוף יש לך היקף עבודה, לוח זמנים ומחיר קבוע - או תשובה כנה שלא שווה לבנות את זה.