הפקת מסמכים ב-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 | לא | ת.ז או ח.פ שיופיעו על גבי המסמך | |
לא | כתובת אימייל | ||
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 | לא | סוג תשלום אחר |
מבנה תשובה המתקבלת מהשרת:
שדה | תיאור |
status_code | קוד סטטוס שגיאות. במידה והכל תקין יוחזר 0. |
status_description | תיאור השגיאה. במידה והכל תקין יוחזר 'OK'. |
doc_no | מספר המסמך שנוצר. |
pdf_original | קישור למסמך המקור. |
pdf_copy | קישור למסמך העתק. |