לוגו עבור תוכנה לניהול עסק והפקת חשבוניות ירוקות ביג בוס

ממשק ה-API שלנו לאתר שלך!

ביג בוס אונליין – BigBoss Web – Api

גרסה: Beta 1.0.2

כללי

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

לשאלות והערות עבור ממשק ה-Api ניתן לפנות למייל [email protected]

תוכן עניינים

כללי

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

לשאלות והערות עבור ממשק ה-Api ניתן לפנות למייל [email protected]

הפעלת מודול API

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

יתרון במתן מזהה התקשרות api_index שונה לכל מערכת מתקשרת:

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

יצירת מזהה התקשרות api_index

אזור זה יתעדכן בקרוב

הסבר על מבנה ותוכן התשובה 

מבנה תשובה 

שם
השדה
תאורסוג שדההערות
result_
code
קוד תשובהint

תוצאת הכנת המסמך:

– 200 – התשובה תקינה

– 201 – המסמך
נוצר

– 204 –
לא נמצאו נתונים

– 400 – הבקשה
לא תקינה

– 401 –
לא מורשה לבצע
את הפעולה

– 404 – הבקשה
לא נמצאה

– 503 – השרות לא זמין

result_
message
תאור תשובהstringהודעה אשר מתלווה לקוד result_
code

במקרה והבקשה נכשלה , לדוגמא קוד 400, שדה זה יכיל את תאור השגיאה
result_
data
שדה זה יכיל את תשובת המתודהstring

– בשדה זה יופיע ערך רק אם הפניה הצליחה, אחרת השדה יהיה ריק

– מבנה התשובה משתנה ע"פ המתודה.

– התיעוד מכיל את מבנה התשובה עבור כל מתודה בנפרד

 

רשימת שגיאות כלליות

קוד תשובהתאור התשובהסיבות אפשריות
401קוד הזדהות לא הועברמזהה api_token לא הועבר
401קוד הזדהות לא תקיןמזהה api_token אשר הועבר אינו תקין
401נתוני הזדהות שגוייםמזהה api_token אשר הועבר אינו מוגדר
401קוד הזדהות אינו פעילמזהה api_token אשר הועבר הוגדר כלא פעיל
401החברה אינה זמינהלא נמצאה חברה משוייכת לבקשה זו (*)
401המשתמש אינו זמיןלא נמצא המשתמש המשוייך לבקשה זו (*)
401המשתמש אינו פעילהמשתמש המשוייך לבקשה זו מוגדר כלא פעיל
400לא הועברו נתוניםלא התקבלו נתונים בגוף הבקשה – עבור פניות מסוג POST
400מבנה נתונים לא תקיןמבנה הנתונים שהועברו לא תואמים את מבנה הנתונים שהמתודה ציפתה לקבל
– במקרה זה יתווסף להודעה הסיבה המדוייקת

 

לקוחות

הוספת לקוח

שם השדהתאורסוג שדה
customer_idמס' לקוח אשר נוצר במערכתint

עדכון לקוח

שם השדהתאורסוג שדה
customer_idמס' לקוח אשר עודכןint

קבלת יתרת לקוח

שם השדהתאורסוג שדההערות
api_tokenקוד ה-API שמייצג את פרטי ההתחברותstringשדה חובה
customer_idמס' לקוחintשדה חובה
  • תשובת המתודה
שם השדהתאורסוג שדה
balanceיתרה מעודכנת עבור הלקוחdecimal

קבלת פרטי לקוח

שם השדהתאורסוג שדההערות
api_tokenקוד ה-API שמייצג את פרטי ההתחברותstringשדה חובה
customer_idמס' לקוחintשדה חובה
 

קבלת רשימת לקוחות

שם השדהתאורסוג שדההערות
api_tokenקוד ה-API שמייצג את פרטי ההתחברותstringשדה חובה

תאור שדות עבור רשומת לקוח

(ראה עמודת הערות לגבי שדות חובה בעת הקמה של לקוח וכן בעת עדכון של לקוח)

