הפקת מסמכים ב-API

מדריך API – הפקת מסמכים

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

בקשה להפקת מסמך – AddDocument

יש לפנות לכתובת:

https://app.invoice-maven.co.il/api/documents/addDocument

יש להעביר את הפרמטרים הבאים בפורמט JSON:

שדות כלליים:

שדה	ברירת מחדל	חובה	תיאור
api_key		כן	מפתח ייחודי המשוייך לעסק במערכת ויש להעביר אותו עם כל בקשה.
test		כן	האם להפיק מסמכי בדיקה בלבד (יש להעביר 1 כדי לבצע בדיקות לפני הפקת מסמכים אמיתיים):0- הפקת מסמכים אמיתיים 1- הפקת מסמכי בדיקה. במצב זה יופקו מסמכים ללא שמירה במערכת. המסמכים שיופקו לא ישלחו במייל ללקוח.
contact_email		כן	אימייל של המפתח תוכנה ליצירת קשר במקרה של בעיה.
contact_phone		כן	טלפון של המפתח תוכנה ליצירת קשר במקרה של בעיה.
doc_id		לא	מספר מזהה יחודי לבקשה. במידה ויתקבלו 2 פניות עם אותו מזהה, בפניה השניה לא יופק מסמך.
doc_type		כן	סוג המסמך:305 – חשבונית מס 400 – קבלה 405 – קבלה על תרומה 320 – חשבונית מס / קבלה 330 – חשבונית זיכוי 10 – הצעת מחיר 100 – הזמנת עבודה 200 – תעודת משלוח 210 – תעודת החזרה 300 – חשבונית עסקה 500 – הזמנת רכש
description		לא	תיאור המסמך
document_date		לא	תאריך של המסמך. אין צורך להעביר שדה הזה מכיוון שהמסמך נוצר עם התאריך של היום הנוכחי באופן אוטומטי. יש לדאוג שתאריכי המסמכים מאותו סוג הם בסדר כרונולוגי.
due_date		לא	תאריך לתשלום עד בפורמט dd/MM/yyyy
vat_included	0	לא	יש להעביר 1 אם מחירי הפריטים במסמך כוללים מע"מ.
discount		לא	הנחה באחוזים או בסכום. אחוז או סכום יקבע בשדה: discount_type
discount_type	1	לא	סוג ההנחה:1- לפי אחוזים 2- לפי סכום
round_total	0	לא	יש להעביר 1 כדי לעגל את הסכום.
withholding_tax		לא	סכום קיזוז מס במקור
send_to_customer	1	לא	0- המסמך לא ישלח ללקוח1- המסמך ישלח ללקוח במייל.
no_vat	0	לא	1- הפקת מסמך ללא מע"מ.
english_document	0	לא	1- הפקת מסמך באנגלית
currency	1	לא	מטבע המסמך:1- שקל 2- דולר 3- אירו 4- ליש"ט 5- דולר אוסטרלי 6- פרנק שיווצרי 7- דולר קנדי 8- כתר נורבגי 9- כתר דני 10- כתר שוודי 11- ראנד דרא"פ 12- ין יפני 13- יואן סיני 14- רובל 15- ריאל ברזילאי 16- דולר הונג קונגי 17- דולר סינגפורי 18- באט תאילנדי 19- פזו מקסיקני 20- דולר ניו זילנדי 21- וון דרום קוריאני 22- רופי הודי 23- זלוטי 24- קונה 25- כתר צ'כי
customer		כן	שדה שמכיל את פרטי הלקוח – ראה מבנה שדות לקוח בהמשך.
items		לא	שדה המכיל רשימה של הפריטים במסמך. אין להעביר במידה וסוג המסמך הינו קבלה.ראה מבנה שדות פריטים בהמשך.
payments		לא	שדה המכיל רשימה של התשלומים במסמך. יש להעביר אך ורק במסמכים מסוג 'קבלה', 'חשבונית מס / קבלה' ו'קבלה על תרומה'.ראה מבנה שדות תשלומים בהמשך.
remarks		לא	הערות בתחתית המסמך
profit_center_id		לא	העבר את מזהה מרכז הרווח כדי לשייך אליו את המסמך. ניתן למצוא את המזהה במסך 'הגדרות->מרכזי רווח' בלחיצה על כפתור עריכה של מרכז רווח.

