ה-API של כספית בענן -- שאלות ותשובות

כיצד מבצעים קישור בין הלקוח לבין החשבונית?

הדרך הנכונה היא זו:
1. ליצור את הלקוח דרך ה-API.
אם תעביר מפתח בשדה ContactId של CaspitContact אז כספית תשתמש בו. אם תשלח null או שתשאיר את השדה ריק אז כספית תייצר עבורך מפתח ותחזיר לך אותו בתשובה.
שם לב: אם קיים לקוח עם המפתח שהעברת לכספית, אז כספתי תעדכן את הלקוח הקיים ולא תיצור לקוח חדש.
2. ליצור את החשבונית דרך ה-API. בעת יצירת החשבונית להעביר בשדה CustomerId ב-CaspitDocument את המפתח שהשתמשת בו (או שקיבלת מכספית).
בעת יצירת החשבונית עליך להעביר את פרטי הלקוח (שם, כתובת, מספר ע"מ) גם בשדות המתאימים באוביקט החשבונית.
מדוע? ראה השאלה הבאה.

מדוע אני צריך להעביר את פרטי הלקוח בחשבונית גם אם שלחתי מפתח של לקוח קיים? מדוע כספית לא שולפת את הפרטים מרשומת הלקוח?

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

ביצירה של קבלה חדשה לא מצאתי שדה להזנת ה ID של הלקוח בכספית או המפתח הזר של הלקוח

השתמש בשדה CustomerId ב-CaspitDocument.

האם זה תקין ליצור מסמך ללא הקישור ללקוח ספצפי בכספית?

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

בעת יצירת חשבונית אילו פרטים מועתקים מכרטיס הלקוח לחשבונית?

כספית לא מעתיקה פרטים מכרטיס הלקוח, ואם לא תשלח אותם אז כספית תותיר את השדות (שם העסק, שם איש הקשר, כתובת, טלפון וכו') ריקים.')

האם השדה RowVersion משמש רק עבור עדכון המסמך בכספית? מה אתה ממליץ להעביר בשדה זה?

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

יצרתי מסמך חדש דרך ה-API. מדוע המספר שלו לא ברצף למסמכים הקיימים בכספית?

כספית מאפשרת ליצור סדרות של מסמכים. כלומר אתה יכול ליצור סידרה 01 לסניף א' של העסק, וסידרה נפרדת 02 לסניף ב' של העסק. ואז במסמכים ימוספרו כך:
סניף א' -- 01/2001, 01/2002
סניף ב' -- 02/2001, 02/2002
מספר הסידרה של משתמש ה-API מאותחל לערך 98. אתה יכול לשלוח את מספר הסניף הרצוי לך דרך ה-API.
כלומר מסמכים שנוצרים כברירת מחדל מן ה-API הם תמיד מסידרה 98: 98/200001, 98/300001 וכו'
את מספר הסניף שלח בשדה DocumentNumberBranch של האוביקט CaspitDocument.

יצרתי מסמך דרך ה-API. מדוע הוא מוצג בצבע אדום?

הצבע של מספר המסמך מסמן את הסטטוס שלו:

• אדום = חדש, לא הודפס
• ירוק = הודפס ונעול לעריכה
• סגול = מבוטל

לאחר שתדפיס את המסמך (ישירות מכספית, או דרך ה-API) הוא ינעל לעריכה והצבע שלו ישתנה מאדום לירוק.

האם אפשר להדפיס מסמך דרך ה-API?

אין אפשרות "להדפיס" מסמך במובן של משלוח שלו למדפסת.
בכדי להדפיס אותו במדפסת מקומית של המשתמש תצטרך "להדפיס" אותו במובן של יצירת מסמך PDF, ואז לשלוח את ה-PDF למדפסת מקומית.
ה-API המתאים הוא:
POST api/v1/PrintDocument/{id}?token={token}&documentNumber={documentNumber}&trxTypeId={trxTypeId}&lan={lan}&createSignedPdf={createSignedPdf}
הקריאה תחזיר לך את ה-PDF שנוצר ב-body של התשובה. ה-body יכיל את הבתים של ה-PDF ועליך לשמור אותם לקובץ.
בנוסף הקריאה תחזיר לך URL להצגת מסמך ה-PDF בשדה location ב-header של התשובה.

כיצד אפשר לשלוף את ה-PDF של מסמך שהודפס?

השתמש ב-API הבא:
GET api/v1/Pdf/{id}?token={token}&documentNumber={documentNumber}&trxTypeId={trxTypeId}&lan={lan}
הקריאה תחזיר לך את הבתים של ה-PDF (לא לינק אלא המסמך עצמו).

כיצד אפשר לשלוח מסמך במייל?

השתמש ב-API הבא:
EMAIL api/v1/Documents/{id}?token={token}&documentNumber={documentNumber}&trxTypeId={trxTypeId}&lan={lan}

הצלחתי ליצור חש/ק אבל אני מקבל את יתרת הלקוח במסמך
איך אני יכול לא להציג את יתרת הלקוח

היכנס לתחזוקה, עיצוב מסמכים.
הלשונית סה"כ של המסמך ומתחתיו, הסר את הסימון מהדפס יתרת לקוח:

אני רוצה לשלוף לקוח אבל אין לי ה-id שלו, אלא רק מספר עוסק מורשה

שלוף את הלקוח באמצעות הע"מ שלו
https://app.caspitweb.biz/api/v1/Contacts/?osekmorshe=234567777&d=1&token=[TOKEN]

לפרמטר d אין משמעות, אבל חייבים לצרף אותו בכדי שהקריאה תעבוד נכון.
כספית תחזיר לך את כל הנתונים של הלקוח כולל ה-ID שלו.

יש המון דוגמאות כאן:
http://www.caspitweb.biz/Content/misc/Api%20Examples%201.txt

כיצד אפשר לעדכן את ה-id של לקוח בכספית?

אתה לא יכול לעדכן את ה-ID של ה-Contact.
כאשר הוא נוצר, לדוגמה מפעולה ידנית של המשתמש בתוך כספית, כספית נתנה לו ID יחודי.
לאחר שתשלוף אותו באמצעות מספר ע"מ שלו,
תוכל לעדכן במערכת שלך את ה-ID שכספית נתנה ל-contact ונכאן והלאה תוכל להשתמש בו לעדכון הפרטים של הלקוח בכספית.

מה ההבדל בין TrxTypeId לבין TrxCodeNumber?
מה הערכים שצריך לשלוח בסוגי המסמכים השונים?

TtrxTypeId הוא סוג המסמך: חשבונית מס, חש/קבלה, קבלה וכו'.
TrxCodeNumber הוא סיווג התנועה של המסמך. כספית מגיעה עם מספר סיווגי תנועה מוכנים. נציין שניים חשובים: 3-מכירות/הכנסות, 2-קבלות.
המשתמש יכול להוסיף סיווגים משלו על מנת להבחין בין חשבוניות מסוגים שונים של הכנסות.

הטבלה הבאה מציגה את הערכים שיש לשלוח לכספית בהנחה שהמשתמש לא הוסיף סיווגי תנועה משלו.

שם המסמך	TrxTypeId	TrxCodeNumber
חשבונית מס	1	3
חשבונית/קבלה	7	3
חשבונית עסקה	6	3
חשבונית זיכוי	9	3
תעודת משלוח	15	3
קבלה	2	2
קבלה לתרומה	19	2
תעודת החזר	13	2

אני מייצר מסמך חדש (לדוגמה, חשבונית מס) דרך ה API. מה צריך לרשום בשדה "*מפתח של המסמך"?

ה-API של כספית עובד כך:
אתה שולח לו נתונים של הישות (מסמך, לקוח) ואופציונאלית גם את המפתח שאתה רוצה להשתמש בו בכדי לשלוף את הישות שנוצרה'.

לכן ישנן שתי אפשרויות:

אם אתה רוצה שכספית תייצר מפתח עבורך –
השאר את השדה NULL. כספית תייצר מפתח שהוא GUID, לדוגמה: f3a6f8e6-1933-48ca-af1d-8c4aaa033545
אם אתה רוצה לעדכן את המסמך בעתיד, אז שמור את המפתח שתקבל בתשובה של כספית.

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

כיצד כספית מאפשרת מסמכים במט"ח

בכספית יש גישה מעורבת בתמיכה במט"ח. היא נובעת מההיסטוריה שבה פותחה התמיכה הזו:
חשבוניות -- כל שורת חשבונית יכולה להכיל מטבע שונה ושער חליפין שונה.
קבלות -- יש רק מטבע אחד ושער חליפין אחד משותפים לכל שורות הקבלה.
חשבוניות/קבלה -- בחלק שורות החשבונית אפשר לתת מטבע שונה ושער חליפין שונה לכל שורה. בחלק הקבלה יש רק מטבע אחד ושער חליפין אחד זהה לכל שורות הקבלה. אין חובה ששער החליפין והמטבע יהיו זהים בין חלק החשבונית לחלק הקבלה. אבל חובה שהסכום הכללי בש"ח יהיה זהה בין חלק החשבונית לחלק הקבלה.

בעת יצירה של חשבונית ובה שורות חשבונית במט"ח, מהיכן נשלף שער החליפין?

המטבע ושער החליפין נלקחים מהנתונים (שורות החשבונית) שאתה שולח ל-API. ברירת המחדל היא ש"ח ו-1.00.
כלומר, אם תשלח מטבע $, אבל לא תשלח שער חליפין אז כספית תקבע את שער החליפין ב-1.00.
בכדי להקל עליך אתה יכול לשלוף את שער החליפין מכספית לפני יצירת הקבלה.

בעת יצירה של קבלה עבור תשלום במט"ח, מהיכן נשלף שער החליפין?

המטבע ושער החליפין נלקחים מהנתונים (ReceiptRate, ReceiptCurrencySymbol) שאתה שולח ל-API. ברירת המחדל היא ש"ח ו-1.00.
כלומר, אם תשלח מטבע $, אבל לא תשלח שער חליפין אז כספית תקבע את שער החליפין ב-1.00.
בכדי להקל עליך אתה יכול לשלוף את שער החליפין מכספית לפני יצירת הקבלה.