שם השדהתאורסוג שדההערות
api_tokenקוד ה-API שמייצג את פרטי ההתחברותstring

שדה חובה

שדה זה לא מועבר בחזרה במתודה customer_get

שדה זה לא מועבר בחזרה במתודה customer_list

customer_idמס' לקוחint

שדה חובה בעת עדכון בלבד

אין להעביר בעת הוספה

company_hp

מס' ח.פ. במקרה של תאגיד

מס' עוסק מורשה במקרה של עוסק יחיד

מס' תעודת זהות במקרה של אדם פרטי

string·         שדה זה יכיל מס' ח.פ. או מס' עוסק מורשה או תעודת זהות
company_name

שם העסק \ שם החברה

שם פרטי ושם משפחה במקרה של לקוח פרטי

string

שדה חובה בעת הוספה בלבד

אורך מקסימלי 200 תוים

contact_nameאיש קשר במקרה של חברהstringאורך מקסימלי 200 תוים
addressכתובתstringאורך מקסימלי 255 תוים
cityעירstringאורך מקסימלי 50 תוים
zipמיקודstringאורך מקסימלי 50 תוים
telמס' טלפוןstringאורך מקסימלי 50 תוים
celמס' ניידstringאורך מקסימלי 50 תוים
emailדוא"לstring

אורך מקסימלי 100 תוים

בדיקת תקינות כתובת דוא"ל

account_codeקוד הכרטיס בהנה"חstringאורך מקסימלי 50 תוים
vat_exemptionהאם הכרטיס פטור ממע"מint

ערכים אפשריים:

–          0 – לא פטור ממע"מ (ברירת מחדל בעת הוספה)

–          1 – כן פטור ממע"מ

commentsהערותstringאורך מקסימלי  4,000 תוים
request_referenceמזהה פניהstringמזהה פנייה חיצוני למניעת כפילויות
אורך מקסימלי 255 תוים

דוגמא לקוד להוספת לקוח

{

"api_token": "myTest",

"request_reference": "111223",

"company_hp": "123456789",

"company_name": "חברה לנסיון בבלבד",

"contact_name": "פיטר",

"address": "הרצל 152",

"city": "אשדוד",

"tel": "08-8661332",

"cel": "050-4915874",

"email": "[email protected]",

"account_code": "800224"

}

פריטים

להלן הנושאים המשוייכים פריטים:

 

הוספת פריט

שם השדהתאורסוג שדה
item_idמס' פריט אשר נוצר במערכתint

עדכון פריט

שם השדהתאורסוג שדה
item_idמס' פריט אשר עודכןint

קבלת פרטי פריט

  • סוג בקשה: Post
  • אופן העברת נתונים וקבלת התשובה: JSON
  • כתובת המתודה: https://bigboss.co.il/bigbossweb/api.asmx/item_get
  • שדות להעברה:
    יש חובה להעביר בבקשה את אחד מהשדות המסומנות ב- (*)
שם השדהתאורסוג שדההערות
api_tokenקוד ה-API שמייצג את פרטי ההתחברותstringשדה חובה
(*) item_idמס' פריטint

להעביר בעת שאילתא ע"פ מס' פריט

אין לעביר catalog_number אם מועבר שדה זה

(*) catalog_numberמק"טstring

להעביר בעת שאילתא ע"פ מק"ט

אין לעביר item_id אם מועבר שדה זה

קבלת רשימת פריטים

שם השדהתאורסוג שדההערות
api_tokenקוד ה-API שמייצג את פרטי ההתחברותstringשדה חובה
managed_in_inventoryהאם מנוהל במלאיint

ערכים אפשריים:

–          (-1) – כל הפריטים (ברירת מחדל)

–          0 – לא מנוהל במלאי

–          1 – כן מנוהל במלאי

group_idקוד קבוצהint

ערכים אפשריים:

–          0 – כל הקבוצות (ברירת מחדל)