שדות לקוח (customer):

שדה	ברירת מחדל	חובה	תיאור
name		כן	שם הלקוח
address		לא	כתובת
city		לא	עיר
zip_code		לא	מיקוד
identification		לא	ת.ז או ח.פ שיופיעו על גבי המסמך
email		לא	כתובת אימייל
phone_number		לא	טלפון
cell_phone		לא	נייד
fax		לא	פקס
save_customer	0	לא	יש להעביר 1 כדי לשמור את הכרטיס לקוח במערכת.

שדות פריטים (items):

שדה	ברירת מחדל	חובה	תיאור
description		כן	תיאור הפריט
item_number		לא	מספר פריט או מספר קטלוגי – במידה
price		כן	מחיר הפריט
quantity	1	לא	כמות. המחיר הסופי של השורת פירוט יהיה: מחיר * כמות
currency	1	לא	ראה קודים של מטבעות בטבלת שדות כלליים
currency_rate	שער נוכחי	לא	שער מטבע במידה ונבחר מטבע השונה משקל. אין צורך לספק שער מטבע- המערכת תשתמש בשער הנוכחי לפי בנק ישראל.
no_vat	0	לא	יש להעביר 1 במידה והפריט הוא ללא מע"מ.
discount_pct		לא	הנחה באחוזים. לדוגמא, יש להעביר 10 עבור 10% הנחה.

שדות תשלומים (payments):

שדה	ברירת מחדל	חובה	תיאור
payment_date		כן	תאריך שבו בוצע התשלום או תאריך פרעון של המחאה. בפורמט dd/MM/yyyy
payment_type		כן	סוג תשלום:1- העברה בנקאית 2- מזומן 3- המחאה 4- כרטיס אשראי 5- פייפאל 6- אפליקציה 9- אחר
amount		כן	סכום התשלום
bank_account		לא	מספר חשבון (חובה בתשלום המחאה)
bank_branch		לא	סניף (חובה בתשלום המחאה)
bank		לא	בנק (חובה בתשלום המחאה)
cheque_number		לא	מספר המחאה (חובה בתשלום המחאה)
credit_card_type		לא	סוג כרטיס אשראי:1- אמריקן אקספרס 2- דיינרס 3- ויזה 4- ישראכרט 5- לאומי קארד 6- מאסטרקארד
credit_card_4_digits		לא	4 ספרות אחרונות של הכרטיס אשראי
credit_transaction_type		לא	סוג התשלום בכרטיס אשראי: (חובה בתשלום מסוג כרטיס אשראי)1- רגיל 2- תשלומים 3- קרדיט 4- חיוב נדחה 5- אחר
number_of_payments		לא	מספר תשלומים בכרטיס אשראי (חובה במידה וסוג התשלום בכרטיס אשראי הוא תשלומים)
first_payment_amount		לא	סכום תשלום ראשון בכרטיס אשראי
payments_one_row	0	לא	יש להעביר 1 במידה ואין צורך בהצגת פירוט התשלומים בכרטיס אשראי על גבי המסמך
paypal_account_number		לא	מספר חשבון פייפאל
paypal_transaction_number		לא	מספר טרנזאקציה בפייפאל
application_type		לא	סוג כרטיס אשראי:1- Bit 2- PayBox 3- Pay 4- Apple Pay 5- Colu
application_account_number		לא	מספר חשבון אפליקציה
application_transaction_number		לא	מספר עסקה באפליקציה
other_type_desc		לא	סוג תשלום אחר

ולידציה: ניכוי מס במקור (withholding_tax)

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

סכום התשלומים + ניכוי מס במקור = סה"כ המסמך

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

לדוגמה: תקבול נטו של 6,341.70 ₪ עם ניכוי מס במקור של 129.42 ₪ ⇐ סה"כ המסמך חייב להיות 6,471.12 ₪.

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

שדה	תיאור
status_code	קוד סטטוס שגיאות. במידה והכל תקין יוחזר 0.
status_description	תיאור השגיאה. במידה והכל תקין יוחזר 'OK'.
doc_no	מספר המסמך שנוצר.
pdf_original	קישור למסמך המקור.
pdf_copy	קישור למסמך העתק.

מדריך API – הפקת מסמכים

ולידציה: ניכוי מס במקור (withholding_tax)

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

הצטרפות