הצטרפות

Invoice Maven API — מדריך מלא למפתחים: לקוחות, ספקים, פריטים ומסמכים

Invoice Maven API — מדריך מלא למפתחים

למערכת Invoice Maven יש REST API מלא שמאפשר ליצור, לעדכן ולחפש לקוחות, ספקים, פריטים ומסמכים ישירות מתוך מערכת חיצונית (CRM, אתר, מערכת הזמנות וכו'). מדריך זה מסביר את כל מה שצריך כדי להתחיל לעבוד מול ה-API.

  • שיטה: כל הקריאות הן POST עם גוף JSON.
  • אבטחה: התעבורה מוצפנת ב-SSL בלבד (port 443).
  • קידוד: UTF-8.

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

מאיפה מקבלים מפתח API?

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

  1. היכנסו למערכת ופתחו את עמוד הגדרות < API.
  2. העתיקו את המפתח בעזרת כפתור ההעתקה שליד שדה מפתח API.
  3. שמרו את המפתח בצד השרת של האפליקציה שלכם בלבד — אין לחשוף אותו בקוד צד-לקוח (דפדפן / אפליקציה).

אימות (Authentication)

אפשר להעביר את המפתח באחת משתי דרכים:

  • בכותרת ה-HTTP (מומלץ): api_key: YOUR_KEY
  • בגוף ה-JSON: "api_key": "YOUR_KEY"

שדות חובה בכל קריאה

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

  • api_key: מפתח העסק (אם לא הועבר בכותרת ה-HTTP).
  • test: 0 לפעולה אמיתית, 1 לבדיקה בלבד (ראו בהמשך).
  • contact_email: אימייל של מפתח התוכנה ליצירת קשר במקרה של בעיה.
  • contact_phone: טלפון של מפתח התוכנה.

מצב בדיקה (Test mode)

כל קריאה תומכת בשדה test שמאפשר להריץ את הקוד בלי לשמור נתונים אמיתיים:

  • 0 — פעולה אמיתית (נשמרת במערכת).
  • 1 — בדיקה בלבד (לא נשמר במערכת). מומלץ לעבוד עם test: 1 בזמן הפיתוח.

מבנה התגובה (Response format)

כל תגובה מוחזרת כ-JSON. השדה status_code מציין הצלחה או כשל:

  • הצלחה: "status_code": "0" (לצד שדות נוספים כמו מזהי הרשומה שנוצרה).
  • שגיאה: כל ערך שונה מ-"0", יחד עם שדה status_description שמתאר את הבעיה.
{
  "status_code": "0",
  "status_description": "OK"
}

לקוחות (Customers)

ניהול לקוחות — יצירה, עדכון, ושילוב Upsert. שלושה endpoints:

  • POST /api/customers/addCustomer — יצירת לקוח חדש. אם הלקוח כבר קיים (לפי id, identification או email) — תוחזר שגיאה.
  • POST /api/customers/updateCustomer — עדכון לקוח קיים. נדרש לפחות אחד משדות הזיהוי: id, identification או email.
  • POST /api/customers/addOrUpdateCustomer — יצירה או עדכון (Upsert). ה-endpoint המומלץ לרוב האינטגרציות: אם הלקוח קיים — מתעדכן, אם לא — נוצר. חוסך לכם לוגיקה של "האם הלקוח כבר קיים?".

שדות עיקריים: name (שם הלקוח, חובה), identification (ת.ז / ח.פ), id (GUID של הלקוח), external_customer_id (מזהה ממערכת חיצונית כגון CRM), email, cell_phone, phone_number, address, city, zip_code, country_code (קוד מדינה ISO — IL לישראל, US לארה"ב), ו-send_to_customer (האם לשלוח אימייל ללקוח בהפקת מסמך עתידי, ברירת מחדל true).

דוגמה — יצירה או עדכון לקוח (בקשה מינימלית):

POST /api/customers/addOrUpdateCustomer

{
  "api_key": "YOUR_API_KEY",
  "test": 0,
  "contact_email": "dev@example.com",
  "contact_phone": "050-1234567",
  "name": "שלום כהן",
  "identification": "123456789",
  "email": "shalom@example.com",
  "external_customer_id": "CRM-12345"
}

תגובה:

{
  "status_code": "0",
  "status_description": "OK",
  "id": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
  "customer_id": 12345
}

ספקים (Suppliers)

ניהול ספקים — מבנה זהה לחלוטין ללקוחות, רק שהרשומה נשמרת כספק במקום כלקוח:

  • POST /api/suppliers/addSupplier — יצירת ספק חדש.
  • POST /api/suppliers/updateSupplier — עדכון ספק קיים.
  • POST /api/suppliers/addOrUpdateSupplier — יצירה או עדכון ספק (Upsert) — מומלץ.

השדות זהים לאלו של הלקוחות (name, identification, email, address וכו').

פריטים (Items)

ניהול קטלוג הפריטים — יצירה, עדכון, ו-Upsert:

  • POST /api/items/addItem — יצירת פריט חדש. אם פריט עם אותו item_no או external_item_id כבר קיים — תוחזר שגיאת כפילות.
  • POST /api/items/updateItem — עדכון פריט קיים (זיהוי לפי id / item_no / external_item_id).
  • POST /api/items/addOrUpdateItem — יצירה או עדכון (Upsert) — מומלץ.

שדות עיקריים: name (שם הפריט, חובה), amount (מחיר, חובה), item_no (מק"ט פנימי ייחודי), external_item_id (מזהה חיצוני ייחודי), description (תיאור שיופיע על המסמך), currency_id (מטבע: 1 = שקל ברירת מחדל, 2 = דולר, 3 = יורו), vat_included_yn (האם המחיר כולל מע"מ), no_vat_yn (האם פטור ממע"מ), inventory_management_yn ו-inventory_count (ניהול מלאי וכמות), archive_yn (בארכיון).

דוגמה — פריט בסיסי:

POST /api/items/addOrUpdateItem

{
  "api_key": "YOUR_API_KEY",
  "test": 0,
  "contact_email": "dev@example.com",
  "contact_phone": "050-1234567",
  "name": "ייעוץ שעתי",
  "amount": 350,
  "item_no": "ITEM-001",
  "currency_id": 1,
  "vat_included_yn": false
}

מסמכים (Documents)

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

  • POST /api/documents/addDocument — הפקת מסמך חדש.
  • POST /api/documents/searchDocuments — חיפוש מסמכים לפי טווח תאריכים, לקוח או סוג.
  • POST /api/documents/closeDocument — סגירת מסמך פתוח (למשל הצעת מחיר ← חשבונית).

שדה type קובע את סוג המסמך:

  • 1 — חשבונית מס
  • 3 — חשבונית מס-קבלה
  • 4 — קבלה
  • 5 — הצעת מחיר
  • 6 — תעודת משלוח
  • 7 — חשבונית זיכוי

שדות עיקריים בהפקת מסמך: customer (אובייקט פרטי הלקוח — נוצר אוטומטית אם אינו קיים), items (מערך שורות המסמך), payment_type (1 = מזומן, 2 = צ'ק, 3 = העברה, 4 = אשראי), currency_code (ILS / USD / EUR), send_email (שליחה אוטומטית של המסמך ללקוח), issue_date (תאריך הפקה — אם לא מועבר, היום), ו-allocation_number.

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

דוגמה — הפקת חשבונית מס ושליחתה ללקוח:

POST /api/documents/addDocument

{
  "api_key": "YOUR_API_KEY",
  "test": 0,
  "contact_email": "dev@example.com",
  "contact_phone": "050-1234567",
  "type": 1,
  "customer": {
    "name": "שלום כהן",
    "identification": "123456789",
    "email": "shalom@example.com"
  },
  "items": [
    { "name": "ייעוץ שעתי", "amount": 350, "quantity": 2 }
  ],
  "payment_type": 4,
  "send_email": true
}

תגובה — כוללת את מספר המסמך, מספר ההקצאה (אם רלוונטי) וקישור ישיר ל-PDF:

{
  "status_code": "0",
  "status_description": "OK",
  "id": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
  "document_id": 6789,
  "document_number": "2026-001",
  "allocation_number": "...",
  "pdf_url": "https://app.invoice-maven.co.il/..."
}

דוגמה — חיפוש מסמכים לפי טווח תאריכים:

POST /api/documents/searchDocuments

{
  "api_key": "YOUR_API_KEY",
  "test": 0,
  "contact_email": "dev@example.com",
  "contact_phone": "050-1234567",
  "from_date": "2026-01-01",
  "to_date": "2026-12-31"
}

דוגמאות קוד ושפות נתמכות

התיעוד האינטראקטיבי מציג דוגמת קוד מוכנה להעתקה עבור כל endpoint, בכל אחת מהשפות הבאות: cURL, Python, JavaScript, PHP, Java, C#, Ruby ו-Go. כמו כן ניתן להוריד מתוך עמוד הגדרות < API קובץ ZIP עם דוגמאות שימוש מלאות.

תמיכה

שאלה או בעיה? שלחו אימייל ל-support@invoice-maven.co.il או פתחו פנייה ב-דף יצירת קשר.

טיפים נוספים לעבודה מול ה-API:
• עבדו עם test: 1 בזמן הפיתוח כדי לא ליצור רשומות אמיתיות, ועברו ל-test: 0 בסביבת הייצור.
• העדיפו את ה-endpoints מסוג addOrUpdate (Upsert) — הם פשוטים יותר ומונעים שגיאות כפילות.
• שמרו את ה-customer_id / item_id / document_id שחוזרים בתגובה, כדי לקשר את הרשומות במערכת שלכם.
• בכל שגיאה — בדקו את השדה status_description שמסביר בדיוק מה הבעיה.

x

הצטרפות