–          אחרת מס' הקבוצה המבוקשת

תאור שדות עבור רשומת פריט

(ראה הערות לגבי שדות חובה בעת הקמה של פריט וכן בעת עדכון של פריט)

שם השדהתאורסוג שדההערות
api_tokenקוד ה-API שמייצג את פרטי ההתחברותstring

שדה חובה

שדה זה לא מועבר בחזרה במתודה item_get

שדה זה לא מועבר בחזרה במתודה item_list

item_idמס' פריטint

שדה חובה בעת עדכון בלבד

אין להעביר בעת הוספה

item_nameשם הפריטstring

שדה חובה בעת הוספה בלבד

אורך מקסימלי 200 תוים

catalog_numberמק"טstringאורך מקסימלי 100 תוים
barcodeברקודstringאורך מקסימלי 4,000 תוים
group_idמס' קבוצהint

·         במידה ולא הועבר ערך בעת הוספה, יעודכן מס' הקבוצה אשר הוגדרה כברירת מחדל במערכת

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

group_nameשם הקבוצהstring

שדה זה יהיה זמין בעת קבלת נתוני הפריט

בעת הוספה \ עדכון המערכת תתעלם מהערך בשדה זה

price_buy_nisמחיר עלות בש"חdecimal

ברירת מחדל בעת הוספה: 0

לא ניתן הזין מספרים שליליים

דיוק של עד 2 ספרות אחרי הנקודה

price_sell_nisמחיר מכירה בש"חdecimal

ברירת מחדל בעת הוספה: 0

לא ניתן הזין מספרים שליליים

דיוק של עד 2 ספרות אחרי הנקודה

price_sell_vat_includedהאם מחיר מכירה כולל מע"מint

ערכים אפשריים:

–          0 – לא כולל מע"מ (ברירת מחדל בעת הוספה)

–          1 – המחיר כולל מע"מ

image_urlקישור באינטרנט אשר מכיל את התמונהstringאורך מקסימלי 500 תוים
extended_descriptionתאור נרחב של הפריטstringאורך מקסימלי 4,000 תוים
managed_in_inventoryהאם הפריט מנוהל במלאיint

ערכים אפשריים:

–          0 – לא מנוהל במלאי (ברירת מחדל)

–          1 – כן מנוהל במלאי

inventory_min_qttyמלאי מינימוםdecimal

ברירת מחדל: 0 (ללא בקרה על מלאי מינימום)

לא ניתן הזין מספרים שליליים

דיוק של עד 2 ספרות אחרי הנקודה

inventory_max_qttyמלאי מקסימוםdecimal

ברירת מחדל: 0 (ללא בקרה על מלאי מקסימום)

לא ניתן הזין מספרים שליליים

דיוק של עד 2 ספרות אחרי הנקודה

במידה ושדה inventory_min_qtty מועבר אזי הערך לא יכול להיות קטן מהערך המועבר בשדה inventory_min_qtty

request_referenceמזהה פניהstringאורך מקסימלי 255 תוים

דוגמא לקוד להוספת פריט

{

"api_token": "myTest",

"request_reference": "111223",

"item_name": "table",

"catalog_number": "abcdef",

"barcode": "barcode_1",

"price_buy_nis": 25,

"price_sell_nis": 117,

"price_sell_vat_included": 1,

"image_url": "https://www.freeimages.com/photo/prague-conference-center-1056491",

"extended_description": "remarks for item",

"managed_in_inventory": 1,

"inventory_min_qtty": 5,

"inventory_max_qtty": 100

}

קבוצת פריטים

להלן הנושאים המשוייכים לקבות פריטים:

הוספת קבוצה

שם השדהתאורסוג שדה
group_idמס' קבוצה אשר נוצרה במערכתint

עדכון קבוצה

שם השדהתאורסוג שדה
group_idמס' פריט אשר עודכןint

קבלת פרטי קבוצה

שם השדהתאורסוג שדההערות
api_tokenקוד ה-API שמייצג את פרטי ההתחברותstringשדה חובה
(*) group_idמס' קבוצהint

