תיעוד API למפתחים

התיעוד המלאAPI של מנוע ההפקה

כל פעולה שיש במסכים יש גם ב-API: הרשמת עסק, הפקת כל סוגי המסמכים (כולל חשבונית זיכוי וקבלה על חשבונית), מספר הקצאה, מקור והעתק, הסכמות, מבנה אחיד, סקירת העסק ויומן הפעולות על כל מסמך, וחיבור לרשות המסים (מנוע 0.17), וקוד חתימה שרק העסק מחזיק (מנוע 0.18), ומינויי אוטומציה ל-Zapier ול-Make (מנוע 0.19), ומגבלות קצב לכל מפתח, טוקן וכניסה (מנוע 0.20). המסכים עצמם (ההרשמה והאזור האישי) עושים בדיוק את אותן פעולות מול אותו מנוע.

כל הקריאות תחת /v1 דורשות כותרת Authorization: Bearer <token>, חוץ מ-/v1/auth/login, /v1/auth/signup ושני הנתיבים הציבוריים של קישורי שיתוף (/v1/share/:token), שבהם הטוקן שבנתיב הוא ההרשאה. יש שישה סוגי טוקנים:

מה אפשר לעשות עם טוקן המשגר (או עם אישור whd1 תקף), אם הוא דולף: לקרוא את משלוחי ה-standard שממתינים בכל העסקים (גוף ההודעות, החתימות והכתובות המלאות של המקבלים, כולל הפרמטרים שבהן), לדווח שמשלוח נשלח כשלא נשלח, לעכב משלוחים, ואחרי 3 דיווחים במשך 10 דקות לפחות – להשבית webhook. מה אי אפשר: לקרוא סודות חתימה או טוקנים של routines, להפעיל routines של Claude בעצמו (המנוע שולח אותם, והטוקן לא יוצא ממנו), או לגשת לכל נתיב אחר. החלפה: ב-Supabase: select vault.update_secret(id, encode(extensions.gen_random_bytes(32), 'hex')) from vault.secrets where name = 'invoice_engine_dispatch_token'; (ה-Edge Function קורא את הערך החדש תוך 60 שניות, ו-pg_net מפיק ממנו אישורים מיד). בשרת ה-Node: משנים את משתנה הסביבה ומפעילים מחדש.

תפקידים בעסק:

כרטיסי לקוח ופריטים (מנוע 0.16) יוצרים ועורכים מי שמפיקים: בעל העסק ועובד; רואה חשבון רק צופה. מפתחות API ומשתמשים מנהל בעל העסק (או המנהל). מפתח API מוצג פעם אחת בלבד, ובבסיס הנתונים נשמר רק ה-SHA-256 שלו. כל פעולה על מסמך נרשמת ביומן בשם מי שביצע אותה (אימייל המשתמש, או שם המפתח). פעולה בטוקן גישה אישי נרשמת כאימייל ושם הטוקן, למשל nissim@example.com (token Claude).

משתמשים וכניסה

סיסמה: 10 תווים לפחות, לא רק מספרים, ולא שם המשתמש מהאימייל. נשמר רק hash מסוג PBKDF2-SHA256 (600,000 חזרות) עם salt אקראי. את אימות הדו-שלבי (שלוש הקריאות של /v1/me/two-factor), שינוי הסיסמה, יצירת טוקן גישה אישי, יצירת מפתח API לעסק והזמנה לעסק אפשר לעשות רק בכניסה עם סיסמה, לא בטוקן גישה אישי (403).

טוקני גישה אישיים (למשל לחיבור Claude / MCP)

משתמש יוצר טוקן לחיבור חיצוני, והחיבור פועל בשמו: אותם עסקים ואותן הרשאות לפי התפקיד בכל עסק (רואה חשבון בטוקן עדיין לא מפיק מסמכים). כשהמשתמש מוסר מעסק, גם הטוקן מאבד את הגישה אליו. הטוקן מוצג פעם אחת בלבד, ובבסיס הנתונים נשמר רק ה-SHA-256 שלו. שולחים אותו כמו כל טוקן: Authorization: Bearer iep_....

טוקן שדלף נגמר כשמבטלים אותו, כשמשנים סיסמה או כשמנהל מבטל את הטוקנים של המשתמש. לכן הוא לא יכול ליצור גישה שנשארת אחריו: לא טוקן חדש, לא מפתח API לעסק (POST /v1/businesses/:id/api-keys) ולא הזמנה לעסק (POST /v1/businesses/:id/invitations). את אלה עושים רק בכניסה עם סיסמה (בטוקן מתקבל 403). לבטל מפתח או הזמנה מותר גם בטוקן. מאותה סיבה טוקן לא יוצר webhook, לא מפעיל מחדש webhook מושבת, לא מוסיף לו סוגי אירועים, לא משנה את הכתובת שלו או את הטוקן של ה-routine, לא מחליף את סוד החתימה ולא מציג את הכתובת המלאה (כל אלה דורשים גם את הסיסמה שוב בגוף הבקשה), ולא שולח בדיקה או שליחה חוזרת ל-routine של Claude (כל אחת פותחת שיחה בחשבון של בעל העסק). להשהות, לצמצם, למחוק, לבדוק webhook רגיל ולשלוח שוב משלוח שנכשל – מותר גם בטוקן.

שינוי סיסמה (או איפוס על ידי מנהל) מבטל את כל הטוקנים של המשתמש, כמו את הכניסות.

משתמשים בעסק (בעל העסק)

הסכומים הם באגורות (מספר שלם), והתאריכים בפורמט YYYY-MM-DD. השגיאות חוזרות כ-JSON בצורה { "error": "..." }:

מגבלות קצב (מנוע 0.20)

כל אישור נספר בנפרד: מפתח API (iek_), טוקן גישה אישי (iep_) וכניסת משתמש (ies_; כל הכניסות של אותו משתמש יחד). בנוסף, הפקת מסמכים מוגבלת לכל עסק, מכל האישורים יחד, כדי שאוטומציה שנתקעה בלולאה לא תשרוף מספרים בסדרה (מספר שהופק לא חוזר). המספרים נקבעים במקום אחד, RATE_LIMITS ב-engine/src/domain/rateLimit.ts:

