מרכז התיעוד
כל מה שצריך: מהחשבונית הראשונה, דרך בוט הטלגרם, ועד אינטגרציה מלאה ב-API. בעברית, בגובה העיניים. עודכן ביולי 2026.
מבוא
פלטפורמת SmartInvoice מאחדת שלושה מודולים: SmartInvoice להנפקת חשבוניות תואמות חוק, ו‑SmartExpense לניהול הוצאות ותזרים. שניהם חולקים מאגר נתונים אחד ומסונכרנים בזמן אמת.
המודול בנוי סביב מודל "חשבוניות ישראל" (תיקון 63 לחוק מע״מ): חשבונית מס מעל הסף מונפקת עם מספר הקצאה מרשות המסים. החיבור האוטומטי לרשות המסים, שיביא את המספר, עדיין בפיתוח ואינו פעיל; עד שייפתח, מזינים את המספר שהתקבל מרשות המסים.
לפני שמתחילים
חיבור לרשות המסים נדרש רק להנפקת חשבוניות מס מעל הסף. עוסק פטור המנפיק קבלות בלבד, פטור מהקצאה.
חיבור לרשות המסים
החיבור מתוכנן להתבצע פעם אחת לכל עסק, דרך זרימת OAuth 2.0 (authorization_code). הטוקנים נשמרים מוצפנים ומתרעננים אוטומטית. תהליך החיבור עדיין בפיתוח ויהיה זמין כשהחיבור ייפתח. כך הוא מתוכנן לעבוד:
- היכנסו להגדרות ← רשות המסים, ולחצו "התחבר".
- המערכת מפנה ל‑
/tax-authority/connectומשם לאישור באתר הרשות. - לאחר האישור, החזרה ל‑
/tax-authority/connect/completeמסיימת את החיבור. - הטוקן נשמר מוצפן; כל בקשת הקצאה משתמשת בו אוטומטית.
יצירת חשבונית מס
בעת יצירת חשבונית, המערכת מקצה מספר רץ ייחודי לכל סוג מסמך, בצורה אטומית (נעילת שורה), כך שלעולם אין כפילות או דילוג, גם תחת עומס מקבילי.
- מונה נפרד לכל סוג מסמך (חשבונית מס, קבלה, זיכוי).
- חישוב מע״מ אוטומטי לפי השיעור התקף.
- פרטי חובה: שם העוסק, ח.פ, פרטי לקוח, פירוט, מקור/עותק.
קבלת מספר הקצאה
לא כל חשבונית זקוקה להקצאה. רק חשבונית מס מעל הסף ללקוח עסקי מחייבת מספר הקצאה, והיא מסומנת כממתינה עד שהמספר נקלט. החיבור האוטומטי לרשות המסים (שע״ם), שמביא את המספר, עדיין בפיתוח ואינו פעיל; בינתיים מזינים במערכת את מספר ההקצאה שהתקבל מרשות המסים, והוא נשמר על המסמך ומודפס על ה‑PDF. קבלות, חשבוניות מתחת לסף ומסמכים שאינם דורשים הקצאה מונפקים מיד, ללא פנייה לרשות המסים.
אין מספר הקצאה עדיין? החשבונית מונפקת
חשבונית מס מעל הסף מונפקת גם ללא מספר הקצאה, ומסומנת כממתינה למספר. משלימים את המספר מאוחר יותר דרך POST /invoices/{id}/allocation או מהמסך של המסמך, והוא נשמר ומודפס על ה-PDF. המערכת מוודאת שהמספר תקין (ספרות בלבד) ולעולם אינה יוצרת מספר הקצאה מזויף. הבקשה האוטומטית של המספר מול שע״ם עדיין בפיתוח ואינה פעילה.
ביטול וחשבונית זיכוי
חשבונית שהונפקה אינה ניתנת לעריכה או מחיקה. אם החשבונית כבר נשלחה או קיבלה מספר הקצאה, הביטול נחסם, ובמקומו יש להפיק חשבונית זיכוי.
- ביטול מסמן
status = cancelledושומר את המסמך (כולל PDF עם סימון "מבוטל"). - תיקון סכומים מתבצע אך ורק דרך חשבונית זיכוי, שרשרת ביקורת שלמה.
בוט הטלגרם
הבוט @Sminvoices_bot מנפיק חשבוניות וקולט הוצאות ישירות מהצ'אט - אותו חשבון, אותם מסמכים ואותו מספור כמו בפורטל. הבוט מובל בכפתורים: בכל שלב יש כפתורי חזרה וביטול, ואין צורך לזכור פקודות.
חיבור החשבון
מתחברים פעם אחת, בטלגרם עצמו: בפורטל, תחת הגדרות ← חיבורים ו-API ← "חבר טלגרם", נפתח קישור חד-פעמי לבוט. לוחצים Start - והחשבון מחובר עד שתבחרו להתנתק (כפתור ניתוק נמצא באותו מסך). אפשר גם לפתוח את הבוט ישירות: הוא יפנה אתכם לפורטל להשלמת החיבור המאובטח.
מה הבוט יודע לעשות
- הנפקת חשבונית - תהליך מודרך, שדה אחד בכל שלב: סוג מסמך (כל 10 הסוגים, לפי סוג העוסק שלכם), פרטי לקוח, פריטים ומחירים, הנחה, אמצעי תשלום בקבלות (כולל אסמכתא חובה בצ'ק, העברה ואשראי חיצוני), סיכום ואישור. ה-PDF חוזר לצ'אט, ואפשר לשלוח ללקוח במייל בכפתור אחד.
- העלאת הוצאה - מצלמים קבלה או שולחים PDF, והמסמך נקלט בהוצאות עם זיהוי ספק, סכום ומע״מ.
- טקסט חופשי - כותבים "חשבונית" או "הוצאה" והבוט פותח את התהליך המתאים.
- שינוי שפה - עברית, אנגלית או צרפתית, מכפתור "שינוי שפה" בתפריט.
דוגמת שיחה
אתם: /start
הבוט: מה נעשה היום? [הנפקת חשבונית] [העלאת הוצאה] [עזרה] [שינוי שפה]
אתם: [הנפקת חשבונית]
הבוט: איזה מסמך מנפיקים? [חשבונית מס-קבלה] [חשבונית מס] [קבלה] ...
אתם: [חשבונית מס-קבלה]
הבוט: למי מפיקים? כתבו את שם הלקוח.
אתם: דוד כהן
הבוט: (טלפון, מייל, פריט ומחיר - שדה אחרי שדה)
אתם: ייעוץ, 3500
הבוט: איך שולם? [מזומן] [אשראי חיצוני] [העברה בנקאית] [ביט] [צ'ק]
אתם: [העברה בנקאית]
הבוט: הקלידו אסמכתא / מספר פעולה:
אתם: 88231
הבוט: לקוח: דוד כהן · ייעוץ: 3500 x 1 · תשלום: העברה בנקאית · סה"כ: 3,500 ש"ח [הפק] [עריכה]
אתם: [הפק]
הבוט: ✓ הופקה חשבונית 10000012 על סך 4,130 ש"ח. (PDF מצורף) [שליחה במייל]
אותם ספרים בדיוק
מסמך שהונפק מהבוט זהה לחלוטין למסמך מהפורטל: אותו רצף מספור, אותו PDF, אותו תיעוד ואותה שמירה לשבע שנים.
מודל "חשבוניות ישראל"
תיקון 63 לחוק מע״מ מחייב מספר הקצאה על חשבונית מס מעל הסף: בלי מספר הקצאה, הלקוח אינו יכול לקזז את מס התשומות בגין החשבונית. המודל חל על עוסק מורשה, חברות ושותפויות. כרגע המספר מוזן במערכת ידנית; בקשת המספר האוטומטית מול שע״ם עדיין בפיתוח ותיפתח בהמשך.
ספים
הספים יורדים בהדרגה ונטענים מהגדרת המערכת, ניתנים לעדכון מיידי ללא גרסה חדשה.
| תקופה | סף (לפני מע״מ) |
|---|---|
| סף התחלתי | ₪25,000 |
| מ‑1.1.2025 | ₪20,000 |
| מ‑1.1.2026 | ₪10,000 |
| מ‑1.6.2026 | ₪5,000 |
שימור ואי‑שינוי
- שימור 7 שנים לכל המסמכים הפיסקליים; מסמכים אלה מוחרגים מכל מחיקה תקופתית.
- אי‑שינוי, מסמך שהונפק אינו נערך או נמחק; תיקון רק בחשבונית זיכוי.
- מספור רץ ללא דילוגים, עם נעילת שורה atomic לכל הקצאה.
חיבור העסק לרשות המסים · OAuth 2.0
זהו החיבור בין העסק לרשות המסים, ולא אימות של הלקוח מול ה‑API שלנו. כל עסק מתחבר ומאשר גישה אצל הרשות בזרימת OAuth 2.0 (authorization_code); המערכת שומרת access ו‑refresh token מוצפנים, ומרעננת אוטומטית לפני פקיעה. הטוקן הזה נשלח מהשרת שלנו אל הרשות בבקשת הקצאה, ולעולם אינו נשלח על ידי קורא ה‑API.
Authorization: Bearer <access_token>
Content-Type: application/json
נקודות קצה
בסיס הכתובות: https://lhflow.com/smartinvoice/api/v1. כל בקשה נושאת Authorization: Bearer <token>, אך סוג הטוקן נקבע לפי נקודת הקצה ואינו בר‑החלפה: POST /documents מקבלת מפתח API בפורמט sk_live_... בלבד, וכל שאר נקודות הקצה מקבלות JWT של משתמש מחובר בלבד. טוקן ה‑OAuth של רשות המסים אינו משמש לאימות מול ה‑API הזה - הוא נשלח מהשרת שלנו אל הרשות בלבד. כל השדות בגוף הבקשה הם JSON.
נתיבים שמוגשים כרגע רק בבסיס הקודם
הנתיבים /expenses/recurring, /wa-inbox/business-hours, /wa-inbox/client-errors, /inbox/conversations, /inbox/reply ו‑/inbox/messages/{id}/react זמינים כיום רק בבסיס הקודם https://lhflow.com/fixmaster/api/v1. חשיפתם בבסיס https://lhflow.com/smartinvoice/api/v1 בפיתוח ועדיין אינה פעילה - עד אז יש לפנות אליהם בבסיס הקודם.
חיבור לרשות המסים
| שיטה | נתיב | תיאור |
|---|---|---|
| GET | /tax-authority/connect | פתיחת זרימת חיבור OAuth לעסק |
| POST | /tax-authority/connect/complete | סיום החיבור עם קוד ההרשאה שהתקבל, ושמירת הטוקן |
| POST | /invoices/{id}/allocation | בקשת מספר הקצאה לחשבונית |
חשבוניות ומסמכים
| שיטה | נתיב | תיאור |
|---|---|---|
| GET | /invoices | רשימת מסמכים (סינון לפי תאריך/סוג/סטטוס) |
| POST | /invoices | יצירת מסמך. invoice_type אחד מ‑15 הסוגים הנתמכים; אם לא נשלח - נגזר מברירת‑המחדל של העסק |
| GET | /invoices/types | רשימת סוגי‑המסמכים + שמותיהם + יעדי‑המרה |
| GET | /invoices/numbering | קידומות והמספר הבא לכל סוג |
| POST | /invoices/numbering | עדכון קידומת/מספר לסוג מסמך |
| POST | /documents | יצירת מסמך באמצעות מפתח API (sk_live_...) - לאינטגרציות ומערכות חיצוניות |
דוגמה · יצירת מסמך POST /documents
יצירת חשבונית מס קבלה עם פריט אחד ותשלום במזומן, באמצעות מפתח API אישי. המסמך נוצר, ממוספר ומופק בקריאה אחת; התגובה (201) מחזירה את המסמך המלא תחת document.
הוצאות
| שיטה | נתיב | תיאור |
|---|---|---|
| GET | /expenses | רשימת הוצאות (לפי תאריך‑המסמך) |
| POST | /expenses/upload | העלאת חשבונית/קבלה לזיהוי OCR |
| GET | /expenses/recurring | הוצאות קבועות - רשימה + סה״כ חודשי |
| POST | /expenses/recurring | יצירת הוצאה קבועה (שכירות/משכורות/מנוי) |
| PUT | /expenses/recurring/{id} | עדכון הוצאה קבועה |
| DELETE | /expenses/recurring/{id} | מחיקת הוצאה קבועה |
הגדרות
| שיטה | נתיב | תיאור |
|---|---|---|
| GET | /invoices/unified-settings | הגדרות עסק + חשבוניות (עטוף ב‑settings) |
| GET | /invoice-settings | הגדרות חשבונית כולל default_invoice_type |
| PUT | /invoice-settings | עדכון הגדרות (קידומות, מע״מ, ברירת‑מחדל לסוג מסמך) |
| GET | /wa-inbox/business-hours | שעות פעילות + מצב שבת (off/fixed/auto) |
| PUT | /wa-inbox/business-hours | עדכון שעות פעילות (בעלים בלבד) |
תיבת דואר מאוחדת (Spikit)
| שיטה | נתיב | תיאור |
|---|---|---|
| GET | /inbox/conversations | רשימת שיחות (מסונן לפי מחלקה) |
| POST | /inbox/reply | מענה לשיחה בערוץ המקורי |
| POST | /inbox/messages/{id}/react | הוספת/הסרת תגובת אימוג׳י (נשלחת גם ללקוח) |
| POST | /wa-inbox/client-errors | דיווח שגיאות מאפליקציית הלקוח למערכת מעקב התקלות |
דוגמה · יצירת הוצאה קבועה
"name": "שכירות",
"amount": 4500,
"currency": "ILS",
"day_of_month": 1,
"category": "שכר דירה",
"auto_create": true
}
בקשת הקצאה
שולחים POST לנתיב ההקצאה, ללא גוף בקשה. מזהה החשבונית נלקח מכתובת הנתיב; ח.פ הלקוח והסכום נקראים מהחשבונית השמורה בשרת. ההקצאה מתבצעת רק אם החשבונית מסומנת כטעונת הקצאה (מעל הסף) וטרם התקבל עבורה מספר הקצאה.
פרמטרים
| שדה | סוג | תיאור |
|---|---|---|
| invoice_id חובה | string | מזהה החשבונית להקצאה, בכתובת הנתיב (path) ולא בגוף הבקשה |
תגובה · 200 OK
"status": "success",
"message": "מספר הקצאה התקבל בהצלחה",
"allocation_number": "847392015",
"allocation_date": "2026-07-17 10:32:00",
"source": "shaam"
}
דוגמה · בקשת הקצאה
קודי שגיאה
POST /documents (מפתח API)
| קוד | מזהה | משמעות |
|---|---|---|
| 201 | ok | המסמך נוצר (הגוף כולל document) |
| 400 | invalid_body | גוף הבקשה חסר או אינו JSON |
| 400 | validation_failed | שדה לא עבר ולידציה (פירוט ב-message) |
| 400 | payment_required | מסמך עם קבלה (receipt / tax_invoice_receipt) חייב payment.method + amount |
| 400 | cash_law_blocked | המזומן חורג מחוק צמצום השימוש במזומן (עד ₪6,000; בעסקה מעל ₪6,000 המגבלה היא הנמוך מבין ₪6,000 ל-10% ממחיר העסקה). details כולל את המגבלה |
| 400 | invalid_allocation_number | allocation_number חייב ספרות בלבד |
| 401 | invalid_token | מפתח API חסר או שגוי |
| 403 | insufficient_scope | למפתח אין הרשאת documents:create |
| 429 | rate_limited | חריגה ממגבלת קצב הבקשות של מפתח ה-API (ברירת מחדל: 60 לדקה, 1,000 לשעה, 5,000 ליום) - יש להאט ולנסות שוב. limit כולל את המגבלה שנחצתה |
| 429 | api_quota_exceeded | נוצלה מכסת המסמכים החודשית של ה-API (כשמוגדרת מכסה; כברירת מחדל אין מכסה חודשית) |
| 500 | - | שגיאה פנימית (מדווחת אוטומטית) |
הודעות השגיאה (message) באנגלית ומיועדות למפתחים; code יציב לתכנות מולו; details מובנה כשרלוונטי. תרגום למשתמש הקצה הוא באחריות הצד שלכם.
API הקצאה מול רשות המסים (שע״ם)
| קוד | מזהה | משמעות |
|---|---|---|
| 200 | success | מספר הקצאה התקבל ונשמר על החשבונית |
| 400 | - | המסמך אינו דורש הקצאה, או שכבר יש לו מספר |
| 403 | pending_tax_authority_approval | החיבור לרשות המסים עדיין לא נפתח |
| 404 | - | החשבונית לא נמצאה בעסק הזה |
| 502 | allocation_unavailable | שע״ם לא החזיר מספר. המערכת לעולם אינה ממציאה מספר, ולכן ההקצאה לא נשמרה - אפשר לנסות שוב או להזין ידנית |
חתימות דיגיטליות (SmartSign)
SmartSign מחתים לקוח על מסמך - חשבונית קיימת או PDF שהעליתם - דרך קישור, ובונה סביב החתימה שובל ראיות חתום. העסק מרכיב בקשה, ממקם על המסמך תיבת חתימה (כשבר מהעמוד), ושולח ללקוח קישור; הלקוח חותם מהטלפון בלי חשבון ובלי התחברות. הקישור חתום ב-HMAC ותקף 30 יום.
מה זו החתימה הזו, מבחינה משפטית
זו חתימה רגילה של הלקוח לפי חוק חתימה אלקטרונית (סעיף 3(א)), ולא חתימה מאושרת מבוססת תעודה. זהות החותם אינה מאומתת - זה מכוון - אלא אם הופעל אימות OTP לאותו מסמך. את שובל הראיות (מה נשלח, למי, מתי נצפה ומאיזה IP, ומה חזר) המערכת חותמת בחתימה האלקטרונית המאובטחת שלה (RSASSA-PSS מעל SHA-256), וזו הראיה לכך שהמסמך לא שונה לאחר החתימה. הנטל להוכיח שהלקוח חתם מוטל עלינו לפי סעיף 3א, ולכן כל אירוע נשמר.
איך זה עובד
- העסק מרכיב בקשה: בוחר מסמך (חשבונית קיימת או PDF שהועלה), ממקם תיבת חתימה, ומזין את פרטי החותם.
- שליחת הקישור בוואטסאפ או במייל. הקישור נושא חתימת HMAC ואינו דורש התחברות.
- הלקוח פותח את הקישור, קורא את המסמך, וחותם - בציור, בהקלדה או בהעלאת תמונת חתימה. נרשם אירוע צפייה עם IP ו-User-Agent.
- אם הופעל OTP, נשלח לחותם קוד בן 6 ספרות והוא נדרש לפני החתימה.
- בעת החתימה, החתימה נשמרת, מוטבעת אל תוך ה-PDF, ותעודת השלמה (Certificate of Completion) נחתמת בחתימה המאובטחת מעל כל שובל הראיות.
נקודות קצה · העסק (JWT)
נקודות הקצה של העסק דורשות JWT של משתמש מחובר. הן זמינות בבסיס https://lhflow.com/fixmaster/api/v1 וגם בבסיס https://lhflow.com/smartinvoice/api/v1.
| שיטה | נתיב | תיאור |
|---|---|---|
| POST | /signatures/requests | יצירת בקשת חתימה (מסמך, חותם ותיבות מיקום). מחזיר 201 עם id |
| GET | /signatures/requests | רשימת בקשות החתימה של העסק |
| GET | /signatures/requests/{id} | פרטי הבקשה, שדות המיקום ושובל האירועים |
| POST | /signatures/requests/{id}/send | שליחת קישור החתימה לחותם (וואטסאפ/מייל) |
נקודות קצה · החותם (ציבורי)
נתיבי /sign/... אינם דורשים התחברות - חתימת ה-HMAC בקישור (exp ו-sig בכתובת) היא כל השער. קישור לא תקף או שפג תוקפו מוחזר כ-403.
| שיטה | נתיב | תיאור |
|---|---|---|
| GET | /sign/{id} | פרטי המסמך לחתימה; כותב אירוע צפייה עם IP ו-User-Agent |
| GET | /sign/{id}/document | קובץ ה-PDF לקריאה לפני החתימה |
| POST | /sign/{id}/otp | שליחת קוד OTP (ללא גוף) או אימותו ({"code":"…"}) |
| POST | /sign/{id}/submit | שליחת החתימה (signature_image כ-PNG בבסיס 64) וחיתום התעודה |
קודי שגיאה
| קוד | מזהה | משמעות |
|---|---|---|
| 403 | Forbidden | קישור החתימה חסר, או שחתימת ה-HMAC שגויה. לא נכתב אירוע |
| 403 | expired | פג תוקף הבקשה (מעבר ל-30 יום) |
| 403 | otp_required | המסמך דורש OTP והחותם טרם אימת קוד |
| 403 | invalid_code | קוד ה-OTP שהוזן שגוי |
| 404 | Not found | הבקשה לא נמצאה (גם בעסק זר, כדי לא לאשר שהמזהה קיים) |
| 409 | already_signed | המסמך כבר נחתם; חתימה או שליחה חוזרת נחסמת - השובל כבר חתום |
| 429 | too_many_attempts | יותר מדי ניסיונות OTP שגויים (עד 5) |
| 400 | invalid signature_image | התמונה שהתקבלה אינה PNG תקין |
| 500 | Signing links are not configured | SECRET_KEY אינו מוגדר; השליחה נחסמת (fail-closed) ולעולם אינה יוצאת ללא חתימה |
| 500 | Internal error | שגיאה פנימית (מדווחת אוטומטית) |
אינטגרציות לחנויות
חיבור חנות אינטרנט בלי שורת קוד - כל הזמנה משולמת מפיקה מסמך אוטומטית.
WooCommerce (וורדפרס)
- מורידים את התוסף: smartinvoice-woocommerce.zip
- בוורדפרס: תוספים ← הוספת תוסף ← העלאת תוסף ← הפעלה.
- WooCommerce ← הגדרות ← לשונית SmartInvoice ← מדביקים מפתח API (מהפורטל: הגדרות ← חיבורים ו-API) ומפעילים.
התוסף מפיק חשבונית מס קבלה (או קבלה / חשבונית מס) בכל תשלום, מונע כפילות להזמנה, מוסיף כפתור הפקה ידנית בכל הזמנה, ומציג את מספר המסמך גם במייל ללקוח.
Shopify / Wix - הדבקת כתובת אחת
- בפורטל SmartInvoice: הגדרות ← חיבורים ו-API ← "חיבור חנות אינטרנט" ← מעתיקים את הכתובת האישית.
- Shopify: Settings ← Notifications ← Webhooks ← Create webhook ← אירוע Order payment ← מדביקים את הכתובת (פורמט JSON).
- Wix: Automations ← אוטומציה חדשה ← טריגר "New order" (Wix Stores) ← פעולה "Send via webhook" ← מדביקים את הכתובת.
כל הזמנה משולמת מפיקה חשבונית מס קבלה אוטומטית: פריטים, משלוח, לקוח וסה"כ (מחירים כולל מע"מ). הזמנה שכבר הופק לה מסמך לא תופק פעמיים. מערכות אחרות יכולות לשלוח לאותה כתובת JSON גנרי: {"order_id", "total", "customer": {...}, "items": [{"description","quantity","unit_price"}], "payment_method"}.
הגדרות
| הגדרה | תיאור |
|---|---|
| allocation_thresholds | סף ההקצאה, נטען מ‑system_config וניתן לעדכון ללא release |
| SHAAM_SANDBOX | מעבר בין סביבת sandbox ל‑production |