להעביר בעת שאילתא ע"פ מס' קבוצה

אין לעביר catalog_number אם מועבר שדה זה

קבלת רשימת קבוצות

שם השדהתאורסוג שדההערות
api_tokenקוד ה-API שמייצג את פרטי ההתחברותstringשדה חובה

תאור שדות רשומה עבור קבוצה

(ראה הערות לגבי שדות חובה בעת הקמה של פריט וכן בעת עדכון של פריט)

שם השדהתאורסוג שדההערות
api_tokenקוד ה-API שמייצג את פרטי ההתחברותstring

שדה חובה

שדה זה לא מועבר בחזרה במתודה itemgroup_get

שדה זה לא מועבר בחזרה במתודה itemgroup_list

group_idמס' פריטint

שדה חובה בעת עדכון בלבד

אין להעביר בעת הוספה

group_nameשם הפריטstring

שדה חובה

אורך מקסימלי 200 תוים

דוגמא לקוד להוספת קבוצה

{

"api_token": "myTest",

"group_name": "my group",

}

מלאי

להלן הנושאים המשוייכים למלאי:

קבלת כמות במלאי עבור פריט

שם השדהתאורסוג שדההערות
api_tokenקוד ה-API שמייצג את פרטי ההתחברותstringשדה חובה
(*) item_idמס' פריטint

להעביר בעת שאילתא ע"פ מס' פריט

אין לעביר catalog_number אם מועבר שדה זה

(*) catalog_numberמק"טstring

להעביר בעת שאילתא ע"פ מק"ט

אין לעביר item_id אם מועבר שדה זה

  • תשובת המתודה
שם השדהתאורסוג שדה
quatityכמות במלאיdecimal

קבלת כמות במלאי עבור רשימת של פריטים

שם השדהתאורסוג שדההערות
api_tokenקוד ה-API שמייצג את פרטי ההתחברותstringשדה חובה
group_idקוד קבוצהint

ערכים אפשריים:

–          0 – כל הקבוצות (ברירת מחדל)

–          אחרת מס' הקבוצה המבוקשת

  • תשובת המתודה
שם השדהתאורסוג שדה
item_idמס' פריטint
catalog_numberמק"טstring
item_nameשם הפריטstring
group_idמס' קבוצהstring
quatityכמות במלאיdecimal

מסמכים

להלן הנושאים המשוייכים למסמכים:

יצירת מסמך

תאור שדות עבור רשומת מסמך

שם השדהתאורסוג שדההערות
api_tokenקוד ה-API שמייצג את פרטי ההתחברותstringשדה חובה
request_referenceמזהה פניה במערכת היוזמת את הבקשהstringמזהה פנייה חיצוני למניעת כפילויות
אורך מקסימלי 255 תוים
document_typeסוג מסמךInt

שדה חובה

יכול להכיל את הערכים הבאים:

·         3 – הצעת מחיר

·         100 – הזמנה

·         200 – תעודת משלוח

·         300 – חשבונית עסקה

·         305 – חשבונית מס

·         320 – חשבונית מס קבלה

·         330 – חשבונית זיכוי

·         400 – קבלה

document_vat_typeסוג מע"מ במסמךint

שדה חובה (חוץ מאשר במסמך קבלה)

יכול להכיל את הערכים הבאים:

·         1 – המחירים בשורות המסמך לא כוללים מע"מ

·         2 – המחירים בשורות המסמך כן כוללים מע"מ

·         3 – המסמך ללא מע"מ

company_idמס' קוחint

שדה חובה במידה ולא מועבר שדה  company_name

במידה ומועבר:

·         חייב להיות ערך אשר כבר קיים, אחרת תדווח שגיאה

company_hp

מס' ח.פ. במקרה של תאגיד

מס' עוסק מורשה במקרה של עוסק מורשה

מס' תעודת זהות במקרה של אדם פרטי

string

