לכספית API המאפשר לך ליצור לקוחות ומסמכים ממערכת חיצונית.

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

לכספית API המאפשר לך ליצור לקוחות ומסמכים ממערכת חיצונית.

ה-API מבוסס על טכנולוגית Web API. בקצרה, התקשורת עם כספית נעשית באמצעות משלוח של הודעות HTTP כמו GET, POST, PUT ו-DELETE.

התשובות מתקבלות גם כן כהודעות HTTP המכילות את המידע הרלוונטי.

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

ה-API מבוסס על טכנולוגית Web API. שולחים לכספית GET, POST, PUT ו-DELETE

בכדי לנסות את ה-API של כספית בצע את הצעדים הבאים:

  1. בקש אסימון מכספית -
    גלוש ל- https://app.caspitweb.biz/api/v1/token?user=demo&pwd=demodemo&osekmorshe=123456789
    שם המשתמש והסיסמה שבלינק הם של חשבון הדמו של כספית Web.

  2. המערכת תשלח לך אסימון (TOKEN). האסימון הוא בפורמט GUID. לדוגמא, 90ddaeb7-51d6-4eb5-85a2-4cdaae401ced

  3. עתה שלוף את אנשי הקשר. השתמש בלינק הבא, אבל החלף את האסימון באסימון שקיבלת בשלב הקודם:
    https://app.caspitweb.biz/api/v1/contacts?token=90ddaeb7-51d6-4eb5-85a2-4cdaae401ced

    תקלה אפשרית: אם לא תחליף את האסימון שבלינק תקבל הודעת שגיאה שהאסימון אינו ולידי. נסה שוב עם אסימון חדש.

  4. המערכת תשלח לך רשימה של אנשי קשר מכספית.
    הרשימה תוחזר בפורמט XML או בפורמט JSON לפי הבקשה ששלח הדפדפן שלך.

ברכות! זה עתה השלמת את הטרנזקציה הראשונה דרך ה-API.

בכדי לבדוק את ה-API תוכל להשתמש בחשבון הדמו של כספית Web.
שם המשתמש: demo, סיסמה: demodemo

אם תשתמש ב-IE ולא בכרום יתכן שתקבל את התוצאות בפורמט json ולא בפורמט XML.
מדוע? הבעיה אינה בכספית, אלא בדפדפן. יש הסבר במדריך למשתמש.

לרשותך המשאבים הבאים:

שאלות ותשובות

ביצירה של קבלה חדשה לא מצאתי שדה להזנת ה 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 וכו'

יצרתי מסמך דרך ה-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-קבלות.
המשתמש יכול להוסיף סיווגים משלו על מנת להבחין בין חשבוניות מסוגים שונים של הכנסות.

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

שם המסמךTrxTypeIdTrxCodeNumber
חשבונית מס13
חשבונית/קבלה73
חשבונית עסקה63
חשבונית זיכוי93
תעודת משלוח153
קבלה22
קבלה לתרומה192
תעודת החזר132

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

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

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

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

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