עזרה כללית ב-API

דף ה-API במערכת — מפתח חיבור, תיעוד אינטראקטיבי וקוד מוכן בכל שפה

למי זה מיועד? מפתחים, אנשי IT, ובעלי עסקים שרוצים לחבר את Invoice Maven לתוכנות צד שלישי — חנות אונליין, CRM, מערכת הנהלת חשבונות, אוטומציות, או כל מערכת שמייצרת חשבוניות בכמויות. כל מה שצריך נמצא בדף אחד: הגדרות > API.

מה יש בדף?

דף ה-API כולל שני חלקים עיקריים:

מפתח ה-API שלכם — הקוד הייחודי שמזהה את העסק שלכם בקריאות API. ניתן להעתיק בלחיצה אחת.
תיעוד אינטראקטיבי מלא — כל ה-endpoints (לקוחות, ספקים, פריטים, מסמכים) עם פרמטרים, דוגמאות, וקוד מוכן בכל שפה (cURL, Python, JavaScript, PHP, Java, C#, Ruby, Go) שאפשר להעתיק ולהדביק.

איך מגיעים לדף?

מהתפריט הראשי, היכנסו להגדרות > API. תועברו לעמוד app.invoice-maven.co.il/api.jsf.

חלק 1: מפתח ה-API

בראש העמוד תראו את מפתח ה-API שלכם — מחרוזת ייחודית של אותיות ומספרים. זה המזהה של העסק שלכם בקריאות לשרת.

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

אזהרה: אל תכניסו את ה-API key בקוד frontend (HTML/JS) שרץ בדפדפן הלקוח — כל אחד יוכל לראות אותו. השתמשו בו רק מהשרת שלכם (Backend).

חלק 2: תיעוד API אינטראקטיבי (חדש!)

מתחת לאזור המפתח יש פורטל תיעוד מלא ומובנה בעמוד עצמו. תוכלו לנווט בו ולגלות את כל ה-endpoints בלי לעזוב את העמוד.

איך זה מסודר

תפריט שמאלי: כל ה-endpoints מקובצים לפי קטגוריה — Customers, Suppliers, Items, Documents.
אזור תוכן מרכזי: לחצו על endpoint בתפריט — תראו תיאור, רשימת פרמטרים, סוגי שדות, וערכי ברירת מחדל.
פאנל שחור משמאל: קוד מוכן לשימוש בכל שפה! בחרו cURL / Python / JavaScript / PHP / Java / C# / Ruby / Go — הקוד מתאים לאותו endpoint שאתם רואים באמצע. כפתור Copy מעתיק את הקוד בלחיצה.

איך משתמשים בקוד

בחרו את ה-endpoint הרצוי בתפריט (לדוגמה: POST /api/items/addOrUpdateItem).
בפאנל הימני בחרו את השפה (לדוגמה Python).
לחצו על אייקון ה-Copy בפינה הימנית של בלוק הקוד.
הדביקו לפרויקט שלכם.
החליפו את YOUR_API_KEY במפתח שלכם מחלק 1.
הריצו — תוכלו לקבל פריט/לקוח/מסמך מיד.

מה מכוסה בתיעוד?

Customers — יצירה, עדכון, יצירה-או-עדכון (Upsert) של לקוחות.
Suppliers — אותם פעולות לספקים.
Items — קטלוג פריטים: יצירה, עדכון, Upsert. כולל ניהול מלאי, מטבעות שונים, ומע"מ.
Documents — הפקת חשבוניות מס, חשבוניות מס-קבלה, קבלות, הצעות מחיר. כולל קישור אוטומטי למספר הקצאה מרשות המיסים.
Authentication — איך לשלוח את ה-`api_key` נכון.
Test mode — איך להריץ בקשות לבדיקה בלי לשמור ב-DB (חיוני בפיתוח!).

טיפים מעשיים

תמיד התחילו ב-Test Mode

כל endpoint מקבל שדה test. הזינו test=1 כדי לבצע קריאה בלי לשמור בפועל. המערכת תחזיר תגובה כאילו הפעולה הצליחה — בלי ליצור לקוח, פריט, או חשבונית.

אחרי שהקוד שלכם עובד תקין עם test=1, החליפו ל-test=0 לפרודקשן.

השתמשו ב-AddOrUpdate כברירת מחדל

ל-Add ול-Update יש מקרי שימוש ספציפיים (טיפול בכפילויות, אכיפת תקינות). ל-AddOrUpdate אין — הוא תמיד עובד: אם הרשומה קיימת, מעדכן. אם לא — יוצר. הכי גמיש ופחות שגיאות.

הגדירו את `contact_email` ו-`contact_phone` כראוי

אלה שדות חובה — מפתח התוכנה שמשלב מול ה-API. אם תהיה בעיה, צוות התמיכה של Invoice Maven יוכל לפנות ישירות לאחראי.

שמרו את ה-`id` שמוחזר

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

קישורי תיעוד נוספים

שאלות נפוצות

שאלה: איך אני מקבל api_key אם אני לא רואה אותו?
תשובה: אם השדה ריק — צרו קשר עם התמיכה דרך דף יצירת קשר. אצלכם הוא כנראה עדיין לא הופעל בחשבון.

שאלה: למה הקוד שאני מעתיק לא עובד?
תשובה: ודאו שהחלפתם את YOUR_API_KEY במפתח האמיתי שלכם. בנוסף, ודאו ש-`test=1` בזמן הבדיקה (לא מעבירים ערכים חוקיים בכוונה? המערכת תפסול אותם).

שאלה: איפה אני רואה את ההיסטוריה של קריאות API?
תשובה: כל קריאה נשמרת בטבלת api_call במערכת. צוות התמיכה יכול לחפש לכם לפי תאריך/endpoint/שדה — שלחו מייל עם הפרטים.

שאלה: יש Rate Limit?
תשובה: כן, אבל יחסית רחב — מעל אלפי קריאות ביום. אם אתם צריכים יותר — דברו איתנו.

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

שאלה: אפשר לחבר Make/Integromat?
תשובה: כן — יש לנו תבניות מוכנות. ראו המדריך לאוטומציות ב-Make.

צעדים הבאים

סדר עבודה מומלץ: • היכנסו ל-הגדרות > API וקבלו את המפתח שלכם.
• גלשו בפורטל הסגול-שחור בחלק התחתון של הדף — תוכלו ללמוד את כל ה-endpoints ולהעתיק קוד.
• התחילו ב-AddOrUpdateItem או AddOrUpdateCustomer — הכי קל.
• הריצו עם test=1, ודאו שזה עובד, ואז עברו ל-test=0.
• למידע נוסף או שאלות: דף יצירת קשר.