הפקת מסמכים ב-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-   ראנד דרא"פ

customer   כן שדה שמכיל את פרטי הלקוח – ראה מבנה שדות לקוח בהמשך.
items   לא שדה המכיל רשימה של הפריטים במסמך. אין להעביר במידה וסוג המסמך הינו קבלה.  

ראה מבנה שדות פריטים בהמשך.

payments   לא שדה המכיל רשימה של התשלומים במסמך. יש להעביר אך ורק במסמכים מסוג 'קבלה', 'חשבונית מס / קבלה' ו'קבלה על תרומה'.  

ראה מבנה שדות תשלומים בהמשך.

remarks   לא הערות בתחתית המסמך

שדות לקוח (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 במידה והפריט הוא ללא מע"מ.

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

שדה ברירת מחדל חובה תיאור
payment_date   כן תאריך שבו בוצע התשלום או תאריך פרעון של המחאה. בפורמט dd/MM/yyyy
payment_type   כן סוג תשלום:  

1-     העברה בנקאית

2-     מזומן

3-     המחאה

4-     כרטיס אשראי

5-     פייפאל

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   לא מספר טרנזאקציה בפייפאל

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

 

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

 

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

נשמח לתת מענה לכל בעיה והתלבטות.
צוות התמיכה עושה הכל כדי לספק מענה מהיר.
אנחנו כאן.

טופס פניה לתמיכה
אזור תוכן, לקיצור דרך לחצ/י כפתור ALT + zאזור פוטר, לקיצור דרך לחצ/י כפתור ALT + x