ממשק API מגרסת SP5 2020 ומעלה
עמוד זה מסביר את מערכת הממשקים לתוכנת החשבשבת בגרסת חלונות כולל הנחיות למתכנתים.
מה זה API?
API הוא ראשי תיבות של Application Programming Interface או בעברית ממשק תכנות יישומים. הוא כולל ספריות קוד פתוח, תקשורת נתונים ועוד, באמצעותן ניתן למשוך מידע או להתחבר למאגר מידע ונתונים של חברה אחרת. חשבשבת מאפשרת את החיבור אליה, על ידי קוד פתוח עבור הנתונים שלה ואף יצרה מאגרי מידע המסבירים את השימוש בקוד ה-API. באופן זה המתכנתים יכולים לחסוך זמן עבודה יקר. אחד היתרונות של ממשקי API הוא האפשרות להעביר מידע לחשבשבת המקומית בדחיפה דרך הדפדפן.
- הערה: לחילופין, ניתן להשתמש בממשקי הקבצים של חשבשבת ללא כל שינוי. הסברים על ממשקים אלה ניתן למצוא באתר חשבשבת בסעיף: מידע לבתי תוכנה.
הסבר לתהליך בחשבשבת
תוכנת חשבשבת עובדת עם שרת MS SQL server המותקן אצל הלקוח. ההתקנה מתבצעת במחשב/שרת מקומי, או בשרת בענן.
ה-API איננו מתקשר ישירות עם שרת הלקוח, אלא עם שרת ייעודי של חברת חשבשבת.
יש תחילה להירשם לשירות בכתובת: https://forms.h-erp.co.il/HConnectSignContract.asp
לאחר הרישום לשירות מתקין חשבשבת ייצור קשר לצורך התקנת התוסף
שירות למתכנת במייל hatmaot@h-erp.co.il (ללא עלות)
- תמיכה טלפונית/זום בתשלום עבור שעות הטמעה במחיר 400 ₪ + מע"מ לשעה (או חלק ממנה)
מסמך זה מסכם את כל הנדרש למתכנתים על מנת להפעיל את ה API ללא כל תמיכה או עזרה. יש לקרוא מסמך זה בעיון. ניתן לשלוח מייל ולציין את שם הלקוח, מספר המנוי, שם הספק (הספק הוא תוכנת צד ג' שמעוניינת להתקשר עם חשבשבת) ולצרף פירוט של בקשת התמיכה.
הגדרות צד לקוח
1. Station ID
על מנת ששרת החשבשבת יזהה את התחנה שעבורה נשלחות קריאות ה-API יש להוסיף לכל קריאה פרמטר של Station, כך שניתן יהיה לזהות לאיזה לקוח אתם מפנים את קריאת ה-API.
לאחר הרישום לשירות ולאחר התקנת התוסף ניתן להיכנס לתפריט – כלים מתקדמים >> פרטי התחברות ל Mobile
יפתח המסך הבא:
2. מזהה חברה – Company
בכל התקנת חשבשבת ניתן לפתוח מספר לא מוגבל של חברות. כדי לזהות את החברה בספריית החברות, אליה נדרשת התממשקות וקריאות ה- API, יש להוסיף פרמטר הנקרא Company . בכניסה לתוכנת חשבשבת, מוצג מסך הכולל את רשימת כל החברות. יש להעתיק את שם הקובץ באנגלית המוצג בספריית החברות:
3. מזהה סוג הממשק – plugin
לפי פרמטר זה יודעים איזה סוג ממשק רוצים לקלוט. לדוגמא, כדי ליצור קבלה בתוכנת חשבשבת, יש לציין את שם הפלאגין kupain כדי לקרוא נתונים מחשבשבת יש להשתמש בפלאג אין בשם Reports.
שמות הממשקים הקיימים Plugin – HESHIN חשבונות, IMOVEIN מסמכים, KUPAIN ממשק קבלות, Movein תנועות יומן, Itemin פריטים, Reports: משיכת נתונים משרת חשבשבת
- תוכן הממשק והשדות הנדרשים מפורטים במסמך Plugin Data – לחץ כאן
4. רישום סוג Plugin לקליטה
לצורך אימות דו כיווני יש להעניק הרשאה לספק לבצע קריאת API מהתחנה המקומית:
יש להיכנס לתפריט. הגדרות >> הגדרות H-Connect ולרשום באחת מתחנות חשבשבת את הנתונים הבאים
4.1. חברה: לקליטת הממשק – חברה מספריית החברות המקומית
4.2. מזהה הספק: ה-ID של קובץ האבטחה, הנמצא בשרת הספק והתקבל מה NETPASSPORT (פירוט בהמשך).
4.3. סוג ממשק לקליטה: סוג Plugin אותו רוצים להפעיל.
הגדרות – צד ספק
לאבטחת המידע יש לבנות מנגנון דו כיווני. כלומר, לא די להגדיר את צד הלקוח ונתוני הלקוח, אלא יש להגדיר גם את צד הספק. לכן, יש להחתים את הנתונים בכל קריאת API, בין אם מעוניינים לקרוא נתונים מתוך מסד הנתונים של חשבשבת, ובין אם מעוניינים לשלוח נתונים למסד הנתונים של חשבשבת.
החתמת הנתונים מתבצע באמצעות מערכת Net-Passport כפי שיוסבר בהמשך התיעוד.
הנחיות למתכנת -רישום וקבלת מזהה ספק להחתמת הנתונים:
ניתן להוריד חינם מאתר https://netpassport.io/register קובץ אבטחה שחותם כל קריאה וכתיבה לשרת המקומי. קובץ זה חותם את הספק המורשה והנו ייחודי לספק.
הקמת ספק חדש :
ספק חדש הוא התוכנה צד ג' המבקשת לבצע קריאות API לחשבשבת המקומית. הרישום הינו ברמת הספק ולא ברמת לקוח קצה או ממשק, כלומר, נדרש רישום חד פעמי. ניתן להשתמש בהגדרות אלו ללקוחות קצה שונים ולממשקים שונים.
- יש להירשם לשרות בכתובת –https://netpassport.io
בכניסה לאתר מוצג המסך הבא:
1.1 לוחצים על SIGN IN :
ואז ניתן להתחבר לשרות באמצעות שלוש האפשרויות הבאות :
בסיום הקמת החשבון מוצג מספר הספק Netpassport id בצד ימין של המסך בחלקו העליון:
מזהה ספק זה, ישמש אתכם לכל קריאות ה-API שתבצעו לתכנת חשבשבת. מספר זה יש לרשום בשדה netPassport id כפי שפורט לעיל.
1.2 – יש להוריד את שני הקבצים הבאים מ- netPassport:
publickey.pem
privatekey.pem
App console >> Generate key pair >> Save keys & download public key
יש להוריד את קובץ KEYS.ZIP ולחלץ אותו לתיקיה.
בעת החתמת הנתונים, יש להפעיל את החתימה עם ה-netPassport id ועם ה- privatekey, ניתן להפנות את הקוד לקובץ (ע"פ הדוגמא המצורפת), או להזין את ה- privatekey בקוד עצמו
- החתמת הנתונים :
כפי שפורט לעיל, על מנת להבטיח את אמינות הנתונים, וכדי שרק מי שמורשה לכך, יוכל לבצע קריאות API משרת הנתונים של חשבשבת, נדרש בכל קריאת API להחתים את הנתונים.
בכל קריאת API החתימה משתנה בהתאם לנתונים בקובץ JSON.
החתמת הנתונים מתבצעת לאחר הגדרת מזהה ספק, (netpassport id) כפי שפורט לעיל, ע"י השוואת ה-private key ומזהה הספק, מול הנתונים הקיימים בהגדרות הספק בשרת חשבשבת.
שימו לב! יש להחתים אך ורק את הנתונים שנמצאים תחת ה- message כפי שמופיע בדוגמא לקוד בהמשך התיעוד
להלן הסבר ודוגמא בקוד כיצד לבצע את החתמת הנתונים בכל קריאה.
בהמשך יפורט איך ניתן להחתים את הנתונים גם למי שלא עובד עם node.js או לא מעוניין להתקין ספריות של node.js בשרת.
Sign data
There are two way to sign data , use netPassport in node.js or by EXE file
Node.js
- download your private key from netpassport.io .
- $ npm install net-passport
const { signer } = require("net-passport");
const fs = require("fs");
// Pass in the .pem file or a pth to the file
const pk = fs.readFileSync(
path.join(__dirname, "lib", "keys", "privatekey.pem"),
"utf-8"
);
// OR
const pk = path.join(__dirname, "lib", "keys", "privatekey.pem")
// Initiate your message object
const message = {
netPassportID: 112233,
myData: "Hi there"
};
// Pass in two parameters that includes your object message (as mentioned above) and
a private key or path to your private key
const signature = signer.sign(message, pk);
send the signature to the API.
Learn more about net-passport in https://www.npmjs.com/package/net-passport.
By exe file
download your private key from netpassport.io , and EXE file from:
for windows: https://sws.wizground.com/files/netPassport-win.exe
for mac: https://sws.wizground.com/files/netPassport-macos
for linux: https://sws.wizground.com/files/netPassport-linux
// send port as parameter to netPasport EXE and execute it
let port = 8040;
const exec = require("child_process").exec;
function createServer() {
return new Promise((resolve, reject) => {
var child = exec(`netPassport-win.exe ${port}`);
child.stdout.on("data", data => {
console.log(data);
resolve("ok");
});
child.on("error", err => {
console.log(`exe failed! , ${err}`);
reject("err");
});
});
}
// send post message to http://localhost:yourPort/sign with the
// following parametrs for signing your data:
// privatekey – .pem file or a pth to the file.
// netPassportID – your net passport ID (from
// https://netpassport.io/home# on the top right).
// data – your data.
let signature = await axios.post(`http://localhost:${port}/sign`, {
privatekey: "./privateKey.pem",
netPassportID: "588406346880516097",
data: JSON.stringify(modulData),
});
// to check if the signature is correct send post message to
// http://localhost:yourPort/verify with the following parametrs:
// privatekey – .pem file or a pth to the file.
// netPassportID – your net passport ID (from
https://netpassport.io/home# on the top right).
// data – your data.
//signature – the signature you got in sing request
let verify = await axios.post(`http://localhost:${port}/verify`, {
privatekey: "./privateKey.pem",
netPassportID: "588406346880516097",
data: JSON.stringify(modulData),
signature: signature.data,
});
console.log(verify.data);
אפשרות חתימה לאתרי WORDPRESS בתוסף נלווה – להסבר לחץ כאן 
Error in API parameters |
| |
חסר שדה station בגוף הבקשה | Body. Station parameter is missing | 1 |
חסר שדה station בגוף הבקשה | Body. Plugin parameter is missing | 2 |
חסר שדה station בגוף הבקשה | Body. Company parameter is missing | 3 |
חסר שדה station בגוף הבקשה | Body. Message parameter is missing | 4 |
שדה netPassportID בשדה message שבגוף הבקשה | body.message.netPassportID parameter is missing | 5 |
חסר שדה pluginData בשדה message שבגוף הבקשה | body.message.pluginData parameter is missing | 6 |
חסר שדהsignature בגוף הבקשה | body.signature parameter is missing | 7 |
Net Passportחסר אימות / נכשל | your net passport is not correct | 8 |
התחנה המבוקשת לא בשרות – Hconnect | Not in service | 9 |
אין הרשאה בחשבשבת למודול המבוקש | you are not allowed to use [moduleType] module | 10 |
שגיאה בטעינת המודול | Failed to load [moduleType] module | 11 |
אין קובץ פרמטרים למודול הנבחר | No [plugin] parameters file | 12 |
שגיאה באימות הנתונים | Failed to validate [plugin] module | 13 |
קובץ אצווה לא קיים | Batch file '[batchPath]' doesn't exist | 14 |
JSON לא תקין | Invalid JSON | 15 |
parameters file – קובץ הפרמטרים (בתחנה) |
| |
אין שדה field | no field key | 1 |
ערך השדהfield ריק | 'field' value is empty | 2 |
אין שדה required | no required key | 3 |
ערך השדה requiredלא בולאני | 'required' value is not Boolean | 4 |
אין שדהtype | no type key | 5 |
ערך השדה type לא חוקי | invalid 'type' | 6 |
אין שדה length | no length key | 7 |
ערך השדה length לא תואם לסוג בשדה type | 'length' value is not numeric | 8 |
JSON הנתונים לא חוקי | pluginData object | 9 |
אין שדה dataבpluginData | no data key in pluginData | 10 |
סוג השדה data אינו מערך | your data is not an array | 11 |
invalid data- נתונים לא תקינים |
| |
שדה נדרש | required field | 1 |
סוג הערך שנשלח שגוי | type error , [field] is not a [field type] | 2 |
אורך הערך שנשלח שגוי | length err ([field]) length ([length]) is not small equal to [type] length ([field length]) | 3 |
הגדרת "מסופון 2"
עד כאן הסברים לגבי העברת מידע מהספק לשרת המקומי בצד הלקוח. נתוני הממשק נשמרים בתיקייה בשרת החשבשבת תחת hash>>rep>>hconnect
בשלב זה הפלאג-אין מבצע המרה לקובץ שאותו ניתן לקלוט בחשבשבת ודוחף אותו דרך "מסופון 2" לחשבשבת.
מנגנון זה הינו הדרך היחידה לקליטת ממשקים לחשבשבת והוא שומר הסף לאימות הנתונים, כך שירשמו בצורה תקינה בתוכנה.
יצירת קובץ אצווה "מסופון 2" במבנה הבא:
batch file name: compId_interface_netPassportI
c:\hash7\Hconnect\compId_interface_netPassportId_*.dat :קובץ מיובא
Delimited :מבנה הקובץ
(,) :תו מפריד
*.prm :קובץ פרמטרים
Ansi2Ansi :המרה לעברית
דוגמה:
לפירוט ולהרחבה על תוכנית מסופון 2 לחץ כאן
דוגמא לקוד קריאת API
API Post
Send post API request to https://ws.wizground.com/api In the following structure:
- שים לב, כל עוד לא הוגדר בחשבשבת "מסופון 2" לא יתבצע שום עדכון במסד הנתונים, יתקבל חיווי שקריאת ה API עבדה בצורה תקינה אך הנתונים לא יקלטו לחשבשבת
JS example:
fetch ("https://ws.wizground.com/api", {
headers: {
"Content-Type":"application/json"
},
method: 'POST',
body: JSON.stringify({
"station": "4cf0a29b-5e20-4855-a46b-8293f31c1d59", // wanted station`s ID
"plugin": "imovein", // wanted module`s name
"company": "demo", // wanted company
"message": { // message body:
"netPassportID": "5884063480516097", // net-passport ID
"pluginData":] {
"Accountkey": "2",
"Reference": "9000919",
"DocumentID": "34",
"ItemKey": "4202",
"Quantity": "20.00,{ "
{
"Accountkey": "2",
"Reference": "9000919",
"DocumentID": "34",
"ItemKey": "4203",
"Quantity": "5.00"
}]},
// signed data (explanation below)
"signature": "eyJhbGciOiJQUzI1NiIsInR5cCI6IkpXVCJ9.eyJuZXRQYXNzcG9
ydElEIjoiNTg4NDA2MzQ2ODgwNTE2MDk3IiwibXlEYXRhIjoiaGVsbG8iLCJpYXQiOjE2MDA5NTY2MjJ9.Ez74J6dZjP-chNoTZVRO24_e5wvSXxmX3FFB99vRY7F7AQQt_YcYdHcZj-9InfN7w7Tq-18zBGNDrvtnpBIXIiFmXkr7Q66VCas-gq9S-alm4Z3jBFHPFFMFY3bfm_EDKKeqBVxC3o4pYdfJpIfYQNJ-6Yn-lfw7fvDmHqnDDr0nmPwGhTvJCqu16ogLC24d0MVMlNFFqDkD3sT-h6iWBcBunSd-ZkczZpP0UVa6PXJoH494LIPI8tn4vZruYYLL0jhMNpEMB2pT48ugiljnK-GpzTRA67ZsJ73gT- -HE6uSFVJMZ8Hd7FjEkv8PsH0ZWutj8WDEIG8DzHoZc28qJqBWPZsU43blmQyVXBrVOxZ7Xw6c0PeUzMcQkiHoxnD3
c55mLNXvNDuKuJBI0BBJjgy2iDdQf-L1denrqaacTtgPaFquNB-vtkxtYlLStEIc_2-50z-
MKOjHvRtsWx2f_2nNIvB0EXT-A_kDJqn9r-AFXiJN3hgE_lSQ"
})
.then(response => response.json())
.then(result => console.log(result))
.catch(error => console.log(`{error} ${ error }`));
| Imovein json: | JSON KUPAIN |
| : [{ "DocumentID": "34", "AccountKey": "20003", "AccountName": "ליווט ", "ValueDate": "16/02/2021", "ItemKey": "4203", "ItemName": "עכבר", "Quantity": "20.00", "Price": "45.00", "DiscountPrc": "10.00", "Remarks": "בדיקה API", "reference": "90009122" },{ "DocumentID": "34", "AccountKey": "20003", "AccountName": "ליווט ", "ValueDate": "16/02/2021", "ItemKey": "4202", "ItemName": "מקלדת אינטרנט", "Quantity": "10.00", "Price": "50.00", "DiscountPrc": "10.00", "Remarks": "בדיקה API", "reference": "90009122" }] | {"accountKey":"2", "docNumber":"699", "transType":"33", "payDate":"13\/01\/2021", "suF":"100.00", "payments":"1", "creditFirm":"ויזה", "cheqsCustomerID":"123456789", "stockPhone":"0509876543", "4Digits":"1880", "FirstPayment":"0", "stockExtraText5":"bob@gmail.com" } |
לאחר מכן, יש להעתיק את השורות המוצפנות של השאילתה שנוצרה, ולהדביק אותה בקוד ה API encrypt_reportData
Reports JSON:
| required | remarks | field |
מפתח לקוח | Yes | encrypt_reportData | |
מספר קבלה | Yes | params_data |
- The data in this file include two parts:
- "encrypt_reportData" – a long encrypted string that refers to the report structure.
- "params_data" – if the report was designed to be issued according to parameters, this part lists the parameters that you have to enter for a proper export of the data.
- If you do use parameters you should update one property value only on each property object. The property "defVal" includes a default value for this property and this is the place to change it to the value that you want. All other properties should be modified according to their type. For example for report (below) having sort codes 100 – 399 you should change to "100" instead "-999999999" and 399 instead "999999999".
- Date type parameter is in mm/dd/yy format.
Jason Example with "client" changes:
encrypt_reportData = '0c61e292d66a71326e011b089534ee1……………….4b4312a84bac14e0ab520a0361d9bcd090';
params_data=[ { "p_name":"__MUSTACH_P0__", "id":"0", "type":"long", "name":"חתך/שדה מרשומת החשבון/1. פרטי חשבון/קוד מיון", "defVal":"100", "opName":"מ..עד", "opOrigin":"from" }, { "p_name":"__MUSTACH_P1__", "id":"500", "type":"long", "name":"חתך/שדה מרשומת החשבון/1. פרטי חשבון/קוד מיון1", "defVal":"399", "opName":"מ..עד", "opOrigin":"to" } ];
|
דגשים לבניית מערכת ממשקים לאתרי סחר
סנכרון אתר האינטרנט הוא בעל חשיבות משתי סיבות:
- שיקוף הנתונים הקיימים בתוכנת חשבשבת ERP אל מול הלקוחות (מלאי זמין למכירה, מחיר המכירה ללקוח קיים וכו').
- חיסכון בכוח אדם ויצירת מנגנון אוטומטי בין האתר לבין מערכת המידע.
הפונקציות אותן ניתן להטמיע בין המערכות באמצעות מערכת הממשקים:
- סנכרון כרטיסי חשבון: אתרי B2B ידרשו סנכרון חשבון בין חשבשבת לבין האתר.
מכיוון שניהול הלקוח מתבצע בחשבשבת (ניהול האובליגו והאשראי), יש חשיבות להקמת כרטיסי הלקוחות בחשבשבת ובסנכרון חד כיווני לאתר.
- סנכרון כרטיסי פריטים: הפריטים מוקמים בחשבשבת. חשוב מאד לנצל את האפשרויות בתוכנה לניהול מלאי מוקפד, וליצירת הזמנות רכש, תוך שימוש בכלים המתקדמים לתכנון הרכש והאופטימיזציה של המלאי. סנכרון הפריטים מתבצע בתדירות הרצויה, פעם בלילה או מספר פעמים ביום. הסנכרון הוא חד כיווני לאתר האינטרנט. דוח הפריטים יכיל את הפריטים הקיימים באתר וכן את המלאי הזמין למכירה באתר.
מהו מלאי זמין?
מלאי זמין מתייחס ליתרת הפריט ממחסן האתר, אחרי גריעת צבר ההזמנות. ניתן לרשום בשדה נתון נוסף בפריט כמות מינימום, ולהתחשב בנתון זה בנוסחה לחישוב המלאי הזמין.
- סנכרון מחירונים: חשבשבת מאפשרת לקבוע מחירים ללקוחות בדרכים מגוונות. לדוגמא, ניתן לקבוע מחיר לפי כמות, או להחיל על המחיר מבצע כלשהו. יש להעביר את המחירון הרלוונטי מהמשרד האחורי לאתר, ולוודא שבקבוצת הפריטים הנמכרים באתר, אין משתמשים במשרד האחורי במחירים תחת תנאים מורכבים (שאם לא כן, המחיר באתר עלול להיות שונה מהמחיר במשרד האחורי)
יש לוודא שמחיר המכירה העובר לאתר אינו כולל מע"מ, וגם הממשק החוזר אינו כולל מע"מ במחיר. על אף זאת, חובה להציג באתר קמעונאי את המחיר הכולל מע"מ - ממשק הזמנות: הזמנות מלקוחות מתקבלות בערוצים השונים: בהקלדה משיחת טלפון, באמצעות מסופוני סוכנים, מאתרי סחר וגם מאתר האינטרנט. כדאי לסמן את ההזמנות מהאתר כדי שניתן יהיה לפלח את ההזמנות לפי ערוצים השונים.
קיימות שתי אפשריות לקליטת הזמנות: למאגר זמני או למאגר קבוע.
אם ההזמנות המקוריות הופקו באמצעות תוכנה אחרת (או בפנקס ידני) יש לקלוט את ההזמנות באמצעות המסמך הזמנת סוכן. ההזמנה צריכה לכלול את נתוני המוצרים (פריטים) כמויות, מחירים (ללא מע"מ), סוג משלוח, פרטי הלקוח, הערות וכו'. - ממשק קבלות: אחד הנושאים הקריטיים בניהול אתר אינטרנט המבצע סליקה של כרטיס אשראי הוא הפקת קבלות. לפי הוראות רשות המסים יש להפיק קבלה מיד עם סליקת כרטיס האשראי. חשבשבת מאפשרת קליטה של הקבלה ממערכת הסליקה החיצונית ושליחת הקבלה ללקוח במייל. נתוני התשלום ייקלטו במאגר זמני של הקבלות, ועל המשתמש להפיק את הקבלה (או מספר קבלות ברצף) באופן יזום. הקבלות יופקו ויישלחו למייל אותו רשם הלקוח כאשר ביצע את ההזמנה באתר.
- חשבונית אוטומטית: הזמנת סוכן הנכנסת מממשק יכולה להפוך, באופן אוטומטי, לחשבונית מס. פעולה זו מתאימה ללקוחות שהמוצר שהם רוכשים אינו פריט מלאי ואין תהליך ליקוט, אריזה ומשלוח, כך שהמוצר סופק במלואו בזמן הרכישה באתר. אם רוצים לממש אופציה זו נדרשת תמיכה ממחלקת הטמעות.
- פקודות יומן: באתרים מסויימים מפיקים חשבוניות מס וקבלות בתוכנות אחרות, ומעוניינים לממשק לחשבשבת אך ורק את נתוני פקודות היומן (הנהח"ש בלבד).אם רוצים לנהל את המלאי בחשבשבת, יש להעביר ממשק נוסף – של תנועות המלאי.
