סגירת מסמכים ב-API

מדריך API – סגירה ידנית של מסמכים

ניתן לפנות ל- API של Invoice Maven באמצעות בקשת JSON.
יש לפנות באמצעות POST .
החיבור צריך להתבצע באמצעות SSL (פורט 443).
לכל פניה יתווסף מפתח API שהוא בעצם מזהה חד ערכי לחשבון הלקוח במערכת.
הפעולה מסמנת מסמך פתוח (חשבונית עסקה / חשבונית מס / הזמנת עבודה / הצעת מחיר וכד') כסגור ידנית, באופן זהה לסימון 'סגור ידנית' במסך 'מסמכים' של המערכת.
לאחר הפניה השרת יחזיר תשובה בפורמט JSON המציינת האם הפעולה הצליחה ואם לא את קוד ותיאור השגיאה.
ניתן להעביר מסמך אחד או רשימה של מסמכים בפניה אחת. במקרה שאחד המסמכים לא נמצא או כבר סגור — אף אחד מהמסמכים בפניה לא ייסגר (פעולה אטומית).
את השדות המועברים יש לכתוב ב- lowercase בלבד.
הקידוד של הפניה צריך להיות UTF-8.

בקשה לסגירת מסמך – CloseDocument יש לפנות לכתובת: https://app.invoice-maven.co.il/api/documents/closeDocument יש להעביר את הפרמטרים הבאים בפורמט JSON: שדות כלליים:

שדה	ברירת מחדל	חובה	תיאור
api_key		כן	מפתח ייחודי המשוייך לעסק במערכת ויש להעביר אותו עם כל בקשה.
documents		לא	רשימה (מערך) של מסמכים לסגירה. ניתן להעביר את השדות (id / doc_id / doc_no + doc_type) ברמת הבקשה הראשית, כדי לסגור מסמך בודד, או להעביר רשימה תחת שדה זה כדי לסגור מספר מסמכים בפעולה אחת. ראה מבנה שדות מסמך בהמשך.

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

שדה	ברירת מחדל	חובה	תיאור
id		לא	מזהה ייחודי (UUID) של המסמך כפי שהוחזר מ-AddDocument או מ-SearchDocuments. שיטת זיהוי מומלצת.
doc_id		לא	מזהה חיצוני שהועבר ע"י המפתח בשדה doc_id ב-AddDocument בעת הפקת המסמך.
doc_no		לא	מספר המסמך (document_no) במערכת. כשמשתמשים בשדה זה חובה להעביר גם doc_type.
doc_type		תלוי	סוג המסמך (חובה רק אם הזיהוי הוא לפי doc_no). ראה רשימת קודי סוגי מסמך ב-AddDocument: 305 – חשבונית מס 400 – קבלה 405 – קבלה על תרומה 320 – חשבונית מס / קבלה 330 – חשבונית זיכוי 10 – הצעת מחיר 100 – הזמנת עבודה 200 – תעודת משלוח 210 – תעודת החזרה 300 – חשבונית עסקה 500 – הזמנת רכש

דוגמת בקשה לסגירת מסמך בודד לפי id:

{
  "api_key": "YOUR_API_KEY",
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}

דוגמת בקשה לסגירת מסמך בודד לפי doc_no + doc_type:

{
  "api_key": "YOUR_API_KEY",
  "doc_no": 1234,
  "doc_type": 300
}

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

{
  "api_key": "YOUR_API_KEY",
  "documents": [
    { "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" },
    { "doc_id": "ORDER-2026-0042" },
    { "doc_no": 1234, "doc_type": 300 }
  ]
}

מבנה תשובה המתקבלת מהשרת:

שדה	תיאור
status_code	קוד סטטוס שגיאות. במידה והכל תקין יוחזר 0.
status_description	תיאור השגיאה. במידה והכל תקין יוחזר 'OK'.
closed_documents	מערך של המסמכים שנסגרו. כל איבר במערך מכיל: id (UUID), doc_no, doc_type ובמידה והועבר בעת הפקת המסמך גם doc_id (מזהה חיצוני).

דוגמת תשובה תקינה:

{
  "status_code": "0",
  "status_description": "OK",
  "closed_documents": [
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "doc_no": 1234,
      "doc_type": 300,
      "doc_id": "ORDER-2026-0042"
    }
  ]
}

קודי שגיאה אפשריים:

קוד	תיאור
2	שדה חובה חסר (api_key, documents, doc_type וכד').
4	מפתח API לא נמצא במערכת.
5	הערך של documents אינו מערך, או שהאיבר במערך אינו אובייקט.
37	מסמך לא נמצא לפי המזהה שהועבר.
38	המסמך כבר סגור (לא ניתן לסגור מסמך פעמיים).
39	לא הועבר אף מזהה (id / doc_id / doc_no) לאחד מהמסמכים.

מדריך API – סגירה ידנית של מסמכים

יש צורך בעזרה?

הצטרפות