• מה נחשב הפקה: POST /v1/businesses/:id/documents בלי dryRun. בדיקה בלי הפקה ("dryRun": true) ותצוגה מקדימה (/documents/preview) לא נספרות כהפקה (רק במגבלה הכללית). הספירה אחרי בדיקת ההרשאה, כך שאישור של עסק אחר לא מנצל את המכסה של העסק. כל ניסיון הפקה נספר, גם כזה שהמנוע דחה (422), כדי שאוטומציה ששולחת שוב ושוב בקשה שגויה תיעצר גם היא.
• מה לא נספר: GET /health, נתיבי המשגר (/v1/internal/*), טוקן המנהל, והנתיבים הציבוריים (כניסה והרשמה, קישורי שיתוף ואישור הסכמה), שיש להם מגבלות משלהם. טוקני שירות (ENGINE_API_TOKENS, מערכות של מפעיל השרת) לא נספרים במגבלה הכללית, אבל ההפקה שלהם נספרת במגבלת העסק.
• בקשה שעברה מקבלת את הכותרות של הטיוטה של IETF (draft-ietf-httpapi-ratelimit-headers): RateLimit-Limit (המכסה בדקה), RateLimit-Remaining (כמה נשארו), RateLimit-Reset (שניות עד הדקה הבאה) ו-RateLimit-Policy (כל המגבלות שחלות, למשל 10;w=1, 120;w=60). בהפקה – של מגבלת ההפקה (2;w=1, 60;w=60).
• בקשה שנחסמה: 429 עם Retry-After (שניות), אותן כותרות (RateLimit-Remaining: 0), והודעה בעברית: { "error": "יותר מדי בקשות. נסו שוב בעוד 45 שניות.", "retryAfter": 45 }. הבקשה לא בוצעה (גם לא הפקה: שום מספר לא נשרף), ולכן בטוח לשלוח אותה שוב אחרי ההמתנה. גם בקשה שנחסמה נספרת בדקה שלה, כך שמי שממשיך לשלוח בלי לחכות לא מקבל מכסה חדשה באמצע הדקה.
• ניסיונות חוזרים: מחכים לפחות Retry-After שניות, ואם שוב 429 – מכפילים את ההמתנה (1, 2, 4, 8... שניות, עם רכיב אקראי קטן) עד דקה. לא שולחים שוב בלולאה צמודה. בהפקה רצופה (למשל ייבוא) שולחים אחת אחרי השנייה, לא במקביל. Zapier מטפל בזה לבד (ThrottledError עם ההמתנה), וב-Make מגדירים טיפול בשגיאה (Break עם ניסיונות חוזרים).
• איך זה עובד בכמה עותקים: המנוע רץ ב-Edge Function בכמה עותקים במקביל, ומונה בזיכרון רואה רק את העותק שלו. לכן המגבלה לדקה נספרת ב-Postgres (טבלת api_rate_counters, מיגרציה 021): upsert אחד לבקשה (INSERT ... ON CONFLICT DO UPDATE ... RETURNING hits) על שורה אחת לאישור ולדקה, בטבלה UNLOGGED (בלי יומן כתיבה; אחרי קריסה של בסיס הנתונים היא מתרוקנת, וזה רק מאפס את הדקה). חלון קבוע ולא נע: שורה אחת במקום שורה לכל בקשה; את החריגה האפשרית סביב גבול הדקה מחליק הפרץ שבזיכרון. בהפקה יש upsert שני (של העסק). אם המונה לא זמין, הבקשה עוברת (ונרשמת שורה ביומן).

בריאות

GET /health → { "ok": true, "software": "...", "version": "...", "registrationNumber": "...", "build": "<sha256>" } (בלי טוקן). build היא טביעת המהדורה שרצה בשרת, כדי לוודא שזו המהדורה שנרשמה (ראו EDITIONS.md).

מצב קריאה בלבד (מנוע 0.21)

בחלון ההקפאה של העברת השרת (ובתחזוקה) השרת יכול לרוץ במצב קריאה בלבד (ENGINE_READ_ONLY=1, ראו deploy/README.md). אז /health כולל "readOnly": true, וכל בקשה שכותבת מקבלת 503 עם Retry-After: 600 ו- { "error": "המערכת במצב קריאה בלבד בזמן העברה לשרת חדש...", "readOnly": true }: כל POST/PUT/PATCH/DELETE חוץ מ-/v1/auth/login ו-/v1/auth/logout, וגם GET שרושם משהו בספרים (העתק /v1/documents/:id/copy, ה-PDF של קישור שיתוף, ייצוא מלא /v1/businesses/:id/archive). כל השאר (רשימות, מסמך, סקירה) עובד כרגיל. מערכת שמתחברת ל-API מנסה שוב אחרי Retry-After.

הרשמת עסק

קריאה אחת שעושה את כל מה שעושה מסך ההרשמה, בטרנזקציה אחת (אם שלב נכשל, לא נשאר עסק חצי רשום). משתמש מחובר נעשה בעל העסק (כשהשרת פתוח להרשמה עצמית). מנהל יכול לצרף בעל עסק עם "owner": { "email", "name", "password" }; אם האימייל כבר רשום, המשתמש הקיים מצורף.

POST /v1/businesses/register

{
  "name": "חויה בקליק",
  "vatNumber": "316288877",
  "kind": "licensed",
  "street": "שמואל הנביא", "houseNumber": "7", "city": "בני ברק", "phone": "054-...", "email": "...",
  "firstNumbers": { "305": 60001, "320": 50001, "330": 80001, "400": 70001 },
  "computerizedNoticeSentOn": "2026-10-01"
}

• נפתחות כל הסדרות שמותרות לסוג העסק: עוסק מורשה וחברה 305, 320, 330, 400; עוסק פטור 300, 400; עמותה 400. סדרה שלא צוינה ב-firstNumbers מתחילה ב-1. סדרה שאסורה לסוג העסק נדחית. מספר התחלה הוא מספר שלם מ-1 עד 9,999,999,999 (10 ספרות). כל עוד לא הופק בסדרה מסמך, אפשר להעלות אותו אחר כך (שינוי מספר ההתחלה).
• נוצרים מפתח ותעודת חתימה לעסק.
• computerizedNoticeSentOn לא חובה. בלעדיו אפשר להפיק רק מקור להדפסה, עד שרושמים את התאריך.

התשובה: 201 { businessId, sequences: [{ docType, firstNumber }], certificatePem }.

סקירת העסק

GET /v1/businesses/:id מחזיר את מה שמוצג במסך הסקירה באזור האישי:

גם GET /v1/businesses מחזיר לכל עסק את real_documents_since (או null).

תקרת המחזור השנתי: עוסק פטור ועסק זעיר (מנוע 0.22)

GET /v1/businesses/:id/turnover?year=2026 (כל מי שרשאי לקרוא את העסק; year לא חובה, ברירת המחדל היא השנה הנוכחית בשעון ישראל) → { businessId, year, kind, smallBusiness, applies, demo, turnoverAgorot, ceilingAgorot, ceilingSource, percent, level, message, parametersReviewed }.

• המחזור (באגורות, לפי תאריך המסמך בשנה): עוסק מורשה / חברה – חשבוניות מס (305) וחשבוניות מס / קבלה (320) פחות חשבוניות זיכוי (330), לפני מע"מ; קבלות וחשבון עסקה לא נספרים. עוסק פטור – חשבוניות עסקה (300) וקבלות (400) שאינן מפנות לחשבונית עסקה (קבלה על חשבונית עסקה היא תשלום על עסקה שכבר נספרה), כולל ניכוי במקור. עמותה – קבלות וקבלות על תרומה, לידיעה בלבד.
• התקרה חלה (applies: true) על עוסק פטור ועל עסק שמסומן עסק זעיר (smallBusiness, למטה). ceilingSource הוא exempt או small_business (לעוסק פטור שהוא גם עסק זעיר – הנמוכה מביניהן). התקרות נקבעות לכל שנה בידי מנהל המערכת (פרמטרים שנתיים); לשנה בלי תקרה ceilingAgorot, percent ו-level הם null.
• level: ok מתחת ל-80%, near80 מ-80%, near90 מ-90%, over כשהמחזור עולה על התקרה. message בעברית מ-near80 ומעלה (ב-over של עוסק פטור: לפנות למשרד מע"מ כדי לעבור למעמד עוסק מורשה; של עסק זעיר: יציאה ממסלול עסק זעיר).
• demo: true כשהעסק במצב הדגמה: המחזור מחושב על מסמכי ההדגמה. במצב מסמכים אמיתיים נספרים רק מסמכים אמיתיים.

התראה בהפקה: כשמסמך מעביר את העסק את 80%, 90% או את התקרה עצמה, התשובה ל-POST /v1/businesses/:id/documents כוללת turnoverNotice: { kind: "turnover", year, level, ceilingSource, turnoverAgorot, ceilingAgorot, percent, demo, message }, וההודעה מתווספת גם ל-warnings. רק פעם אחת לכל סף (המסמך הבא באותה רמה לא מתריע), ולא בבדיקה בלי הפקה.

עסק זעיר: PUT /v1/businesses/:id עם { "smallBusiness": true } (בעל העסק; רק עוסק פטור או עוסק מורשה, אחרת 422). כל שינוי נרשם ביומן business_setting_changes (מה, מי ומתי). הסקירה מחזירה את business.smallBusiness.

שינוי מספר ההתחלה של סדרה

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

PUT /v1/businesses/:id/sequences/:docType עם { "nextNumber": 60001 } → 200 { docType, nextNumber, previousNextNumber }. המסמך הראשון מהסוג הזה יקבל את nextNumber.

• רק כלפי מעלה: nextNumber חייב להיות גדול מהמספר הבא הנוכחי (sequences[].nextNumber בסקירת העסק). אי אפשר להוריד מספר, גם לא חזרה למספר שהיה לפני שינוי קודם (הטריגר של בסיס הנתונים לא מאפשר מונה שחוזר אחורה).
• רק לפני המסמך הראשון מהסוג הזה בעסק. מסמכים מסוג אחר, או בדיקה בלי הפקה (dryRun), לא חוסמים. אחרי מסמך אחד – 409. אפשר לשנות כמה פעמים לפני המסמך הראשון, וכל פעם רק למעלה.
• מספר שלם מ-1 עד 9,999,999,999 (10 ספרות). המספר נשמר כ-bigint ומודפס כמו שהוא, ובמבנה האחיד יש לו 20 תווים; המגבלה משאירה מקום לכל המסמכים שאחריו ותופסת טעות הקלדה (אפס מיותר), שאחריה אי אפשר היה לחזור למספר נמוך.
• מי: בעל העסק או מנהל. מותר גם בטוקן גישה אישי (iep_), כי השינוי לא נותן גישה שנשארת אחרי הטוקן. לא במפתח API של עסק, לא בטוקן שירות, ולא לעובד או לרואה חשבון (403).
• יומן: כל שינוי נרשם (המספר הבא לפני ואחרי, מי ומתי), ואת הרשומות אי אפשר לשנות או למחוק. הן נכללות גם בייצוא המלא (sequence-changes.csv).
• מקביליות: השינוי וההפקה נועלים את העסק ואת הסדרה באותו סדר, ולכן רצים אחד אחרי השני: אם ההפקה נשמרה קודם, השינוי נדחה ב-409; אם השינוי נשמר קודם, המסמך מקבל את המספר החדש.

GET /v1/businesses/:id/sequences/changes (כל מי שיש לו גישת צפייה בעסק: בעל העסק, עובד, רואה חשבון, מפתח API של העסק, מנהל) → { changes: [{ id, docType, previousNextNumber, newNextNumber, actor, at }] }, מהישן לחדש. actor הוא אימייל המשתמש (בטוקן גישה אישי גם שם הטוקן, למשל nissim@example.com (token Claude)) או admin.

מעבר ממערכת אחרת: לכל סוג מסמך בנפרד קובעים המספר הבא = המספר האחרון שהופק במערכת הקודמת מאותו סוג + 1 (חשבונית מס, חשבונית מס/קבלה, זיכוי, קבלה וכו'), כך שהמספור ממשיך ברצף ולא חוזר על מספר שכבר הונפק באותה שנה (הוראה 18(א)(3)). את המספר האחרון בודקים במערכת הקודמת אחרי שמפסיקים להפיק בה. אף פעם לא מפיקים את אותו סוג מסמך בשתי המערכות במקביל: מפסיקים במערכת הקודמת, קובעים כאן את המספר הבא, ורק אז מפיקים כאן. מסמך שהופק במערכת הקודמת אחרי שנקבע המספר כאן היה מקבל מספר שהמערכת הזו תיתן שוב.

הקמה ידנית, צעד אחר צעד (מנהל)

ייצוא מלא

GET /v1/businesses/:id/archive (כל מי שיש לו גישת צפייה) מחזיר ZIP עם:

• originals/ – כל המקורות כפי שנמסרו ללקוחות, כולל החתימה הדיגיטלית;
• openformat/<שנה>/ – קובץ מבנה אחיד לכל שנת מס;
• documents.csv, consents.csv, events.csv – רשימת המסמכים, הסכמות הלקוחות ויומן הפעולות;
• sequence-changes.csv – שינויי מספר ההתחלה של סדרות (לפני המסמך הראשון בכל סדרה);
• mode-changes.csv – המעברים בין מצב הדגמה למצב מסמכים אמיתיים (ב-documents.csv העמודה "מסמך אמיתי": כן, או לא (הדגמה) למסמך שהופק במצב הדגמה);
• designs.csv – (מנוע 0.13) העיצובים של העסק: מזהה, שם, ברירת מחדל, ארכיון והגרסה הנוכחית. ב-documents.csv העמודות "עיצוב" (מזהה העיצוב) ו"גרסת עיצוב" אומרות באיזה עיצוב ובאיזו גרסה שלו הופק כל מסמך;
• customers.csv, items.csv – (מנוע 0.16) כרטיסי הלקוח והפריטים, ולכל כרטיס מזהי המסמכים (העמודה "מזהה" ב-documents.csv) שמקושרים אליו;
• certificates/ – תעודות החתימה, לאימות החתימות בעתיד;
• business.json, README.txt.

אפשר להוריד בכל עת, וגם בסיום השימוש, כדי לשמור את הרשומות 7 שנים (סעיף 25).

יומן הייצואים (מנוע 0.12): כל ייצוא מלא שהמנוע מחזיר נרשם בטבלה archive_exports (העסק, מי – actor כמו ביומן הפעולות, מתי ומספר המסמכים בקובץ). אי אפשר לשנות או למחוק רשומה. בסקירת העסק lastArchiveExportAt הוא הייצוא האחרון. לפי הוראה 25(ו)(2) הגיבוי נעשה בשבוע הראשון של כל רבעון, ונשמר בישראל במקום אחר מהמקום שבו מוחזקת המערכת; האתר מציג לבעל העסק ולרואה החשבון תזכורת כשלא הורד ייצוא מלא מתחילת הרבעון הנוכחי (שעון ישראל).

מצב מסמכים אמיתיים (מנהל)

בשרת שמסמן PDF של עסק במצב הדגמה בסימן מים (למשל "הדגמה בלבד – אינו מסמך חשבונאי"), מנהל המנוע יכול להעביר עסק מסוים למצב מסמכים אמיתיים. רק טוקן המנהל, או מפעיל עם גישה לבסיס הנתונים: לא בעל העסק, לא טוקן גישה אישי, לא מפתח API, לא טוקן שירות, ולכן גם לא כלי ה-MCP (כולם מקבלים 403). ממנוע 0.14 גם מנהל פלטפורמה מהאתר, בנתיב נפרד עם אימות מחדש (ראו ניהול מערכת); הנתיב כאן נשאר לטוקן המנהל בלבד.

עסק חדש ישר במצב מסמכים אמיתיים: בשרת שמוגדר כך (ENGINE_REAL_DOCUMENTS_DEFAULT=1 בשרת ה-Node, ‏realDocumentsByDefault ב-Edge Function; מופעל בשירות הייצור של רצף), עסק חדש – בהרשמה (POST /v1/businesses/register) או בהקמה של מנהל (POST /v1/businesses) – נפתח ישר במצב מסמכים אמיתיים: real_documents_since נקבע לזמן היצירה, ורשומה ביומן business_mode_changes (actor: system, וההערה אומרת מי פתח את העסק) נכתבת באותה טרנזקציה, דרך אותה פונקציה set_real_documents. בתשובת ההרשמה realDocumentsSince (או null כשהעסק נפתח במצב הדגמה), וב-/health ‏"realDocumentsByDefault": true. ברירת המחדל (0): עסק חדש נפתח במצב הדגמה. בשני המקרים המנהל יכול להעביר עסק בין המצבים בנתיב שלמטה (למשל עסק בדיקה למצב הדגמה).

PUT /v1/businesses/:id/real-documents עם { "enabled": true, "note": "למה" } (note לא חובה, עד 1,000 תווים) → 200 { realDocuments, realDocumentsSince, changed, changes: [{ id, realDocuments, actor, note, at }] }. enabled: false מחזיר את העסק למצב הדגמה. מעבר למצב שהעסק כבר נמצא בו לא משנה דבר ולא נרשם (changed: false). קודים: 400 (enabled שאינו true/false, note שאינו טקסט או ארוך מדי, מזהה עסק לא תקין), 403 (לא טוקן המנהל), 404 (העסק לא נמצא).

מפעיל עם גישה לבסיס הנתונים בלבד (למשל SQL Editor של Lovable Cloud, שבו טבלאות המנוע בסכימה invoice):

select * from invoice.set_real_documents('<מזהה העסק>'::uuid, true, '<מי מבצע>', '<למה>');
-- חזרה למצב הדגמה
select * from invoice.set_real_documents('<מזהה העסק>'::uuid, false, '<מי מבצע>', '<למה>');

הפונקציה (מיגרציה 013) נועלת את שורת העסק, מעדכנת את businesses.real_documents_since (זמן המעבר, או null) ורושמת את המעבר ביומן business_mode_changes (מצב, מי, הערה, מתי), הכול בטרנזקציה אחת; ה-API קורא לאותה פונקציה. ביומן אי אפשר לשנות או למחוק רשומה, והוא נכלל בייצוא המלא (mode-changes.csv). הפונקציה רצה בהרשאות מי שקורא לה (לא security definer), וההרשאה ל-PUBLIC הוסרה ממנה.

מה משתנה במסמכים:

• כל מסמך מקבל בהפקה את הסימון documents.real_document לפי המצב של העסק באותו רגע (באותה טרנזקציה, כשהעסק נעול), והסימון לא משתנה לעולם. מסמך שהופק לפני המעבר נשאר מסמך הדגמה, וכל העתק שלו ממשיך לצאת עם סימן המים. מסמך שהופק במצב מסמכים אמיתיים נשאר אמיתי גם אם העסק יחזור למצב הדגמה.
• במסמך אמיתי (מקור, העתק, ובדיקה בלי הפקה): אין סימן מים, והשורה התחתונה בכל עמוד היא בדיוק הופק על ידי העסק (במקום הופק באמצעות <שם התוכנה> <גרסה> | מספר רישום תוכנה: …). מספר העמוד וטביעת המסמך נשארים. מסמך הדגמה – בלי שינוי. תצוגת עיצוב לדוגמה (POST /v1/businesses/:id/design/preview) אינה מסמך ונשארת כמו שהייתה.
• realDocument (true/false) מוחזר בתשובת ההפקה, ב-GET /v1/documents/:docId ובבדיקה בלי הפקה.
• הסימון אינו חלק מ-contentHash: ה-hash מכסה את התוכן החשבונאי של המסמך ואת השרשרת, והסימון קובע רק איך הסביבה מציגה אותו. העמודה חסומה לשינוי כמו כל שורת המסמך, ולכן אין צורך להגן עליה גם ב-hash, וה-hash של מסמכים קיימים נשאר כפי שחושב.

ניהול מערכת (מנהלי פלטפורמה)

ממנוע 0.14 (מיגרציה 015) משתמש רגיל יכול להיות מנהל פלטפורמה (users.platform_admin): בעל התוכנה מנהל מהאתר (דף /admin) את מה שעד עכשיו רק טוקן המנהל יכול היה לעשות – רשימת כל העסקים והמעבר של עסק למצב מסמכים אמיתיים.

מה זה נותן, ומה לא:

• רק את הנתיבים /v1/platform/* שבטבלה. מנהל פלטפורמה לא מקבל גישה למסמכים, ללקוחות, להגדרות או למשתמשים של עסק שהוא לא חבר בו: שם ממשיכים לבדוק את התפקיד שלו בעסק (403 כמו לכל משתמש). הרשימה מציגה רק נתונים מסכמים.
• רק בכניסה עם אימייל וסיסמה (ies_). בטוקן גישה אישי (iep_), ולכן גם בכלי ה-MCP ובחיבור ל-Claude, במפתח API ובטוקן שירות – 403. אין כלי MCP לנתיבים האלה.
• המעבר עצמו דורש אימות מחדש בגוף הבקשה, כמו ביצירת טוקן גישה אישי: currentPassword, ו-code (מאפליקציית האימות, או קוד שחזור) כשיש אימות דו-שלבי. סיסמה שגויה: 401; חסר קוד או קוד שגוי: 401 עם twoFactorRequired: true. כישלונות נספרים כמו בכניסה: אחרי 5, חסימה לרבע שעה (429). קלט שגוי נבדק קודם ומחזיר 400 בלי להיספר.
• הסימון נקרא מחדש בכל בקשה: ביטול נכנס לתוקף מיד, גם בכניסה שכבר פתוחה.
• טוקן המנהל עובד גם בנתיבים האלה (בלי אימות מחדש, ונרשם admin).

איך מעניקים (המשתמש נרשם קודם באתר כרגיל). אין שום נתיב של משתמש שמעניק או מבטל – גם לא מנהל פלטפורמה אחר. רק טוקן המנהל (PUT /v1/users/platform-admin למעלה), או מפעיל עם גישה לבסיס הנתונים (למשל SQL Editor של Lovable Cloud, שבו טבלאות המנוע בסכימה invoice):

-- הענקה (נרשמת ביומן עם משתמש בסיס הנתונים שביצע אותה)
update invoice.users set platform_admin = true where email = 'owner@example.com';
-- או עם מי ולמה ביומן
select * from invoice.set_platform_admin('owner@example.com', true, '<מי מבצע>', '<למה>');
-- ביטול
select * from invoice.set_platform_admin('owner@example.com', false, '<מי מבצע>', '<למה>');
-- מי מנהל עכשיו, והיומן
select email, name from invoice.users where platform_admin;
select * from invoice.platform_admin_changes order by id;

כל שינוי של העמודה – דרך הפונקציה, דרך טוקן המנהל או ב-update ישיר – נרשם בטריגר ביומן platform_admin_changes (המשתמש, האימייל, המצב החדש, מי ביצע, הערה ומתי). ביומן אי אפשר לשנות או למחוק רשומה. הפונקציה רצה בהרשאות מי שקורא לה, וההרשאה ל-PUBLIC הוסרה ממנה. האימייל צריך להיות כמו שנרשם (באותיות קטנות).

פרמטרים שנתיים (מנוע 0.22)

תקרות המחזור של עוסק פטור ועסק זעיר לכל שנה (טבלת annual_parameters, מיגרציה 022; 2025 ו-2026 נזרעו כערכים התחלתיים שלא אושרו). שיעור המע"מ וסף מספר ההקצאה לא כאן: הם בקוד לפי תאריך תחילה, כדי שכל מסמך ישן יחושב בדיוק כפי שהופק, ושינוי שלהם הוא עדכון תוכנה.

ספר הלקוחות של היצרן (מנהל)

GET /v1/admin/customer-register מחזיר את כל ההרשמות ושינויי הפרטים (שם, כתובת, מספר עוסק, טלפון, אימייל, מתי), לפי נספח ה'(ה). הרשומות לא משתנות ולא נמחקות.

עיצובים ומותגים

מנוע 0.13: לעסק אחד יכולים להיות כמה עיצובים בשמות (מותגים) – למשל שני מותגים של אותו עוסק. העסק המשפטי אחד: שם העסק, מספר העוסק, הכתובת וכל מה שהוראות ניהול הפנקסים מחייבות מודפסים מפרטי העסק, זהים בכל עיצוב, וכל סוג מסמך ממוספר בסדרה אחת משותפת לכל העיצובים. העיצוב משנה רק מראה: לוגו, צבע הדגשה, תבנית (classic, modern, minimal) ושורת תחתית – כללית, ומנוע 0.15 גם לכל סוג מסמך (footerByType).

• לכל עסק יש תמיד בדיוק עיצוב ברירת מחדל אחד (נאכף גם בבסיס הנתונים). עסק חדש מקבל עיצוב ראשון בשם העסק.
• כל שינוי בעיצוב נשמר כגרסה חדשה שלא משתנה. כל מסמך שומר את העיצוב ואת הגרסה שהיו בתוקף כשהופק, ולכן המקור, כל העתק וכל תצוגה שלו נראים תמיד כמו ביום ההפקה – גם אחרי שהעיצוב השתנה או הועבר לארכיון.
• עיצוב לא נמחק (מסמכים מפנים אליו). אפשר להעביר אותו לארכיון: אז אי אפשר להפיק בו מסמכים חדשים או לשנות אותו. את עיצוב ברירת המחדל אי אפשר להעביר לארכיון (קובעים קודם ברירת מחדל אחרת).
• מזהה עיצוב: dsg_ ו-20 תווים הקסדצימליים. השם (1–60 תווים, ייחודי בעסק) פנימי ולא מודפס.

logo: data URL (או base64) של PNG או JPEG, עד 300KB. accentColor בפורמט #RRGGBB; footerText עד 300 תווים.

שורת תחתית לפי סוג מסמך (מנוע 0.15): footerByType הוא אובייקט מקוד סוג המסמך לטקסט (עד 300 תווים לכל סוג), למשל { "400": "תודה על התשלום!", "305": "תנאי תשלום: שוטף+30" }. מה מודפס על מסמך: השורה של הסוג שלו, אחרת footerText של העיצוב, ואחרת כלום. טקסט ריק = בלי שורה משלו (נשמט). ב-PUT שולחים את האובייקט כולו, והוא מחליף את הקודם; בלי השדה הוא נשאר כמו בגרסה הנוכחית (גם בנתיב הישן PUT /v1/businesses/:id/design). הטקסט נשמר עם גרסת העיצוב, ולכן העתק של מסמך ישן מדפיס תמיד את הטקסט שהיה בתוקף כשהופק. קוד סוג לא מוכר או טקסט ארוך: 422. השורה התחתונה שהחוק מחייב (במסמך אמיתי "הופק על ידי העסק", אחרת שם התוכנה ומספר הרישום) נפרדת ולא משתנה. מפתח API וטוקן שירות לא יוצרים ולא משנים עיצובים (403), אבל בוחרים עיצוב בהפקה (designId) – זו לא הגדרה של העסק. שגיאות אימות (שם תפוס או ארוך, לוגו לא תקין, עיצוב בארכיון, ארכיון של ברירת המחדל) הן 422 עם הודעה בעברית; מזהה לא מוכר בנתיב הוא 404.

הפקה בעיצוב: designId אופציונלי ב-POST /v1/businesses/:id/documents (גם עם dryRun). בלעדיו – עיצוב ברירת המחדל. עיצוב לא מוכר, של עסק אחר או בארכיון: 422, ושום מספר לא מנוצל. התשובה, GET /v1/documents/:docId ותוצאת dryRun כוללות designId ו-designName; ברשימת המסמכים design_id ו-design_name. מסמך שהופק לפני 0.13 מוצג עם העיצוב הראשון של העסק (שבו הופק). ב-webhooks נוסף designId לאובייקט document (בלי השם).

דוגמה – רשימת העיצובים, ואז הפקה במותג השני:

curl -s https://<engine>/v1/businesses/$BIZ/designs -H "Authorization: Bearer $TOKEN"

{
  "designs": [
    { "id": "dsg_3f9c0a7e1b2d4c5e6f70", "name": "חוויה בקליק", "isDefault": true, "archived": false, "archivedAt": null,
      "createdAt": "2026-10-01T08:00:00.000Z", "version": 12, "versions": 3, "template": "classic", "accentColor": "#1a4a8c",
      "footerText": "", "hasLogo": true, "logoType": "png", "logoBytes": 18234 },
    { "id": "dsg_8a1b2c3d4e5f60718293", "name": "מדיה בקליק", "isDefault": false, "archived": false, "archivedAt": null,
      "createdAt": "2026-10-20T08:00:00.000Z", "version": 15, "versions": 1, "template": "modern", "accentColor": "#6a1b9a",
      "footerText": "תודה!", "hasLogo": false, "logoType": null, "logoBytes": 0 }
  ],
  "defaultDesignId": "dsg_3f9c0a7e1b2d4c5e6f70"
}

curl -s -X POST https://<engine>/v1/businesses/$BIZ/documents -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "docType": 305, "designId": "dsg_8a1b2c3d4e5f60718293",
        "customer": { "name": "עיריית רמלה", "vatNumber": "513746776" },
        "lines": [{ "description": "יום הפעלות", "quantity": 1, "unitPrice": 300000 }] }'

{ "id": 431, "docType": 305, "docNumber": 60012, "designId": "dsg_8a1b2c3d4e5f60718293", "designName": "מדיה בקליק", "...": "..." }

המסמך הבא, בכל עיצוב, יקבל את המספר 60013: הסדרה משותפת.

הנתיבים מלפני 0.13 (עיצוב ברירת המחדל)

ממשיכים לעבוד, על עיצוב ברירת המחדל של העסק:

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

כרטיסי לקוח ופריטים

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

• מזהים: כרטיס לקוח cus_ ופריט itm_, ואחריהם 20 תווים הקסדצימליים. באתר: בראש כל כרטיס ("מזהה API"), עם כפתור העתקה.
• externalId: המזהה במערכת אחרת (למשל מספר הלקוח ב-CRM), עד 100 תווים, ייחודי בעסק כשקיים (כפילות: 409). מחפשים לפיו ב-GET /v1/businesses/:id/customers/external/:externalId, ומפיקים לפיו ב-customerExternalId.
• הרשאות: צפייה – כל מי שיש לו גישת צפייה (גם רואה חשבון ומפתח API). יצירה, עריכה, ארכיון, ייבוא ומחיקה – מי שמפיק מסמכים: בעל העסק, עובד, מפתח API של העסק, טוקן שירות ומנהל. רואה חשבון מקבל 403.
• ארכיון: כרטיס או פריט בארכיון לא מופיעים ברשימה הרגילה, ואי אפשר להפיק להם מסמך (422). המסמכים שכבר מקושרים נשארים מקושרים. מחיקה רק לכרטיס שאף מסמך לא מקושר אליו (ולפריט שאף שורה לא הופקה ממנו); אחרת 409.
• אירועים: יצירה ועדכון של כרטיס או פריט לא נכנסים ליומן האירועים של העסק ולא נשלחים ב-webhooks. היומן וה-webhooks מתעדים רק פעולות על מסמכים.

כרטיס לקוח

התשובה: כל השדות, ועוד id, businessId, archived, archivedAt, createdAt, updatedAt. שדה לא מוכר בגוף הבקשה נדחה ב-422 (כדי ששגיאת כתיב לא תיבלע בשקט).

curl -s -X POST https://<engine>/v1/businesses/$BIZ/customers -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "name": "עיריית רמלה", "vatNumber": "513746776", "email": "office@ramla.example", "city": "רמלה",
        "paymentTermsDays": 30, "externalId": "crm-77", "tags": ["רשויות"], "customFields": { "ענף": "חינוך" } }'

{ "id": "cus_5c1f0e9a7b3d2c4e6f80", "businessId": "...", "name": "עיריית רמלה", "vatNumber": "513746776",
  "externalId": "crm-77", "tags": ["רשויות"], "customFields": { "ענף": "חינוך" }, "archived": false, "...": "..." }

פריט (מחירון)

אין לפריט סימון "פטור ממע"מ": המנוע מחשב שיעור מע"מ אחד לכל המסמך, לפי סוג המסמך וסוג העסק.

הפקה עם כרטיס ופריט

ב-POST /v1/businesses/:id/documents (גם עם dryRun):

• customerId (או customerExternalId): המנוע ממלא את פרטי הלקוח במסמך מהכרטיס – שם, ח"פ, כתובת (ברחוב), עיר, מיקוד, קוד ארץ, טלפון (ובלעדיו הנייד) ואימייל. customer לא חובה; כל שדה שנשלח ב-customer גובר על הכרטיס (גם ערך ריק). customer.key לא נלקח מהכרטיס. המסמך מקושר לכרטיס: customerId בתשובה, ב-GET /v1/documents/:docId, ב-customer_id ברשימת המסמכים, וב-GET /v1/businesses/:id/documents?customerId=cus_.... כרטיס של עסק אחר, שלא קיים או שבארכיון: 422, ושום מספר לא מנוצל.
• בלי customerId ההפקה עובדת בדיוק כמו קודם (חובה customer עם name), והמסמך לא מקושר לכרטיס. אין קישור אוטומטי לפי ח"פ; מקשרים אחר כך בייבוא מהמסמכים.
• itemId (או itemSku) בשורה: התיאור (שם הפריט), המחיר, המק"ט והיחידה מתמלאים מהפריט, אלא אם נשלחו בשורה. description ו-unitPrice לא חובה בשורה כזו. מחיר הפריט מותאם ל-pricesIncludeVat של המסמך: פריט שמחירו כולל מע"מ במסמך שמחיריו לפני מע"מ – מפורק לפי שיעור המע"מ של המסמך, ולהפך – מתווסף מע"מ (במסמך בלי מע"מ המחיר נשאר כמו שהוא). השורה שומרת את הערכים עצמם; ב-GET /v1/documents/:docId לכל שורה גם itemId.

{ "docType": 305, "customerId": "cus_5c1f0e9a7b3d2c4e6f80", "customer": { "email": "billing@ramla.example" },
  "lines": [{ "itemId": "itm_0a9b8c7d6e5f40312233", "quantity": 2 }, { "itemSku": "ACT-1", "quantity": 1, "unitPrice": 120000 }] }

הקישורים נשמרים בטבלאות נפרדות (document_customers, document_line_items) שאפשר רק להוסיף להן, מחוץ ל-hash ובלי לגעת בשורת המסמך, שנשארת חסומה לשינוי.

ייבוא הלקוחות מהמסמכים הקיימים

POST /v1/businesses/:id/customers/import-from-documents עם { "dryRun": true } (או גוף ריק להרצה) → { dryRun, documentsScanned, customersFound, customersCreated, customersMatched, documentsLinked }.

• עובר על כל מסמכי העסק שעוד לא מקושרים לכרטיס, ומקבץ אותם לפי ח"פ הלקוח; בלי ח"פ – לפי שם ואימייל (בלי הבדלי רווחים ואותיות גדולות).
• לקוח שכבר יש לו כרטיס (אותו ח"פ; בלי ח"פ – כרטיס בלי ח"פ עם אותו שם ואימייל) מקושר לכרטיס הקיים. אחרת נוצר כרטיס מהפרטים של המסמך האחרון שלו.
• המסמכים לא משתנים: לכל מסמך נוספת רק שורה ב-document_customers (source: backfill). ה-hash והשרשרת לא משתנים.
• אפשר להריץ שוב בכל עת: רק מסמכים חדשים בלי כרטיס נספרים. dryRun: true רק סופר.

מפתחות API (בעל העסק או מנהל)

מפתח החתימה וקוד החתימה (מנוע 0.18)

חוזר מס הכנסה 24/2004 מגדיר "חתימה אלקטרונית מאובטחת" לפי חוק חתימה אלקטרונית, ואחד התנאים הוא שאמצעי החתימה בשליטתו הבלעדית של בעל החתימה – כאן העסק. עד מנוע 0.17 המפתח הפרטי של כל עסק הוצפן בסיסמה אחת של השרת (SIGNING_KEY_PASSPHRASE / Vault invoice_engine_signing_passphrase), ולכן מפעיל השרת יכול היה לחתום בשם כל עסק. ממנוע 0.18 (מיגרציה 019) בעל העסק יכול לקבוע קוד חתימה, והמפתח נעול בו.

ברירת המחדל: חתימה אוטומטית. בלי קוד, מפתח החתימה של העסק שמור בשרת (מוצפן בסיסמת המערכת), protection: "platform", והכל עובד אוטומטית: האתר, כל מפתח API וכל טוקן (גם חיבור MCP) שמפיקים בעסק מקבלים מקור ממוחשב חתום, בלי קוד ובלי האצלות. האתר לא מציג על כך אזהרה ולא מבקש לקבוע קוד. קוד החתימה הוא אפשרות מתקדמת (הגדרות ← חתימה ← מתקדם) לבעל עסק שרוצה שליטה בלעדית, ומי שבחר בה יכול תמיד לחזור לחתימה אוטומטית (DELETE .../signing/pin, למטה).

עם קוד חתימה:

• הקוד: 8 תווים לפחות, לא סיסמת החשבון, בלי רווח בקצוות, לפחות 4 תווים שונים. באתר ברירת המחדל היא קוד אקראי שהדפדפן יוצר (20 תווים, XXXX-XXXX-XXXX-XXXX-XXXX, כ-99 ביט), שמוצג פעם אחת ואפשר לזכור אותו בדפדפן.
• ההצפנה: PBKDF2-SHA256 עם 600,000 סבבים ומלח אקראי של 16 בתים לכל מפתח, ומהתוצאה מפתח AES-256-GCM; ההקשר (העסק וטביעת התעודה) הוא חלק מהנתונים המאומתים. הקוד לא נשמר בשום מקום, וגם לא שום דבר שפותח את המפתח בלעדיו.
• בקביעה הראשונה המפתח נפתח פעם אחרונה בסיסמת המערכת, נעטף בקוד, העטיפה נבדקת (נפתחת בקוד ומתאימה לתעודה), ורק אז העותק בסיסמת המערכת נמחק – מכל המפתחות של העסק, גם מפתחות קודמים, כדי שאי אפשר יהיה לחתום בהם בדיעבד.
• התעודה והמפתח הציבורי לא משתנים: כל מקור שכבר נחתם נשאר תקף ומאומת באותה תעודה.
• עסק שלא קבע קוד עובד בחתימה אוטומטית (protection: "platform"), כמו שתואר למעלה.
• הקוד לא נרשם ביומן השרת (הוא בגוף הבקשה, שלא נרשם) ולא חוזר בשום תשובה.
• ניסיונות כושלים: כמו בכניסה – אחרי 5 קודים שגויים החתימה של העסק נחסמת לרבע שעה (429, signingError: "pin_locked").
• חזרה לחתימה אוטומטית (מיגרציה 023): DELETE /v1/businesses/:id/signing/pin עם הקוד הנוכחי. כל מפתח של העסק שנעול בקוד הזה נעטף שוב בסיסמת המערכת (העותק נבדק לפני שהעטיפה בקוד נמחקת), pin_set_at ו-legacy_destroyed_at מתנקים, כל ההאצלות של העסק נמחקות (כל אחת נרשמת כ-delegation_revoked עם reason: "pin_removed"), ונרשם pin_removed – הכל בטרנזקציה אחת. המפתח והתעודה לא משתנים. הקוד נבדק עם אותה ספירת ניסיונות כושלים כמו בחתימה. מפתח ישן שנעול בקוד אחר (קודם) נשאר כמו שהוא: הוא כבר לא חותם, והתעודה שלו ממשיכה לאמת מסמכים ישנים. השומר של שורות המפתחות (מיגרציה 023) מתיר לכתוב שוב את העותק בסיסמת המערכת רק באותו עדכון שמוחק את העטיפה בקוד, ולמחוק את העטיפה בקוד רק כשנכתב עותק – למפתח תמיד נשארת עטיפה אחת שנפתחת.
• שכחתם את הקוד: אי אפשר לשחזר אותו – גם לא מפעיל המערכת. יוצרים מפתח ותעודה חדשים בחתימה אוטומטית (POST /v1/businesses/:id/signing-keys בלי pin; בעסק שיש לו קוד – רק בעל העסק, עם currentPassword). המקורות הקודמים נשארים תקפים בתעודה הקודמת; ההאצלות של המפתח הקודם נמחקות, והמפתח הקודם נשאר כמו שהוא. אפשר גם ליצור מפתח חדש עם קוד חדש (pin) – למשל כשמדיניות המערכת דורשת קוד.

יומן אירועי החתימה (events, טבלה שאפשר רק להוסיף לה): pin_set, pin_changed, legacy_destroyed, delegation_created, delegation_revoked, key_rotated, pin_locked, policy_changed, pin_removed (מיגרציה 023: חזרה לחתימה אוטומטית) – מי ומתי, בלי הקוד.

שגיאות חתימה (signingError בגוף התשובה): pin_required (422: חסר קוד ואין האצלה), pin_invalid (403: קוד שגוי), pin_locked (429), pin_rejected (422: קוד חדש לא תקין), policy_requires_pin (422; בחזרה לחתימה אוטומטית 409), pin_not_set (409: לעסק אין קוד), no_signing_key (422).

האצלת חתימה (API ו-MCP)

נחוץ רק בעסק שבחר בקוד חתימה (בחתימה אוטומטית כל מפתח וטוקן חותמים בלי האצלה). מערכת אוטומטית (CRM, סקריפט, חיבור Claude) שצריכה להפיק מקורות ממוחשבים בלי שיקלידו קוד: בעל העסק מאציל חתימה למפתח API של העסק או לטוקן גישה אישי (iep_, גם הטוקן של חיבור MCP). המפתח הפרטי נעטף עוד פעם במפתח שנגזר (HKDF-SHA256, מלח אקראי) מהסוד המלא של המפתח או הטוקן. הסוד מוצג פעם אחת ונשמר במנוע רק כ-SHA-256, ולכן השרת לבדו לא פותח את העטיפה: רק בקשה שמגיעה עם הסוד עצמו. בבקשה כזו המנוע גוזר את המפתח, פותח בזיכרון, חותם ושוכח.

• ביטול המפתח או הטוקן (או שינוי הסיסמה של בעל הטוקן, שמבטל את כל הטוקנים שלו) מוחק גם את ההאצלה.
• החלפת מפתח מוחקת את ההאצלות של המפתח הקודם; יוצרים אותן מחדש. חזרה לחתימה אוטומטית מוחקת את כל ההאצלות של העסק (אין בהן צורך יותר).
• חיבור Claude (MCP): הטוקן של חיבור נשמר מוצפן בשרת של האתר, ולכן ההאצלה עוברת דרכו (POST /api/oauth/connections/:id/signing-delegation באתר). שימו לב: כך גם השרת של האתר יכול לחתום בשם העסק כל עוד החיבור פעיל – זו כבר לא שליטה בלעדית מלאה. בלי האצלה, produce_original ב-MCP מחזיר הודעה בעברית עם קישור לחתימה באתר, והקוד לא עובר דרך Claude.

מסמכים

הפקה

POST /v1/businesses/:id/documents

{
  "docType": 320,
  "operator": "tami",
  "customer": { "key": "crm-1234", "name": "משפחת כהן", "vatNumber": "", "city": "ירושלים", "email": "..." },
  "lines": [{ "description": "הפעלה בקליקרים", "quantity": 1, "unitPrice": 90000 }],
  "pricesIncludeVat": true,
  "payments": [{ "method": 4, "amount": 90000, "paymentDate": "2026-09-22" }],
  "notes": "תודה!"
}

סוגי המסמכים (הקודים לפי נספח 1 למבנה האחיד, חוץ מהצעת מחיר):

סוג שנוסף אחרי שהעסק נרשם צריך סדרה: POST /v1/businesses/:id/sequences (בעל העסק), פעם אחת. עד המסמך הראשון מהסוג הזה אפשר להעלות את המספר הבא ב-PUT /v1/businesses/:id/sequences/:docType.

designId (אופציונלי, מנוע 0.13): העיצוב שבו המסמך יופק, מ-GET /v1/businesses/:id/designs; בלעדיו – עיצוב ברירת המחדל. ראו עיצובים ומותגים.

shareLink (אופציונלי, מנוע 0.15): true, או { "expiresInDays": 30 } – יוצר באותה הפקה גם קישור שיתוף למסמך. הקישור מוחזר ב-shareLink של התשובה ({ id, token, path, url, expiresAt, ... }, פעם אחת) ובגוף ההודעה של document.issued ב-webhooks. ערך אחר: 400, ושום מספר לא מנוצל. לא בבדיקה (dryRun) ולא בתצוגה מקדימה.

customerId / customerExternalId ו-itemId / itemSku בשורה (אופציונליים, מנוע 0.16): פרטי הלקוח והשורות מתמלאים מכרטיס הלקוח ומהמחירון, ומה שנשלח בבקשה גובר. ראו הפקה עם כרטיס ופריט.

התשובה היא 201 עם { id, docNumber, amountNet, vatAmount, amountTotal, requiresManualSignature, designId, designName, customerId, allocation: { required, reason }, shareLink?, warnings?, ... }.

בדיקה בלי הפקה (dryRun)

אותה קריאה עם "dryRun": true (ובאותה הרשאה, הפקה) בודקת ומחשבת את המסמך בדיוק כמו הפקה אמיתית: אותה פונקציה, אותן בדיקות, אותם סכומים ומע"מ, המספר הבא בסדרה וחובת מספר ההקצאה. המנוע אף כותב את המסמך בתוך טרנזקציה, ובסוף מבטל אותה. שום דבר לא נשמר: אין מסמך, אין אירוע ביומן, המונה של הסדרה לא מתקדם ושרשרת ה-hash לא משתנה.

{ "docType": 320, "customer": { "name": "משפחת כהן" }, "lines": [...], "payments": [...], "dryRun": true }

התשובה היא 200 עם המסמך כפי שהיה מופק (אותם שדות כמו GET /v1/documents/:docId: עסק, לקוח, שורות, תשלומים, סכומים), ועוד allocation, "dryRun": true ו-note. id ו-contentHash הם null, כי שום דבר לא נשמר. docNumber זמני: זה המספר שהמסמך יקבל אם יופק עכשיו, אלא אם יופק לפניו מסמך אחר באותה סדרה. בקשה לא תקינה נדחית בדיוק כמו בהפקה (422 עם אותה הודעה). dryRun חייב להיות true או false; ערך אחר (למשל "true" כמחרוזת) נדחה ב-400, כדי שלא יופק בטעות מסמך אמיתי.

המזהה הפנימי (id) של המסמך הבא אחרי בדיקה עשוי לדלג, כי מונה המזהים של Postgres לא חוזר אחורה בביטול טרנזקציה. זה לא מספר המסמך: docNumber נשאר רציף בלי פערים.

תצוגה מקדימה כ-PDF

POST /v1/businesses/:id/documents/preview (מנוע 0.15) מקבל אותו גוף כמו ההפקה (כולל designId), באותה הרשאה (מי שמפיק – גם מפתח API; רואה חשבון: 403), ומחזיר application/pdf: המסמך בדיוק כפי שיופק – אותו ציור, העיצוב שנבחר, שורת התחתית של סוג המסמך והשורות – ועליו סימן מים באלכסון "תצוגה מקדימה – אינו מסמך", "יוקצה בהפקה" במקום המספר, סימון "טיוטה" (פלט מקובץ זמני, נספח ה'(א)) במקום מקור או העתק, ובלי טביעת המסמך. הבדיקה היא אותה בדיקה בלי הפקה (dryRun), ולכן בקשה לא תקינה נכשלת בדיוק באותן שגיאות כמו ההפקה (אותו קוד ואותה הודעה). שום דבר לא נשמר: לא מספר ולא מונה הסדרה, לא אירוע ביומן, לא משלוח webhook, לא שרשרת ה-hash, לא העתק ביומן ולא קישור שיתוף (shareLink מתעלמים ממנו כאן). בעסק במצב מסמכים אמיתיים התצוגה מסומנת בכל זאת, והשורה התחתונה היא "הופק על ידי העסק", כמו במסמך שיופק. התשובה עם Cache-Control: no-store.

חשבונית זיכוי

{
  "docType": 330,
  "customer": { "key": "crm-1234", "name": "עיריית רמלה", "vatNumber": "513746776" },
  "lines": [{ "description": "ביטול חלק מההפעלה", "quantity": 1, "unitPrice": 100000 }],
  "base": { "docType": 305, "docNumber": 60012 },
  "creditReason": "ההפעלה קוצרה בשעה"
}

הזיכוי חייב להיות לאותו לקוח של החשבונית, ועד היתרה שלה. כמה כבר זוכה רואים ב-creditedNet של החשבונית (GET /v1/documents/:docId) או ב-credited_net ברשימת המסמכים. אין מחיקה ואין ביטול: כל תיקון הוא מסמך חדש.

קבלה על חשבונית

{
  "docType": 400,
  "customer": { "key": "crm-1234", "name": "עיריית רמלה", "vatNumber": "513746776" },
  "payments": [{ "method": 4, "amount": 354000, "paymentDate": "2026-10-15" }],
  "base": { "docType": 305, "docNumber": 60012 }
}

• כש-allocation.required אמת, צריך לבקש מספר הקצאה מרשות המסים ולרשום אותו לפני הפקת המקור.
• כש-requiresManualSignature אמת (למשל במזומן), אי אפשר להפיק מקור ממוחשב. מפיקים מקור להדפסה וחותמים עליו ביד.

שאר הקריאות

יומן האירועים של העסק

GET /v1/businesses/:id/events?after=<מזהה>&limit=<1..500> (צפייה) מחזיר את כל האירועים של מסמכי העסק – הפקה, מספר הקצאה, מקור, העתקים – לפי סדר המזהה, מהישן לחדש. מיועד לחיבור חיצוני שבודק מה חדש מאז הפעם הקודמת:

{
  "events": [
    { "id": 812, "documentId": 431, "docType": 305, "docNumber": 60012, "event": "issued",
      "at": "2026-10-15T09:12:44.000Z", "actor": "nissim@example.com (token Claude)", "details": { "contentHash": "..." } }
  ],
  "next": 812
}

• מנוע 0.19: event – רק סוג אחד (issued, original_produced, copy_produced, allocation_recorded, ...); order=desc – העמוד מהחדש לישן (עדיין רק מזהים גדולים מ-after), ואז next הוא המזהה הגדול ביותר בעמוד. לסקירה בתדירות של Zapier ו-Make.
• after (ברירת מחדל 0): מחזיר רק אירועים שהמזהה שלהם גדול ממנו. limit ברירת מחדל 100, עד 500. ערך לא תקין: 400.
• next הוא המזהה של האירוע האחרון בעמוד, או after עצמו כשאין חדשים. שולחים אותו כ-after בקריאה הבאה.
• id, documentId, docType ו-docNumber הם תמיד מספרים (JSON number). at בפורמט ISO 8601 ב-UTC.
• רק מסמכים של העסק שבנתיב. מפתח API רואה רק את העסק שלו, ומשתמש רק עסק שהוא שייך אליו.
• בכל עסק המזהים נקבעים לפי סדר השמירה: כתיבות ליומן של אותו עסק ממתינות זו לזו עד סוף הטרנזקציה. לכן כשאירוע מופיע, כל האירועים הקודמים של העסק כבר מופיעים, וחיבור שמתקדם לפי next לא מפספס אף אירוע, גם כשכמה פעולות רצות במקביל.
• המזהים לא רציפים: יש ביניהם אירועים של עסקים אחרים ומזהים של בדיקות בלי הפקה (dryRun) שבוטלו.

קישורי שיתוף

מנוע 0.15: קישור קבוע וחתום למסמך אחד, שכל מי שמחזיק בו פותח בלי להתחבר – למשל כדי לשלוח ללקוח בוואטסאפ או במייל. הקישור הוא כתובת באתר, <האתר>/s/<token>. הטוקן אקראי (24 בתים, 32 תווי base64url), מוחזר פעם אחת ביצירה, ובבסיס הנתונים נשמר רק ה-SHA-256 שלו (מיגרציה 016). אי אפשר להציג שוב קישור קיים: יוצרים חדש ומבטלים את הישן.

url היא הכתובת המלאה כשהמנוע יודע את כתובת האתר (ENGINE_SHARE_BASE_URL בשרת; ב-Edge Function – כתובת האתר של הפרויקט), ואחרת null, ואז path (/s/<token>) מצטרף לכתובת האתר.

מה מוגש: המקור הממוחשב החתום – רק כשהכללים של המנוע כבר מתירים לתת אותו ללקוח: הוא הופק (POST /v1/documents/:docId/original עם computerized: true, אחרי הודעה לפקיד השומה, הסכמת הלקוח ואמצעי תשלום מותר), וההחלטה האחרונה של הלקוח היא עדיין הסכמה (הוראה 18ב(ג); בהצעת מחיר אין צורך בהסכמה). בכל מקרה אחר – העתק מסומן "העתק", שנרשם ביומן המסמך כמו כל העתק (copy_produced, בשם share-link:<id>, וגם ב-webhooks). הקישור לא מפיק מקור ולא עוקף שום כלל; מקור להדפסה לא נשלח בקישור.

פרטיות ואבטחה: הנתיבים הציבוריים עונים עם Cache-Control: no-store, X-Robots-Tag: noindex ו-Referrer-Policy: no-referrer. טוקן לא מוכר: 404; קישור שבוטל או פג: 410 (אותה הודעה). מגבלת קצב לכל קישור ולכל רשת של לקוח (429). ביומן הפתיחות לא נשמרת כתובת ה-IP: רק client, טביעה מקוצרת (16 תווים) של הרשת (IPv4 /24, IPv6 /48) יחד עם מזהה הקישור, שאי אפשר להחזיר ממנה את הכתובת או לקשר בין קישורים. הטוקן לא נכתב ליומן השרת. קישור לא נמחק ולא משתנה בבסיס הנתונים, חוץ מהביטול; הקישורים (בלי הטוקנים) נכללים בייצוא המלא (share-links.csv).

הפקה עם קישור: "shareLink": true (או { "expiresInDays": 30 }) ב-POST /v1/businesses/:id/documents יוצר את הקישור באותה טרנזקציה של ההפקה. הכתובת נכנסת לגוף ההודעה של document.issued (data.shareLink), אבל לא ליומן האירועים הקבוע. שימו לב: גוף ההודעה נשמר בהיסטוריית המשלוחים עד 30 יום, וכל מי שמנהל את ה-webhooks של העסק רואה אותו.

Webhooks

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

• standard – כתובת https של המערכת שלכם (CRM, הנהלת חשבונות וכו'). כל הודעה נשלחת ב-POST וחתומה לפי Standard Webhooks, בסוד חתימה (whsec_...) שמוצג פעם אחת ביצירה.
• claude_routine – routine של Claude Code (claude.ai/code/routines) עם טריגר API. המנוע עצמו מפעיל אותו, בכתובת הקבועה https://api.anthropic.com/v1/claude_code/routines/<trig_...>/fire, עם הטוקן של ה-routine (sk-ant-oat01-...). הטוקן נשמר מוצפן, לא מוצג שוב ולא יוצא מהמנוע (גם לא למשגר).

סוגי האירועים (אירוע אחד ביומן = הודעה אחת):

קריאה ל-/copy יוצרת document.copy_produced. כדי להוריד PDF בתגובה ל-webhook השתמשו ב-/original (אחרי הפעם הראשונה בלי אירוע) או בנתוני ה-JSON, אחרת כל הורדה תיצור הודעה חדשה. לכן document.copy_produced לא נבחר כברירת מחדל, routine של Claude לא יכול לקבל אותו, ולאותו webhook ואותו מסמך נשלחת לכל היותר הודעת העתק אחת בכל 10 דקות.

הרשאות

רק בעל העסק (וטוקן המנהל, בחלק מהפעולות). עובד, רואה חשבון, מפתח API וטוקן שירות מקבלים 403. חריג אחד (מנוע 0.19): מינויי Zapier ו-Make, במפתח API או בטוקן גישה, רק לכתובות של הפלטפורמות.

• T – בעל העסק בכניסה עם סיסמה (ies_) או בטוקן גישה אישי (iep_), או טוקן המנהל.
• O – בעל העסק בכניסה עם סיסמה בלבד.
• S – O, ועוד אימות מחדש בגוף הבקשה: currentPassword, ו-code כשיש אימות דו-שלבי (כמו ביצירת טוקן גישה). סיסמה שגויה: 401 (ונספרת לחסימה); בלי קוד: 401 עם twoFactorRequired: true. קלט שגוי נבדק קודם ומחזיר 422 בלי להיספר.

webhook ממשיך לשלוח נתונים גם אחרי שטוקן בוטל או שסיסמה הוחלפה, ולכן יצירה, הפעלה מחדש, הוספת אירועים, שינוי כתובת או טוקן, החלפת סוד והצגת הכתובת המלאה הם S. בעל העסק שביצע פעולת S אחרונה הוא האחראי ל-webhook; כשהוא מוסר מהעסק או מפסיק להיות בעל העסק, ה-webhook מושבת מיד (creator_removed), ובעל עסק אחר צריך לבדוק אותו ולהפעיל מחדש.

ההרשאה נבדקת שוב בתוך הטרנזקציה של השינוי: משתמש שהוסר מהעסק (או שכבר אינו בעל העסק) בזמן שהבקשה שלו רצה מקבל 403, גם אם הבדיקה בתחילת הבקשה עברה. PATCH מחליט אם הוא S לפי מצב ה-webhook בתחילת הבקשה; אם בינתיים ה-webhook הושבת או צומצם, כך שהשינוי הפך להפעלה מחדש או להוספת אירוע, והבקשה לא כללה כניסה עם סיסמה ואימות מחדש, התשובה היא 409 (ה-webhook השתנה בינתיים...) ושום דבר לא משתנה. שולחים שוב, והפעם נדרש S.

התשובות של היצירה, reveal-url ו-rotate-secret נשלחות עם Cache-Control: no-store.

נקודת קצה (WebhookEndpointInfo):

{
  "id": "7d0e5b8a-3c2f-4e1d-9b6a-0f1e2d3c4b5a", "businessId": "5f0c3c1e-...", "kind": "standard",
  "url": "https://api.my-crm.com/webhooks/…?token=***", "urlHasQuery": true, "urlMasked": true, "routineId": null,
  "description": "CRM", "eventTypes": ["document.issued", "document.original_produced", "document.allocation_recorded"],
  "secretHint": "…Hh8=", "previousSecretExpiresAt": null,
  "enabled": true, "disabledReason": null, "disabledAt": null,
  "consecutiveFailures": 0, "failingSince": null, "lastSuccessAt": "2026-10-15T09:12:45.120Z", "lastFailureAt": null, "holdUntil": null,
  "createdAt": "...", "createdBy": "nissim@example.com", "updatedAt": "...", "stats": { "pending": 0, "failed24h": 0 }
}

• הכתובת מוצגת תמיד מקוצרת, כי הנתיב והפרמטרים כוללים לפעמים סיסמה של המערכת המקבלת (Slack, Discord, Zapier ו-Make שמים אותה בנתיב): רק הקטע הראשון בנתיב, וגם הוא רק כשהוא מילה (עד 24 תווים, לכל היותר 2 ספרות), ואחריו …; בפרמטרים name=*** כשהשם מילה, ו-*** לכל חלק אחר. למשל https://hooks.slack.com/services/T0/B0/XXXX מוצג https://hooks.slack.com/services/…, ו-https://hook.eu1.make.com/<טוקן> מוצג https://hook.eu1.make.com/…. urlMasked: true כשחלק מהכתובת מוסתר. הכתובת המלאה רק ב-reveal-url. גם בהיסטוריית השינויים הכתובת מקוצרת כך. ב-routine של Claude הכתובת קבועה ונגזרת מהמזהה, ולכן מוצגת במלואה.
• routineId ב-routine: אפשר להדביק את המזהה (trig_...) או את כתובת ה-API שמוצגת ב-claude.ai; המנוע לוקח ממנה את המזהה.
• עד 10 webhooks לעסק (כולל מושבתים), וכתובת אחת פעם אחת בלבד (routine – מזהה אחד פעם אחת).
• description עד 200 תווים, בלי תווי בקרה.

כללי הכתובת (standard)

https:// בלבד, בפורט הרגיל (443), לשם מתחם ולא לכתובת IP (בכל צורה), בלי שם משתמש וסיסמה, בלי #, עד 2,048 תווים. אסורים localhost ושמות פנימיים או שמורים: .local, .localdomain, .internal, .intranet, .lan, .home, .corp, .private, .arpa (כולל home.arpa), .test, .example, .invalid, .onion, ושם בלי נקודה. פרמטרים (?a=b) מותרים. הכתובת נשמרת מנורמלת (אותיות קטנות בשם המתחם, punycode, בלי :443). שם מתחם ציבורי שמפנה לכתובת פנימית (למשל 10.0.0.1.nip.io) נעצר ברמת הרשת, אצל המשגר: שרת ה-Node לא מתחבר לכתובות פרטיות, שמורות, loopback, link-local, CGNAT, multicast ו-IPv4 בתוך IPv6 (ועוד טווחים ב-ENGINE_WEBHOOK_BLOCK_CIDRS), ו-Cloudflare Workers לא מתחבר לרשתות פרטיות. האתר גם לא שולח לכתובות בדומיין שלו עצמו (למשל *.lovable.app); מקבל שמתארח שם משתמש בכתובת אחרת.

גוף ההודעה

JSON בלי רווחים, שנבנה פעם אחת כשהאירוע נכתב ונשלח בדיוק כך בכל ניסיון. רק מזהים, סוג, מספר, תאריך וסכומים (באגורות): בלי פרטי לקוח, בלי מי שביצע ובלי שם העסק. את שאר הפרטים קוראים ב-API, בהרשאות של המקבל (למשל GET /v1/documents/:docId עם data.document.id).

{
  "type":      "document.issued" | "document.original_produced" | "document.copy_produced" | "document.allocation_recorded" | "webhook.test",
  "timestamp": זמן האירוע (ISO 8601 UTC),
  "data": {
    "eventId":    המזהה ביומן האירועים (בלי ב-webhook.test),
    "businessId": "...",
    "document": { "id", "docType", "docTypeName", "docNumber", "documentDate", "currency", "amountNet", "vatAmount", "amountTotal",
                  "designId"?: (מנוע 0.13: מזהה העיצוב שבו הופק, בלי השם),
                  "baseDocument"?: { "docType", "docNumber" }, "allocationNumber"?: (רק ב-document.allocation_recorded) },
    "original"?: { "kind": "computerized" | "printed" },   (רק ב-document.original_produced)
    "shareLink"?: { "id", "url"?, "path", "expiresAt" },   (מנוע 0.15, רק ב-document.issued שהופק עם shareLink)
    "endpointId"?, "message"?                                (רק ב-webhook.test)
  }
}

{"type":"document.issued","timestamp":"2026-10-15T09:12:44.000Z","data":{"eventId":812,"businessId":"5f0c3c1e-8a4b-4c47-9a39-2f7d2b6f1a10","document":{"id":431,"docType":305,"docTypeName":"חשבונית מס","docNumber":60012,"documentDate":"2026-10-15","currency":"ILS","amountNet":300000,"vatAmount":54000,"amountTotal":354000}}}

{"type":"document.original_produced","timestamp":"2026-10-15T09:13:02.517Z","data":{"eventId":813,"businessId":"5f0c3c1e-8a4b-4c47-9a39-2f7d2b6f1a10","document":{"id":431,"docType":305,"docTypeName":"חשבונית מס","docNumber":60012,"documentDate":"2026-10-15","currency":"ILS","amountNet":300000,"vatAmount":54000,"amountTotal":354000},"original":{"kind":"computerized"}}}

{"type":"document.copy_produced","timestamp":"2026-10-16T07:40:11.204Z","data":{"eventId":820,"businessId":"5f0c3c1e-8a4b-4c47-9a39-2f7d2b6f1a10","document":{"id":433,"docType":400,"docTypeName":"קבלה","docNumber":70031,"documentDate":"2026-10-16","currency":"ILS","amountNet":354000,"vatAmount":0,"amountTotal":354000,"baseDocument":{"docType":305,"docNumber":60012}}}}

{"type":"document.allocation_recorded","timestamp":"2026-10-15T09:20:00.000Z","data":{"eventId":815,"businessId":"5f0c3c1e-8a4b-4c47-9a39-2f7d2b6f1a10","document":{"id":431,"docType":305,"docTypeName":"חשבונית מס","docNumber":60012,"documentDate":"2026-10-15","currency":"ILS","amountNet":300000,"vatAmount":54000,"amountTotal":354000,"allocationNumber":"202610150001234"}}}

{"type":"webhook.test","timestamp":"2026-10-15T10:00:00.000Z","data":{"businessId":"5f0c3c1e-8a4b-4c47-9a39-2f7d2b6f1a10","endpointId":"7d0e5b8a-3c2f-4e1d-9b6a-0f1e2d3c4b5a","message":"הודעת בדיקה. אין מסמך חדש."}}

חתימה (standard)

כל בקשה נשלחת ב-POST עם הכותרות:

signature = base64(HMAC-SHA256(key = base64decode(הסוד בלי "whsec_"), message = "{webhook-id}.{webhook-timestamp}.{body}")), כש-body הוא הבתים של גוף הבקשה כמו שהתקבלו (לא JSON שפוענח ונבנה מחדש). דחו הודעה כש-webhook-timestamp רחוק מעכשיו ביותר מ-5 דקות. וקטור לבדיקה (הסוד הוא הבתים 0x00..0x1f):

secret    = whsec_AAECAwQFBgcICQoLDA0ODxAREhMUFRYXGBkaGxwdHh8=
webhook-id = msg_0123456789abcdef0123456789abcdef
webhook-timestamp = 1792055564
body      = הדוגמה של document.issued למעלה, בדיוק (333 בתים ב-UTF-8)
signature = v1,Vj1weAfat3Gnkclb/AS+L5gH7UB52TP/WeXEsvRcSuw=

בדיקה ב-Node.js (בלי תלויות):

import { createHmac, timingSafeEqual } from "node:crypto";

export function verifyWebhook(secret, headers, rawBody, nowSeconds = Date.now() / 1000) {
  const id = headers["webhook-id"], timestamp = headers["webhook-timestamp"], signatures = headers["webhook-signature"] ?? "";
  if (!id || !/^\d+$/.test(timestamp ?? "") || Math.abs(nowSeconds - Number(timestamp)) > 300) throw new Error("bad timestamp");
  const key = Buffer.from(secret.slice("whsec_".length), "base64");
  const expected = createHmac("sha256", key).update(`${id}.${timestamp}.${rawBody}`).digest();
  const valid = signatures.split(" ").some((entry) => {
    const [version, value] = entry.split(",");
    const given = Buffer.from(value ?? "", "base64");
    return version === "v1" && given.length === expected.length && timingSafeEqual(given, expected);
  });
  if (!valid) throw new Error("bad signature");
  return JSON.parse(rawBody);
}

בדיקה ב-Python (בלי תלויות; raw_body הם הבתים של הגוף, headers עם שמות באותיות קטנות או אובייקט כותרות שלא מבחין בין אותיות):

import base64, hashlib, hmac, json, time

def verify_webhook(secret, headers, raw_body, now=None):
    msg_id = headers.get("webhook-id")
    timestamp = headers.get("webhook-timestamp") or ""
    signatures = headers.get("webhook-signature") or ""
    now = time.time() if now is None else now
    if not msg_id or not timestamp.isdigit() or abs(now - int(timestamp)) > 300:
        raise ValueError("bad timestamp")
    key = base64.b64decode(secret[len("whsec_"):])
    signed = f"{msg_id}.{timestamp}.".encode() + raw_body
    expected = base64.b64encode(hmac.new(key, signed, hashlib.sha256).digest()).decode()
    for entry in signatures.split(" "):
        version, _, value = entry.partition(",")
        if version == "v1" and hmac.compare_digest(value, expected):
            return json.loads(raw_body)
    raise ValueError("bad signature")

אפשר גם להשתמש בספריות הרשמיות של Standard Webhooks (standardwebhooks, בכל שפה).

החלפת סוד (rotate-secret): הסוד החדש מוחזר פעם אחת. בלי previousSecretValidHours (ברירת מחדל 24) הסוד הקודם ממשיך לחתום במשך 24 שעות, וכל הודעה נושאת שתי חתימות, כדי שתספיקו לעדכן את המערכת המקבלת. כשהסוד דלף שולחים previousSecretValidHours: 0, והסוד הקודם מפסיק מיד. הסוד נשמר במנוע רק מוצפן (AES-256-GCM, במפתח שנגזר מסיסמת מפתחות החתימה של השרת).

מסירה

• לפחות פעם אחת (standard): אותה הודעה יכולה להגיע יותר מפעם אחת (למשל כשהתשובה שלכם אבדה בדרך). זהו כפילויות לפי webhook-id. אין הבטחה לסדר: השתמשו ב-data.eventId (עולה לפי סדר השמירה בעסק), או קראו את המצב ב-API.
• יומן האירועים הוא המקור המוסמך (GET /v1/businesses/:id/events): ההודעות נכתבות לתור באותה טרנזקציה של האירוע, אבל תקלה בתור לעולם לא מכשילה הפקה של מסמך (ואז ההודעה לא נוצרת). להתאמה מלאה, השוו מדי פעם מול היומן.
• זמן: בדרך כלל תוך שניות; לכל היותר כחצי דקה אחרי האירוע (בלי pg_cron 1.5 ומעלה: עד דקה), ויותר כשה-webhook בהשהיה של המפסק (בהמשך).
• תשובה: כל 2xx היא הצלחה. הגוף לא נקרא. הפניות (3xx) לא נעקבות ונחשבות כישלון. זמן קצוב: 10 שניות.

ניסיונות חוזרים (standard, עד 8 ניסיונות, כ-44 שעות). לכל השהיה תזוזה קבועה של ±10% לכל הודעה:

• 429 ו-503: לפי Retry-After (שניות או תאריך), לא פחות מההשהיה שבטבלה ולא יותר מ-24 שעות.
• 410: הכתובת לא קיימת עוד – ה-webhook מושבת (gone).
• מפסק: אחרי 3 כישלונות ברצף לא שולחים ל-webhook במשך 1, 5, 15, 30 דקות, ואחר כך שעה אחרי כל כישלון נוסף, ונשלחת רק הודעה אחת בכל פעם (בדיקה). הצלחה משחררת את כל מה שממתין (עד 5 בכל סבב).
• השבתה אוטומטית: אחרי 10 כישלונות ברצף שנמשכים 72 שעות לפחות (failing); 410 (gone); כתובת שמפנה לרשת פנימית (blocked_address) או שלא עוברת את בדיקת הכתובות של המשגר (invalid_url); סוד שאי אפשר לפענח (secret_unreadable); 1,000 הודעות שממתינות (backlog); האחראי כבר לא בעל העסק (creator_removed). כשהתוצאה מגיעה ממשגר חיצוני (Cloudflare Worker), 410 / כתובת חסומה / כתובת לא תקינה הן "פסילה": ההודעה נשלחת שוב, וה-webhook מושבת רק אחרי 3 פסילות במשך 10 דקות לפחות. הצלחה מאפסת אותן.
• השהיה מול השבתה: PATCH { enabled: false } היא השהיה (manual): הודעות שכבר המתינו בזמן ההשהיה נשמרות ונשלחות אחרי הפעלה מחדש (S). אירועים שקורים בזמן ההשהיה לא נכנסים לתור ולא יישלחו גם אחרי ההפעלה; מי שצריך אותם קורא את יומן האירועים (GET /v1/businesses/:id/events). בהשבתה אוטומטית ההודעות שממתינות מבוטלות (cancelled), והפעלה מחדש לא שולחת אותן; אפשר לשלוח שוב משלוח שבוטל או נכשל, אחד אחד (retry), עם אותו webhook-id ואותו גוף.
• שמירה: משלוחים שהסתיימו נמחקים 30 יום אחרי שנוצרו, ממתינים (למשל ב-webhook מושהה) אחרי 31 יום; היסטוריית השינויים אחרי שנתיים.

משלוח (WebhookDeliveryInfo): { id, endpointId, messageId, eventType, eventId, documentId, status, attempts, nextAttemptAt, lastAttemptAt, lastStatusCode, lastError, lastDurationMs, resultUrl, createdAt, completedAt, payload }. nextAttemptAt: null בממתין = מיד. lastError הוא הסבר קצר בעברית (בלי גוף התשובה, בלי כתובות ובלי טוקנים).

routine של Claude Code

• יוצרים routine ב-claude.ai/code/routines, מחברים אליו את המחבר של מערכת הפקת המסמכים, ובחלק Select a trigger בוחרים API ולוחצים Generate token. את הכתובת (או המזהה trig_...) ואת הטוקן (sk-ant-oat01-...) מדביקים ביצירה (S). הטוקן מוחלף ב-PATCH { routineToken } (S).
• מומלץ לשלוח רק document.issued (ברירת המחדל), ו-routine ייעודי שמחובר רק למחבר של מערכת הפקת המסמכים. פרטי הלקוחות שה-routine קורא מהמסמכים נשמרים בהיסטוריית השיחות ב-claude.ai.
• המנוע שולח בעצמו: POST לכתובת הקבועה עם authorization: Bearer <הטוקן>, anthropic-version: 2023-06-01 וגוף {"text": "..."}. הטקסט: שורה בעברית לכל אירוע, ואחריה מערך ה-JSON של ההודעות (בדיוק הגוף של ה-webhooks).
• קבוצות ומרווח: הפעלה אחת לכל האירועים שממתינים (עד 20), ולכל היותר הפעלה אחת בכל 3 דקות לכל routine (עד 20 בשעה, מתוך 30 שמותרות ל-routine).
• בלי ניסיון חוזר אחרי תוצאה לא ודאית: ל-API של Claude אין מזהה שמונע כפילות, וכל הפעלה פותחת שיחה. המנוע מנסה שוב לבד רק כשבטוח שלא נפתחה שיחה: 429 (לפי Retry-After, בין דקה לשעה, עד 24 שעות מהאירוע, בלי להיחשב ככישלון), 500/503/529 וחיבור שלא הוקם (עד 4 ניסיונות). זמן קצוב (30 שניות), תקלת רשת או 5xx אחר: נכשל, עם האזהרה "ייתכן שנפתחה שיחה ב-Claude". 400 (למשל routine מושהה) משבית (routine_paused_or_invalid); 401/403/404 משביתים (routine_rejected).
• שליחה חוזרת ידנית ובדיקה של routine פותחות שיחה חדשה בחשבון של בעל העסק, ולכן רק בכניסה עם סיסמה (O), עם אזהרה באתר.
• הצלחה: resultUrl של המשלוח הוא הקישור לשיחה (https://claude.ai/code/session_...).

Channels והתראות שרת של claude.ai לא נתמכים: הם עובדים רק בתוך Claude Code מקומי, ולא משרת מרוחק.

היסטוריית שינויים

כל יצירה, עדכון, החלפת סוד, הצגת כתובת, הפעלה, השהיה, השבתה אוטומטית ומחיקה נרשמים (audit ב-GET .../webhooks, 50 האחרונים): { id, endpointId, action, actor, kind, url, eventTypes, detail, at }, עם הכתובת המקוצרת ומי שביצע (system בהשבתה אוטומטית). הרשומות נשארות גם אחרי מחיקת ה-webhook, ונמחקות אחרי שנתיים.

מינויי אוטומציה: Zapier ו-Make (מנוע 0.19)

פלטפורמות אוטומציה (Zapier, Make) נרשמות לאירועים ומבטלות את הרישום בעצמן (REST hooks), כשהמשתמש מפעיל או מכבה זאפ או תרחיש. לכן כאן לא נדרשת סיסמת בעל העסק: מינוי נוצר במפתח API של העסק (iek_) או בטוקן גישה אישי (iep_) של מי שמפיק בעסק (בעל העסק או עובד). בכניסה עם סיסמה (ies_), בטוקן שירות ובטוקן המנהל – 403; רואה חשבון – 403.

מה שומר על זה בטוח:

• רשימת היתר אחת (INTEGRATION_HOOK_HOSTS ב-engine/src/domain/webhooks.ts): Zapier – hooks.zapier.com; Make – hook.<אזור>.make.com (eu1, eu2, us1, us2...), hook.integromat.com, כל *.make.com, ו-hook.<אזור>.make.celonis.com. כתובת אחרת: 422. קודם כל חלים כללי הכתובת הרגילים (https בלבד, פורט 443, לא IP, לא שם פנימי), והמשגר בודק שוב לפני כל שליחה, כולל ההגנה ברמת הרשת.
• המינוי קשור למפתח או לטוקן שיצר אותו: ביטול המפתח (DELETE /v1/api-keys/:keyId) או הטוקן, וגם שינוי סיסמה (שמבטל את כל הטוקנים), מוחקים את המינויים שלו (בהיסטוריה: zapier: credential_revoked). טוקן שפג מפסיק לקבל הודעות מיד. כך מינוי לא נותן גישה שנשארת אחרי האישור – ומפתח API ממילא קורא את כל המסמכים של העסק.
• אותו גוף, אותה חתימה, אותו משגר: מינוי הוא webhook רגיל מסוג standard, ולכן ההודעה זהה לגוף ההודעה (כולל data.shareLink כשהמסמך הופק עם קישור שיתוף), חתומה כרגיל (הסוד לא מוחזר; הפלטפורמות לא חייבות לבדוק), עם אותם ניסיונות חוזרים, מפסק והשבתה (410 מהפלטפורמה משבית).
• גלוי לבעל העסק: המינויים מופיעים ב-GET /v1/businesses/:id/webhooks עם integration: "zapier" | "make" (ובאתר: בכרטיס ה-webhooks עם שם הפלטפורמה), נרשמים בהיסטוריית השינויים (create / delete, עם שם המפתח), ובעל העסק מבטל כל אחד (DELETE /v1/webhooks/:endpointId). את הכתובת של מינוי אי אפשר לשנות (422): מוחקים, והפלטפורמה נרשמת מחדש.
• מגבלה: עד 25 מינויים לעסק, בנפרד מ-10 ה-webhooks של בעל העסק.
• מגבלות קצב (מנוע 0.20): הקריאות של הפלטפורמות נספרות כמו כל קריאה במפתח או בטוקן (מגבלות קצב). על 429 מחכים לפי Retry-After; האפליקציה של Zapier עושה זאת לבד.

מינוי (IntegrationHookInfo): { id, businessId, platform, url, eventTypes, docTypes, enabled, disabledReason, createdAt, createdBy }, עם הכתובת המקוצרת (https://hooks.zapier.com/hooks/…).

curl -s -X POST https://<site>/api/v1/businesses/$BIZ/integration-hooks -H "Authorization: Bearer $IEK" \
  -H "Content-Type: application/json" \
  -d '{ "platform": "zapier", "url": "https://hooks.zapier.com/hooks/standard/123/abc/", "event": "document.issued", "docTypes": [305, 320] }'

סקירה בתדירות (polling): כשאין מינוי (או כגיבוי), הטריגרים קוראים רשימות מהחדש לישן עם מזהה קבוע, והפלטפורמה מסננת כפילויות לפי id: מסמך חדש – GET /v1/businesses/:id/documents?limit=50 (או sinceId); מקור שהופק – GET /v1/businesses/:id/events?event=original_produced&order=desc; לקוח חדש – GET /v1/businesses/:id/customers?sort=newest (ליצירה ועדכון של כרטיסים אין אירועים ואין webhooks). האפליקציות המוכנות נמצאות ב-integrations/zapier וב-integrations/make, והמדריך באתר ב-/docs/integrations.

המשגר (/v1/internal/webhooks/*)

מי ששולח בפועל את משלוחי ה-standard הוא משגר: בשרת ה-Node הרשום, לולאה בתוך התהליך (ENGINE_WEBHOOK_DISPATCHER=inprocess, עם ההגנה ברמת הרשת); בשירות הנוכחי על Lovable Cloud, ה-Worker של האתר (POST /api/webhooks/dispatch), ש-pg_net ו-pg_cron מעירים. משגר חיצוני מדבר עם המנוע בשלוש קריאות, בטוקן המשגר בלבד:

• outcome: response (עם status 100..599), timeout, network, connect (החיבור לא הוקם), blocked (כתובת פנימית), invalid_url. המשגר מדווח רק עובדות; המנוע מחליט על ניסיון חוזר והשבתה.
• חכירה: כל בקשה שנלקחה שמורה למשגר 60 שניות. דיווח מתקבל רק עם leaseToken הנוכחי של המשלוח, ולכן מותר לשלוח אותו שוב אחרי תקלת רשת (בפעם השנייה הוא ignored). בלי דיווח החכירה פגה והמשלוח יילקח שוב.
• לפני כל שליחה המשגר בודק שוב את הכתובת (אותם כללים, והכתובת חייבת להיות כבר מנורמלת), שולח רק את הכותרות שבבקשה, לא עוקב אחרי הפניות ולא קורא את גוף התשובה.
• בקשה לא כוללת אף פעם authorization או טוקן של routine.

אישור קצר-מועד whd1: במקום הטוקן עצמו, המשגר שולח Authorization: Bearer whd1.<unix>.<hex>, כש-unix הוא הזמן בשניות (10 ספרות) ו-hex הוא HMAC-SHA256 בהקסדצימלי (אותיות קטנות), במפתח = הבתים של טוקן המשגר (UTF-8), על invoice-engine/dispatch/v1|<unix>. תקף כשהזמן רחוק מעכשיו לכל היותר 120 שניות. וקטור:

token  = 0f1e2d3c4b5a69788796a5b4c3d2e1f00112233445566778899aabbccddeeff
unix   = 1792055564
result = whd1.1792055564.a7be6b62a5030574d45830e37a3fe699fb94bb8414275180233e5e369a059f12

ב-SQL (pgcrypto): 'whd1.' || unix || '.' || encode(hmac('invoice-engine/dispatch/v1|' || unix, token, 'sha256'), 'hex'). ה-Edge Function מקבל רק whd1. שרת Node מקבל גם את הטוקן עצמו רק עם ENGINE_WEBHOOK_DISPATCH_RAW=1. בלי טוקן משגר (ובלי משגר בתוך התהליך) הנתיבים האלה מחזירים 404, ויצירת webhook מחזירה 422.

הסכמה לקבלת מסמכים ממוחשבים (הוראה 18ב(ג))

הסכמה של לקוח לקבל מסמכים ממוחשבים צריכה להיות אישית, מפורשת וניתנת להוכחה, והלקוח רשאי לבטל אותה בכל עת. מקור ממוחשב מופק רק ללקוח שההחלטה האחרונה שלו היא הסכמה. כל החלטה (הסכמה או ביטול) היא רשומה חדשה שלא משתנה.

• POST /v1/businesses/:id/consents עם { customerKey, granted: true, channel: "email", evidence: { description: "אישור במייל מ-dana@example.com מיום 1.10.2026", ... } }. מנוע 0.15: בהסכמה חובה evidence.description – מה מוכיח שהלקוח הסכים (3–500 תווים, למשל "טופס חתום מיום ..."). בלעדיו: 422. ביטול (granted: false) לא דורש ראיה (אפשר הערה ב-description).
• GET /v1/businesses/:id/consents/:customerKey → { granted }

קישור אישור ללקוח

מנוע 0.15: העסק שולח ללקוח קישור (<האתר>/c/<token>), והלקוח רואה את שם העסק ואת נוסח ההסכמה המדויק, ומאשר ("אני מסכים/ה לקבל מסמכים ממוחשבים") או מבטל בעצמו, בלי להתחבר. ההחלטה נרשמת ב-consents עם channel: "customer_link" והראיה: { method: "customer_link", linkId, at, decision, wordingVersion, wordingSha256, client, userAgent } – הזמן, גרסת הנוסח וה-SHA-256 של הנוסח שהוצג, טביעה מקוצרת של רשת הלקוח (לא כתובת ה-IP) והדפדפן. הטוקן מוחזר פעם אחת ונשמר רק ה-SHA-256 שלו; אפשר לבטל קישור, וההחלטות שנרשמו נשארות.

אזהרה: קבלה במזומן על מסמך ממוחשב

לפי הוראה 18ב(ד), מי ששולח מסמך ממוחשב בחתימה מאובטחת מקבל את התקבול רק בכרטיס אשראי, בשיק משורטט "לא סחיר" או בהעברה בנקאית. מנוע 0.15: קבלה (400) עם base של מסמך שכבר נמסר כמקור ממוחשב, בתקבול אחר (למשל מזומן), לא נחסמת, אבל בתשובה של dryRun, של ההפקה ושל התצוגה המקדימה (כותרת X-Issue-Warnings, JSON מקודד ל-URL) מופיע warnings: ["..."] בעברית. את המקור של קבלה כזו מדפיסים וחותמים ביד.

מבנה אחיד

POST /v1/businesses/:id/openformat עם { from, to } מחזיר ZIP ובתוכו OPENFRMT/<8 ספרות>.<שנה>/<MMDDhhmm>/INI.TXT ו-BKMVDATA.zip. עם ?format=json מתקבל רק הסיכום: מספר רשומות לכל סוג ודוח המסמכים של נספח 1. מנוע 0.17: עם "transmit": true (רק מי שמפיק) הקובץ גם משודר לרשות המסים מיד עם סיום ההפקה – אותם בתים שיורדים – ותוצאת השידור חוזרת בכותרת X-Ita-Transmission (JSON מקודד ל-URL: status = uploaded / failed / not_sent, summary, sandboxPlaceholder, error). ההורדה עובדת גם כשהשידור נכשל או שהעסק לא מחובר. ראו רשות המסים.

רשות המסים (מנוע 0.17)

חיבור לשירותי ה-Open API של רשות המסים (שע"ם): מספרי הקצאה (חשבוניות ישראל, API 2.0), דיווח קבלות על תרומה ("תרומות ישראל", מודל תרומות 1.0), בדיקת סעיף 46, ושידור קובץ המבנה האחיד (תוספת מס' 1, 3/2026). מתחילים ב-sandbox. כל הפניות לרשות המסים ול-Google עוברות בשרת; הטוקנים לא יוצאים ממנו.

האפליקציה של בית התוכנה (פעם אחת)

environment: sandbox (ברירת המחדל) או production. redirectUri: בדיוק הכתובת שנרשמה באפליקציה בפורטל, ברירת המחדל <האתר>/ita/callback (https://retsef.co.il/ita/callback). scope: מה שמבקשים בהתחברות (ברירת המחדל scope, כמו בדוגמאות של המדריך). הסוד: ב-Edge Function נכתב ל-Supabase Vault (invoice_engine_ita_client_secret, vault.create_secret / vault.update_secret); כשאין Vault או שהכתיבה נכשלת – מוצפן בבסיס הנתונים (AES-256-GCM במפתח שנגזר מסיסמת מפתחות החתימה שב-Vault), ו-secretStore אומר איפה. כל שינוי נרשם ביומן ita_app_changes בלי הסוד. מעבר סביבה מחייב כל עסק להתחבר מחדש.

התחברות של עסק (רק מהאתר)

1. POST /v1/businesses/:id/ita/connect – בעל העסק, בכניסה עם סיסמה (לא טוקן גישה אישי, לא MCP). מחזיר { authorizeUrl, expiresAt }: כתובת ההזדהות ברשות המסים עם state אקראי (נשמר רק ה-hash שלו), קשור למשתמש ולעסק, תקף עשר דקות ולשימוש אחד.
2. רשות המסים מחזירה את הדפדפן ל-/ita/callback?code=...&state=.... הדף מוחק את הקוד מהכתובת ושולח POST /v1/ita/callback { code, state }. המנוע בודק שה-state של אותו משתמש, שיש לו עדיין הרשאת ניהול בעסק, שלא פג ולא נוצל, ומחליף את הקוד בטוקנים (Basic client_id:client_secret).
3. הטוקנים נשמרים מוצפנים. טוקן הגישה תקף כעשר דקות; ה-refresh token חד-פעמי, ומוחלף תחת נעילת השורה (SELECT … FOR UPDATE), כך שבקשות במקביל לא שולחות אותו פעמיים. 401 משירות: חידוש אחד וניסיון חוזר. refresh token שנדחה (או שעברו 90 יום) מסמן את החיבור "צריך להתחבר מחדש".

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

מספר הקצאה (Approval v2)

חשבונית מס / חשבונית מס/קבלה שחייבת מספר הקצאה (הכלל של המנוע, ללא שינוי בספים) מופקת קודם, כרגיל, ומיד אחר כך – מחוץ לטרנזקציה של ההפקה – נשלחת הבקשה (המפרט, 2.1: הפנייה כשהחשבונית "נושאת כבר את מספר האסמכתא"). התשובה של ההפקה כוללת ita.allocation:

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

invoice_id (A50) הוא R<סוג>-<מספר>-<12 תווים מה-hash>: קבוע לכל מסמך, כך שניסיון חוזר (גם אחרי שימוע) נשלח עם אותו מזהה. user_name הוא מבצע הפעולה (עד 25 תווים). accounting_software_number – מספר הרישום, ועד שיש כזה מספר העוסק של מפיק המסמך, כמו במפרט.

קבלות על תרומה ("תרומות ישראל")

עמותה (kind: "nonprofit") עם אישור סעיף 46 רשום ועם חיבור: כל קבלה על תרומה (405) מדווחת (Donations/v1/Report) מיד אחרי ההפקה, באותו עיקרון – הקבלה קודם, הדיווח בטבלה נפרדת (document_donation_reports). התשובה כוללת ita.donation. מספר האישור והמשפט "פרטי התרומה דווחו לרשות המסים" מודפסים על הקבלה (מודל תרומות 2.2) – רק כשהדיווח נרשם לפני הפקת המקור, כדי שכל העתק יהיה זהה למקור. לכן כשהעמותה מחוברת והקבלה עוד לא דווחה, המקור לא מופק (422) אלא אם שולחים withoutDonationReport: true ב-POST /v1/documents/:docId/original.

זהות התורם (2.3.1): מספר הזהות / ח"פ של הלקוח; תושב חוץ 888888888; בלי מספר – תרומה בעילום שם 999999999. אמצעי תשלום: מזומן 01, המחאה 02 (עם פרטי ההמחאה), אשראי 03 (עם סוג העסקה), העברה 04, הוראת קבע 08, "אחר" (ביט ודומיו) 10, תווים / שטר 11. קבלה עם כמה סוגי אמצעי תשלום לא מדווחת (2.3.4: קבלה נפרדת לכל סוג).

שידור קובץ המבנה האחיד (תוספת מס' 1)

GetUrlsForUploadingFiles { caseNumber: <מספר העוסק>, startPeriod, endPeriod } → לכל קובץ (INI, BKM): POST ל-signUrl עם הכותרות שהתקבלו (201 + Location), ואז PUT לפי טבלת הגדלים: עד 32MB בבקשה אחת; מעל זה חלקים של 32MB / 64MB / 128MB עם Content-Range (308 עד החלק האחרון). לפני ההעלאה נבדק הגודל מול x-goog-content-length-range; קובץ גדול מדי לא נשלח, וההודעה מפנה ל-APISUPPORT@TAXES.GOV.IL. נשלח BKMVDATA.TXT עצמו (לא ה-ZIP), כמו בשמות הקבצים בדוגמאות של המפרט. sandbox: מקבל רק PDF עד 1MB, ולכן שם נשלח PDF קטן במקום כל קובץ (sandboxPlaceholder: true, מסומן בממשק וביומן); הגודל וה-SHA-256 שנשמרים הם של הקובץ האמיתי.

עבודת רקע: POST /v1/internal/ita/poll (טוקן המשגר / whd1 בלבד) בודק שידורים מ-30 הימים האחרונים שעוד לא קיבלו תשובה סופית, לכל היותר פעם בעשר דקות לכל שידור. ב-Lovable Cloud מפעילים אותו ב-supabase/sql/ita_poll.sql (pg_cron, כל רבע שעה).

שגיאות

שגיאה של רשות המסים בנתיבים האלה: 409 עם itaError: "not_connected" / "auth" (צריך להתחבר), 422 עם "rejected" / "forbidden", 503 עם "unavailable". ההודעה בעברית. בקשה ולוג לעולם לא כוללים טוקן, קוד או סוד.

חיבור מה-CRM

את הקריאות שולחים מצד השרת בלבד (Supabase Edge Function), כשמפתח ה-API של העסק שמור בסודות. מפתח API אסור לשים בקוד הדפדפן. בדפדפן משתמשים רק בטוקן כניסה של משתמש.

התיעוד הזה הוא engine/docs/API.md של המנוע. אותו תוכן, עם הקדמה לסוכני AI ורשימת כלי ה-MCP, ב-/docs/api.md.