·         שדה זה יכיל מס' ח.פ. או מס' עוסק מורשה או תעודת זהות

·         במידה ומועבר company_id הערך הקיים בכרטיס יעודכן עם הערך המועבר

company_name

שם העסק \ שם החברה

שם פרטי ושם משפחה במקרה של לקוח פרטי

string

שדה חובה במידה ו- לא מועבר company_id

·         במידה ומועבר company_id המערכת תתעלם משדה זה

contact_nameאיש קשר במקרה של חברהstring·         במידה ומועבר company_id הערך הקיים בכרטיס יעודכן עם הערך המועבר
addressכתובתstring·         במידה ומועבר company_id הערך הקיים בכרטיס יעודכן עם הערך המועבר
cityעירstring·         במידה ומועבר company_id הערך הקיים בכרטיס יעודכן עם הערך המועבר
zipמיקודstring

·         במידה ומועבר company_id הערך הקיים בכרטיס יעודכן עם הערך המועבר

·         שדה זה לא נתמך עבור לקוח מזדמן והמערכת תתעלם ממנו אם:

o        לא מועבר שדה  company_id

o        create_customer = 0

telמס' טלפוןstring·         במידה ומועבר company_id הערך הקיים בכרטיס יעודכן עם הערך המועבר
celמס' ניידstring·         במידה ומועבר company_id הערך הקיים בכרטיס יעודכן עם הערך המועבר
emailדוא"לstring·         במידה ומועבר company_id הערך הקיים בכרטיס יעודכן עם הערך המועבר
create_customerהאם להקים לקוחint

ערכים אפשריים:

–          0 – לא להקים (ברירת מחדל)

–          1 – כן להקים

חשוב: לא יוקם לקוח חדש ותתקבל הודעת שגיאה במקרים הבאים:

·         הועבר ערך בשדה company_id

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

due_dateתאריך פרעוןstring

במבנה YYYY-MM-DD

חשוב:

·         תאריך פרעון חייב להיות שווה או גדול מתאריך הפקת המסמך

discount_percentageאחוז הנחהdecimal

·         ניתן להעביר אך ורק במידה ולא הועבר discount_amount

·         יועברו 1 ספאה אחרי הנקודה

discount_amountסכום הנחהdecimal

·         ניתן להעביר אך ורק במידה ולא הועבר discount_percentage

·         יועברו 2 ספרות אחרי הנקודה

circle_penniesעיגול אגורותint

ערכים אפשריים:

–          0 – לא לעגל

–          1 – כן לעגל  (ברירת מחדל)

חשוב:

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

contentתאור תכולת המסמךstring 
commentsהערות למסמךstringחשוב: במסמך מסוג קבלה יש לעדכן את כל המלל בשדה content
send_mailהאם לשלוח את המסמך בדוא"לInt

ערכים אפשריים:

–          0 – לא לשלוח

–          1 – כן לשלוח (ברירת מחדל)

email_toכתובת דוא"ל למשלוח המסמךstringחשוב: גם אם נבחר כרטיס לקוח אשר יש בו כבר דוא"ל, יש לעדכן את הדוא"ל לשליחה בשדה זה
email_bccכתובת דוא"ל למשלוח נסתרstring 
items[]מערך פרטים במבנה המפורט בהמשך שדה חובה (חוץ מאשר במסמך קבלה)
payments[]מערך תקבולים במבנה המפורט בהמשך שדה חובה (במסמכים מסוג קבלה וחשבונית מס קבלה בלבד)

תאור שדות עבור רשומת חיוב items[]

שם השדהתאורסוג שדההערות
catalog_numberמספר קטלוגיstringאורך מקסימלי 100 תוים
descriptionתאור הפריט \ שרותstring

שדה חובה

אורך מקסימלי 4,000 תוים

quantityכמותdecimal

שדה חובה

יועברו 2 ספרות אחרי הנקודה

price_unit_nisמחיר נטו ליחידהdecimal

שדה חובה

