מדריך מפתחים

API לינט

הקדמה, הסבר ודוגמאות למהות ה-API:

ייעודו של ה-API הוא לשמש תשתית למשתמשי תוכנות עסקיות אחרות (כגון ERP, CMS, CRM וכדומה) החפצים לממשק את התוכנות הללו אל לינט הנה"ח בממשק שהוא גם אוטומאטי, גם בזמן אמת וגם דו כיווני.

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

א. האתר יתחבר לתוכנת לינט (יבצע login) באמצעות פקודת login ב-API.

ב. האתר יפעיל פקודת GET ב-API לקריאת שם הלקוח על מנת לבדוק אם הוא קיים בלינט. במידה ולא: האתר יפעיל פקודת NEW ב-API על מנת ליצור את שם הלקוח ויזין את פרטיו. ובמידה והוא קיים, יעדכן פרטיו באמצעות פקודת UPDATE ב-API.

ג. האתר יפעיל פקודת GET ב-API לקריאת שם המוצר על מנת לבדוק אם הוא קיים בלינט. במידה ולא: האתר יפעיל פקודת NEW ב-API על מנת ליצור את שם המוצר/השירות ויזין את פרטיו. ובמידה והוא קיים, יעדכן פרטיו באמצעות פקודת UPDATE ב-API.

ד. האתר יפעיל פקודת NEW ב-API להפקת חשבונית עם פרטי הלקוח, המוצר, מחיר המוצר, כמות וכדומה.

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

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

 מדריך שימוש API למפתחים:

 הדגמה במדריך זה נעשית בGET על מנת לפשט את הקריאה, פקודות הAPI תומכות בGET וב POST אך מומלץ להשתמש בPOST ובמיוחד לפקודות הארוכות.

כמו כן כל פקודות הAPI תומכות בפרמטר jsoncallback על מנת לקבל מזהה ייחודי לפקודה.

ניתן למצוא ישום למופת לAPI כאן

Login

על מנת להשתמש בAPI עלינו לקבל SESSION מהשרת ועושים זאת על ידי קריאה ל Login בשרת שעובדים מולו קריאה לLogin מצריכה 2 פרמטרים בסיסים: שם משתמש ומפתח תוכנה (ניתן לראות מפתח תוכנה במסך "ערוך פירטי משתמש" מהתפריט "דף ראשי"):

action=login

username=SomeUser@name

appKey=esgry5erdgfju7ti

./api.php?action=Login&username=SomeUser@name&appKey=esgry5erdgfju7ti

פלט אפשרי:

({"sid":"a867…56a75b8c"})    כניסה תקינה.

({"sid":"-1"})        מפתח תוכנה או שם משתמש אינם תקינים.

Logout

נשתמש בפקודה על מנת לחסל SESSION.

./api.php?action=Logout

פלט אפשרי:

({"sid":"-2"}) משתמש לא מחובר(נותק).

Get

נשתמש בGet על מנת למשוך נתונים מהתוכנה ועל מנת למשוך את מבני הנתונים מהתוכנה . הפקודה זקוקה לטיפוס הנתונים שאותו רוצים לקבל ומספר מזהה על מנת למשוך מידע ספציפי:

action=Get

data=Item,Account,Document

num=somenumber

./api.php?action=Get&data=Item

פלט אפשרי:

({"num":null,"prefix":"","account":"","name":"","unit":"","extcatnum":"","manufacturer":"","defprice":"","currency":"","ammount":""}) מבנה נתונים: "פריט" שלא נקבע עבורו num

({"data":"-2"}) מבנה נתונים לא ידוע

New

נשתמש בNew על מנת ליצור רשומה חדשה. מאוד מומלץ לקבל לפני כן את מבנה הנתונים בעזרת הפקודה Get.

action=Set

data=Item,Account,Document

(recored data)

./api.php?action=Set&data=Item&account=201& name=ZoZuLifa&defprice=40.00&ammont=150

פלט אפשרי:

({"data":somenumber}) נקבל מספר מזהה של הפריט החדש שיצרנו

({"data":false}) פעולה נכשלה

({"data":"-2"}) מבנה נתונים לא ידוע

Update

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

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

action=Set

data=Item,Account,Document

num=number

(recored data)

./api.php?action=Update&data=Item&num=666&defprice=46.00&ammont=100

פלט אפשרי:

({"data":true}) פעולה הצליחה

({"data":false}) פעולה נכשלה

({"data":"-2"})מבנה נתונים לא ידוע

Normal 0 false false false EN-US X-NONE HE MicrosoftInternetExplorer4 /* Style Definitions */ table.MsoNormalTable {mso-style-name:"טבלה רגילה"; mso-tstyle-rowband-size:0; mso-tstyle-colband-size:0; mso-style-noshow:yes; mso-style-priority:99; mso-style-qformat:yes; mso-style-parent:""; mso-padding-alt:0in 5.4pt 0in 5.4pt; mso-para-margin:0in; mso-para-margin-bottom:.0001pt; mso-pagination:widow-orphan; font-size:11.0pt; font-family:"Calibri","sans-serif"; mso-ascii-font-family:Calibri; mso-ascii-theme-font:minor-latin; mso-fareast-font-family:"Times New Roman"; mso-fareast-theme-font:minor-fareast; mso-hansi-font-family:Calibri; mso-hansi-theme-font:minor-latin; mso-bidi-font-family:Arial; mso-bidi-theme-font:minor-bidi;}