מסמך דוקומנטציה - API להפקת מסמכים במערכת FINBOT
איך להשתמש ב- API של FINBOT ליצירת מסמכי דוקומנטציה בצורה יעילה וקלה.
הסבר כללי
-
שירות ה API להפקת מסמכי הכנסות במערכת FINBOT זמין לשימוש חופשי לכלל משתמשי האפליקציה
-
באמצעות ה API ניתן לבצע אינטגרציות בין מערכת FINBOT למערכות CRM/ אוטומציות שונות
- בקרוב נשיק תוספים לאתרי מכירה אינטרנטיים, כך שבאמצעות התקנת התוסף באתר מכירה בכל עסקה שתתבצע תופק חשבונית במערכת FINBOT/
לדוגמא: בעל עסק שמוכר מוצרים באתר Shopify (שופיפיי), לאחר שיתקין את התוסף של FINBOT ב Shopify בכל קניה שתתבצע באתר תופק אוטומטי חשבונית מס קבלה ב FINBOT הכוללת את כל פרטי העסקה והתשלום
שירות ה API כולל את כל השדות והלוגיקות הקיימים בתהליך הפקת המסמכים באפליקציה, כגון:
- הפקת כל סוגי המסמכים
- קישור בין מסמכים
- הפקת מסמכים ללקוח קיים/חדש/מזדמן
- הפקת מסמכים עם פריט קיים/חדש/מזדמן
- שליחת המסמך ללקוח/למיילים נוספים לאחר ההפקה
- קבלת חיווי במייל האם המסמך אכן הופק בהצלחה או לא
התחלת עבודה
יש להיכנס באפליקציה ללשונית הגדרות העסק > מפתח API להפקת הכנסות וללחוץ על הכפתור “יצירת מפתח API” ,
לאחר הלחיצה המערכת תיצור עבורכם טוקן API אשר באמצעותו תוכלו להפיק מסמכים ב API
שימו לב! הטוקן הינו סודי ויש לשמור עליו מכל משמר. אל תשתף אותו עם אף אחד וודא שהוא מאוחסן בצורה מאובטחת
לצפייה בתהליך התחלת העבודה באפליקציה לחץ כאן
שירות הפקת מסמכים
:Swagger Documentation Link
https://api.finbotai.co.il/api#/default/IncomeController_creat
:URL
https://api.finbotai.co.il/income
Method: Post
Send the token in a "header" of the request - named secret
Example:
בקשות - Requests:
אובייקט עוטף |
שם השדה |
סוג |
שדה חובה? |
הסבר + תוכן אפשרי |
|---|---|---|---|---|
|
|
כן |
סוג המסמך
חשבונית מס - 0 קבלה - 1 חשבונית מס קבלה - 2 דרישת תשלום - 3 חשבונית זיכוי - 4 הזמנה - 5 תעודת משלוח - 6 הצעת מחיר - 7 חשבונית - 8 |
|
|
|
כן |
תאריך המסמך
פורמט: DD/MM/YYYY 20/09/2024 וכדו' |
|
|
|
כן |
שפת המסמך
עברית - he אנגלית - en |
|
|
|
כן |
מטבע
שקל - ILS דולר - USD אירו - EUR ליש"ט - GBP יין יפני - JPY פרנק שוויצרי - CHF יואן סיני - CNY דולר אוסטרלי - AUD דולר קנדי - CAD ריאל ברזילאי - BRL דולר סינגפורי - SGD כתר שבדי - SEK כתר נורבגי - NOK כתר דני - DKK זלוטי - PLN ראנד דרא״פ - ZAR לירה מצרית - EGP דינר ירדני - JOD |
|
|
|
כן |
עיגול סכומים
כן - true לא - false |
|
|
|
כן |
מסמך כולל/ לא כולל מע"מ
כולל מע"מ - true ללא מע"מ - false |
|
|
|
לא |
תיאור המסמך
עד 200 תווים |
|
|
|
לא |
הערות
עד 1500 תווים |
|
|
|
לא |
כמות הנחה
רק מספרים שלמים
במידה ו"סוג ההנחה" הוא סכום: 0 - 99999999 במידה ו"סוג ההנחה" הוא אחוז: 0 - 100 |
|
|
|
כן - במידה ושדה כמות הנחה מכיל ערך |
סוג ההנחה
סכום - 1 אחוז - 2 |
|
|
|
לא |
כותרת למסמך (לשימוש עצמי)
עד 100 תווים |
|
|
|
לא |
כותרת המייל
עד 100 תווים |
|
|
|
לא |
טקסט לצירוף למייל
עד 300 תווים |
|
|
|
לא |
כתובות מייל נוספות לשליחת החשבונית, במידה ורוצים לשלוח כמה כתובות יש להפריד בין הכתובות עם פסיק
עד 999 תווים |
|
פרטי לקוח |
|
|
לא |
מספר סידורי של הלקוח - במידה והמסמך מופק עבור לקוח קיים |
|
|
כן, אלא א"כ שדה מספר סידורי מכיל ערך |
שם לקוח
עד 100 תווים |
|
|
|
לא |
מייל לקוח
עד 50 תווים |
|
|
|
לא |
טלפון לקוח
עד 20 תווים |
|
|
|
לא |
כתובת לקוח
עד 100 תווים |
|
|
|
לא |
ח.פ./ מספר עוסק
עד 9 תווים |
|
|
|
לא |
שם לקוח נוסף - לשימוש עצמי
עד 100 תווים |
|
|
|
לא - ברירת מחדל true |
האם לשמור את הלקוח ברשימת הלקוחות/ המסמך יופק על לקוח מזדמן
כן - true לא - false |
|
|
פריטים [מערך]
במקרה של מסמך קבלה זאת קטגוריית רשות |
|
|
לא |
מספר סידורי של הפריט - במידה והמסמך מופק עבור פריט קיים |
|
|
כן, אלא א"כ שדה מספר סידורי מכיל ערך |
שם פריט
עד 100 תווים |
|
|
|
כן |
כמות 1 - 99999 |
|
|
|
לא, ברירת מחדל false |
האם לשמור את הפריט ברשימת הלקוחות/ המסמך יופק עם פריט מזדמן
כן - true לא - false |
|
|
|
כן, אלא א"כ סוג המסמך הוא תעודת משלוח ואז זה לא שדה חובה. |
מחיר ליחידה
יש לרשום את המחיר לפני מע"מ!
עד 9999999 - כולל מספר עשרוני |
|
|
אמצעי תשלום [מערך]
רלוונטי רק למסמך מסוג חשבונית מס קבלה/ קבלה |
|
|
כן |
סוג האמצעי תשלום
מזומן - 0 העברה בנקאית - 1 אשראי - 2 צ'ק - 3 ניכוי במקור מלקוחות - 4 פייפאל - 5 ביטקוין - 6 אחר - 7 ביט - 8 פייבוקס - 9 ניכויים אחרים - 10 אתריום - 11 שווה כסף - 12 שובר מתנה - 13 גוגל פיי - 14 אפל פיי - 15 |
|
|
כן |
תאריך התשלום
פורמט: DD/MM/YYYY 20/09/2024 וכדו' |
|
|
|
כן |
סכום
עד 9999999 - כולל מספר עשרוני |
|
|
|
כן - רק במידה ואמצעי התשלום הוא צ'ק |
מספר בנק (לקוח) |
|
|
|
כן - רק במידה ואמצעי התשלום הוא צ'ק |
מספר סניף (לקוח) |
|
|
|
כן - רק במידה ואמצעי התשלום הוא צ'ק |
מספר חשבון (לקוח) |
|
|
|
כן - רק במידה ואמצעי התשלום הוא צ'ק |
מספר צ'ק
עד 20 תווים |
|
|
|
כן - רק במידה ואמצעי התשלום הוא אשראי |
4 ספרות של מספר כרטיס אשראי
עד 4 תווים |
|
|
|
כן - רק במידה ואמצעי התשלום הוא אשראי |
מספר תשלומים
עד 3 תווים |
|
|
|
לא |
מספר העסקה
עד 40 תווים |
|
|
|
לא |
כולל מספר הקצאה
כן - true לא - false
במסמך מסוג חשבונית מס/ חשבונית מס קבלה מעל 25 אלף לפני מע"מ (בשנת 2024) זה אוטומטי יבקש מספר הקצאה |
|
|
|
לא, אא"כ מסמך מסוג חשבונית זיכוי |
מקושר למסמך
המספר סידורי (לא אסמכתא) של המסמך שאליו המסמך הזה מקושר |
|
|
|
כן - רק במסמך מסוג חשבונית זיכוי |
סכום לזיכוי, הסכום שבו תופק החשבונית זיכוי |
תגובות - Responses:
שם השדה |
הסבר + תוכן אפשרי |
|---|---|
|
האם המסמך הופק בהצלחה
1 - המסמך הופק בהצלחה |
|
הודעת הצלחה/ שגיאה |
|
לינק למסמך המקור שהופק
נשלח רק במידה והמסמך אכן הופק - סטטוס 1 |
|
מערך שמציג את השגיאות שהתקבלו: (אובייקט של מספר שגיאה + טקסט)
נשלח רק במידה והמסמך לא הופק |
רשימת שגיאות - Errors:
- במידה והטוקן API או השם משתמש לא נכונים אנחנו מחזירים 401, כל השגיאות שלהלן זה רק אם הם נכונים ואז חוזר 200 עם השגיאה בגוף הפלט.
- ערך לא תקין = או שפורמט הערך לא תקין (סטרינג במקום בוליאני וכדו') או שהוכנס ערך לא קיים לדוגמא: בסוג מטבע לרשום AAA.
המקרה |
מספר שגיאה |
טקסט השגיאה |
|---|---|---|
המשרד לא פעיל/ הלקוח לא פעיל |
|
המשתמש אינו פעיל, יש לפנות לתמיכה בטלפון *6453 |
משרד שמוגדר חיוב קצה וללקוח אין אשראי |
|
לא קיים למשתמש אמצעי תשלום תקין, יש לעדכן באפליקציה את אמצעי התשלום |
ערך לא תקין בשדה סוג המסמך |
|
הערך בשדה type אינו תקין |
לא נשלח שדה סוג המסמך |
|
שדה type הינו שדה חובה |
המשתמש עוסק פטור והוקלד ערך של 0/ 2/ 4/ 8 בשדה סוג המסמך |
|
עוסק פטור אינו יכול להפיק את סוג המסמך המבוקש |
הוקלד ערך של 4 בשדה סוג המסמך ולא נבחר מסמך לקישור בשדה "מקושר למסמך" |
|
לא ניתן להפיק חשבונית זיכוי ללא קישור לחשבונית מס/ חשבונית מס קבלה |
ערך לא תקין בשדה תאריך |
|
הערך בשדה date אינו תקין |
לא נשלח שדה תאריך |
|
שדה date הינו שדה חובה |
מנסים להפיק מסמך לחודש מסויים שהמע"מ שלו בסטטוס סגור/ שודר/ שולם |
|
שובר המע"מ של חודש זה שודר |
ערך לא תקין בשדה שפה |
|
הערך בשדה language אינו תקין |
לא נשלח שדה שפה |
|
שדה language הינו שדה חובה |
ערך לא תקין בשדה מטבע |
|
הערך בשדה currency אינו תקין |
לא נשלח שדה מטבע |
|
שדה currency הינו שדה חובה |
ערך לא תקין בשדה כולל/ לא כולל מע"מ |
|
הערך בשדה vatType אינו תקין |
לא נשלח שדה כולל/ לא כולל מע"מ |
|
שדה vatType הינו שדה חובה |
המשתמש עוסק פטור והוקלד ערך TRUE |
|
עוסק פטור אינו יכול לבחור בשדה vatType סכום כולל מע"מ |
ערך לא תקין בשדה עיגול סכומים |
|
הערך בשדה rounding אינו תקין |
לא נשלח שדה עיגול סכומים |
|
שדה rounding הינו שדה חובה |
ערך לא תקין בשדה תיאור המסמך |
|
הערך בשדה description אינו תקין |
ערך לא תקין בשדה הערות |
|
הערך בשדה remark אינו תקין |
ערך לא תקין בשדה סוג ההנחה |
|
הערך בשדה discountType אינו תקין |
הוקלד ערך בשדה סוג ההנחה למרות ששדה כמות הנחה לא מכיל ערך |
|
נבחר סוג הנחה אך לא נבחר סכום הנחה |
ערך לא תקין בשדה כמות הנחה |
|
הערך בשדה discountAmount אינו תקין |
הוקלד ערך בשדה כמות הנחה למרות ששדה סוג ההנחה לא מכיל ערך |
|
נבחר כמות הנחה אך לא נבחר סוג הנחה |
ערך לא תקין בשדה מקושר למסמך |
|
הערך בשדה linkedDocument אינו תקין |
לא נמצא מסמך עם מספר סידורי שהוקלד בשדה "מקושר למסמך" |
|
לא נמצא מסמך לקישור המכיל את המספר סידורי המבוקש |
המסמך שנבחר בשדה "מקושר למסמך" הוא מסמך שלא ניתן לקשר (למשל קישור קבלה לקבלה) |
|
לא ניתן לקשר את המסמך למסמך שנבחר לקישור |
ערך לא תקין בשדה כותרת למסמך |
|
הערך בשדה titleDocument אינו תקין |
ערך לא תקין בשדה כותרת המייל |
|
הערך בשדה subject אינו תקין |
ערך לא תקין בשדה טקסט לצירוף למייל |
|
הערך בשדה body אינו תקין |
ערך לא תקין בשדה כתובות מייל נוספות |
|
הערך בשדה emailContent אינו תקין |
ערך לא תקין בשדה כולל מספר הקצאה |
|
הערך בשדה confirmationNumber אינו תקין |
הוקלד true/ ברירת מחדל true בשדה כולל מספר הקצאה וסוג המסמך הוא לא חשבונית מס / חשבונית מס קבלה |
|
לא ניתן לבקש מספר הקצאה עבור סוג המסמך המבוקש |
הוקלד true/ ברירת מחדל true בשדה כולל מספר הקצאה ושדה מספר עוסק לא נשלח/ מספר הסידורי של הלקוח לא מכיל ח.פ. |
|
לא ניתן לבקש מספר הקצאה ללא מספר עוסק של הלקוח |
הוקלד true/ ברירת מחדל true בשדה כולל מספר הקצאה והלקוח לא מחובר לרשות המיסים |
|
שגיאה בקבלת מספר הקצאה - המשתמש אינו מחובר לרשות המיסים |
הוקלד true/ ברירת מחדל true בשדה כולל מספר הקצאה וחזרה שגיאה מרשות המיסים |
|
שגיאה בקבלת מספר הקצאה - {הטקסט של השגיאה שהתקבלה מרשות המיסים} |
ערך לא תקין בשדה מספר סידורי של הלקוח |
|
הערך בשדה client > id אינו תקין |
לא נמצא לקוח שמכיל את המספר סידורי שהוקלד בשדה "מספר סידורי של הלקוח" |
|
לא נמצא לקוח המכיל את המספר סידורי המבוקש |
ערך לא תקין בשדה שם לקוח |
|
הערך בשדה client > name אינו תקין |
לא נשלח שדה שם לקוח ולא נשלח מספר סידורי של לקוח |
|
שדה client > name הינו שדה חובה |
ערך לא תקין בשדה טלפון לקוח |
|
הערך בשדה client > phone אינו תקין |
ערך לא תקין בשדה כתובת לקוח |
|
הערך בשדה client > address אינו תקין |
ערך לא תקין בשדה ח.פ./ מספר עוסק |
|
הערך בשדה client > tax אינו תקין |
ערך לא תקין בשדה שם לקוח נוסף - לשימוש עצמי |
|
הערך בשדה client > nickname אינו תקין |
ערך לא תקין בשדה להוסיף את הלקוח/ לקוח מזדמן |
|
הערך בשדה client > save אינו תקין |
ערך לא תקין בשדה מספר סידורי של הפריט |
|
הערך בשדה items > id אינו תקין |
לא נמצא פריט שמכיל את המספר סידורי שהוקלד בשדה "מספר סידורי של הפריט" |
|
לא נמצא פריט המכיל את המספר סידורי המבוקש |
ערך לא תקין בשדה שם פריט |
|
הערך בשדה items> name אינו תקין |
לא נשלח שדה שם פריט ולא נשלח מספר סידורי של הפריט |
|
שדה items > name הינו שדה חובה |
ערך לא תקין בשדה כמות |
|
הערך בשדה items > amount אינו תקין |
לא נשלח שדה כמות |
|
שדה items > amount הינו שדה חובה |
ערך לא תקין בשדה מחיר ליחידה |
|
הערך בשדה items > price אינו תקין |
לא נשלח שדה מחיר ליחידה |
|
שדה items > price הינו שדה חובה |
ערך לא תקין בשדה להוסיף את הפריט/ פריט מזדמן |
|
הערך בשדה items > save אינו תקין |
ערך לא תקין בשדה סוג האמצעי תשלום |
|
הערך בשדה payments > type אינו תקין |
לא נשלח שדה סוג האמצעי תשלום |
|
שדה payments > type הינו שדה חובה |
ערך לא תקין בשדה תאריך התשלום |
|
הערך בשדה payments > date אינו תקין |
לא נשלח שדה תאריך התשלום |
|
שדה payments > date הינו שדה חובה |
ערך לא תקין בשדה מספר בנק (לקוח) |
|
הערך בשדה payments > bankName אינו תקין |
לא נשלח שדה מספר בנק (לקוח) והאמצעי תשלום הוא צ'ק |
|
שדה bankNamepayments > הינו שדה חובה |
ערך לא תקין בשדה מספר סניף (לקוח) |
|
הערך בשדה payments > bankBranch אינו תקין |
לא נשלח שדה מספר סניף (לקוח) והאמצעי תשלום הוא צ'ק |
|
שדה payments > bankBranch הינו שדה חובה |
ערך לא תקין בשדה מספר חשבון (לקוח) |
|
הערך בשדה payments > bankAccount אינו תקין |
לא נשלח שדה מספר חשבון (לקוח) והאמצעי תשלום הוא צ'ק |
|
שדה payments > bankAccount הינו שדה חובה |
ערך לא תקין בשדה מספר צ'ק |
|
הערך בשדה payments > numberCheck אינו תקין |
לא נשלח שדה מספר צ'ק והאמצעי תשלום הוא צ'ק |
|
שדה payments > numberCheck הינו שדה חובה |
ערך לא תקין בשדה מספר כרטיס אשראי |
|
הערך בשדה payments > cardNumber אינו תקין |
לא נשלח שדה מספר כרטיס אשראי והאמצעי תשלום הוא אשראי |
|
שדה payments > cardNumber הינו שדה חובה |
ערך לא תקין בשדה מספר תשלומים |
|
הערך בשדה payments > numberPayments אינו תקין |
לא נשלח שדה מספר תשלומים והאמצעי תשלום הוא אשראי |
|
שדה payments > numberPayments הינו שדה חובה |
ערך לא תקין בשדה מספר העסקה |
|
הערך בשדה payments > numberTransaction אינו תקין |
הסכום של הפריטים לא תואם לסה"כ של האמצעי תשלום |
|
סכום הפריטים אינו תואם לסכום התקבולים |
הפקת המסמך נכשלה מכל סיבה אחרת שהיא |
|
שגיאה בהפקת המסמך - {השגיאה שחזרה מהשרת} |
תמיכה טכנית
לתמיכה טכנית ניתן לפנות אלינו:
-
בטלפון - *6453 שלוחה 2 > 2
-
בוואטסאפ - 054-9781187
-
באימייל - ask@finbot.co.il
תוכן עניינים
מאמרים קשורים
-
דוח שנתי - איסוף מסמכים
המשך למאמר -
התממשקות API לתוכנות הפקת הכנסות
המשך למאמר -
שליחת הכנסות ידנית ממערכות חיצוניות
המשך למאמר