יועברו 2 ספרות אחרי הנקודה

 

תאור שדות עבור רשומת תקבול payments[]

שם השדהתאורסוג שדההערות
payment_typeסוג תשלוםint

שדה חובה

יכול להכיל את הערכים הבאים:

·         1 – מזומן

·         2 – שיק

·         3 – כרטיס אשראי

·         10 – ניכוי מס במקור

amount_nisסכום בשקליםdecimal

שדה חובה

יועברו 2 ספרות אחרי הנקודה

due_dateתאריך פרעוןstring

שדה חובה – בתשלום מסוג שיק וכרטיס אשראי

במבנה YYYY-MM-DD

חשוב:

–          תאריך פרעון חייב להיות שווה או גדול מתאריך הפקת המסמך

–          בתקבול מזומן ובניכוי מס במקור יעודכן תאריך המסמך תוך התעלמות מהמועבר בשדה זה

bank_codeקוד בנקint

שדה חובה בתשלום מסוג שיק

להן רשימת הקודים הנתמכים:

1הבנייה
2צפון אמריקאי
4יהב
7בנק לפיתוח תעשייה
8הספנות
9הדואר
10ב.ל.ל
11דיסקונט
12פועלים
13אגוד
14אוצר-החייל
17מרכנתיל
19החקלאות
20המזרחי
22סיטי
24אמריקאי-ישראלי
26יובנק בע"מ
27עין חי
28קונטיננטל
30למסחר
31הבינ"ל
32מימון וסחר
34ערבי ישראלי
35פה.קא.או
46מסד
52פא"י
53עלייה
54ירושליים
99לא מוגדר
branch_numberמס' סניףstring

שדה חובה בתשלום מסוג שיק

יש להעביר 3 ספרות בלבד

bank_account_numberמס' חשבוןstringשדה חובה בתשלום מסוג שיק
cheque_numberמס' שיקstring

שדה חובה בתשלום מסוג שיק

יש להעביר 4 ספרות אחרונות בלבד

credit_card_codeקוד כרטיס אשראיint

שדה חובה בתשלום מסוג כרטיס אשראי

להן רשימת הקודים הנתמכים:

1ישראכרט
2ויזה כאל
3דיינרס
4אמריקן-אקספרס
5JBC
6לאומי כארד
credit_card_numberמס' כרטיסstring

שדה חובה בתשלום מסוג כרטיס אשראי

יש להעביר 4 ספרות אחרונות בלבד

 

מבנה התשובה המתקבל בעת הפקת המסמך

שם השדהתאורסוג שדההערות
document_typeסוג מסמךint 
document_numberמספר מסמךintמספר המסמך שנוצר
customer_idמס' לקוח במסמךintבמקרה של הפקה ללקוח מזדמן יחזור הערך 1-
sent_statusסטטוס שליחת המסמךint

ערכים אפשריים:

–          0 – המסמך לא נשלח

–          1 – המסמך נשלח בהצלחה

document_linkקישור לקובץ pdf של המסמךstring 

דוגמא לקוד להפקת חשבונית מס קבלה

{

"api_token": "myTest",
"request_reference": "111222",
"document_type": 320,
"document_vat_type": 1,
"create_customer": 0,
"company_id": 4237,
"address": "הרצל 134",
"city": "אשדוד",
"discount_percentage": 2.5,
"content": "תאור לתכולה",
"comments": "הערות שונות",
"send_mail": 1,
"email_to": "[email protected]",
"items": [
{
"catalog_number": "1122",
"description": "שולחן עבודה",
"quantity": 2.0,
"price_unit_nis": 100.0,
}
],

"payments": [
{
"payment_type": 2,
"amount_nis": 526.5,
"due_date": "2023-09-05",
"bank_code": 10,
"branch_number": "789",
"bank_account_number": "998877",
"cheque_number": "4321",
}

]

}

45 ימי הניסיון בחינם שלך מתחילים ביצירת חשבון :)

- נרשמים עכשיו ומתחילים -