לקוחות דרך ה-API: הוספה, עדכון, שליפה ויתרה

כל מה שקראתם כאן, המערכת עושה בשבילכם בקליק

45 יום לנסות את ביג בוס בחינם. בלי כרטיס אשראי, בלי התקנה: מייל וסיסמה וזהו.

פתחו חשבון: 45 יום חינם
מדריך למשתמש לתוסף ממשק API בביג בוס

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

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

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

 

הוספת לקוח

הפעולה customer_new פותחת כרטיס לקוח חדש. שדה החובה היחיד הוא שם הלקוח:

שדה מה הוא כללים
company_name שם הלקוח חובה, עד 200 תווים
company_hp מספר עוסק או ח.פ. 9 תווים בדיוק
contact_name איש קשר עד 200 תווים
address כתובת עד 255 תווים
city · zip · tel · cel עיר, מיקוד, טלפון, נייד עד 50 תווים כל אחד
email מייל עד 100 תווים, ונבדק שהוא כתובת תקינה
comments הערות עד 4,000 תווים
account_code קוד החשבון של הלקוח עד 50 תווים. בלי ערך, המערכת מקצה קוד בעצמה
vat_exemption לקוח פטור ממע״מ 0 או 1
request_reference מזהה מהמערכת שלכם עד 255 תווים. נשמר בכרטיס. לקוח חדש עם מזהה שכבר שמור בכרטיס אחר נדחה, ולא נפתח כרטיס נוסף

בהצלחה חוזר מספר הלקוח החדש. ההודעה היא "הלקוח נוסף":

{
  "result_code": 200,
  "result_message": "הלקוח נוסף",
  "data": { "customer_id": 5608 }
}

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

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

אם מוגדר אצלכם Webhook על הוספת לקוח, הוספה דרך ה-API שולחת גם אותו.

 

עדכון לקוח

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

{
  "api_token": "xxxxxxxx",
  "customer_id": 5608,
  "city": "עיר דוגמה"
}

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

 

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

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

"data": {
  "customer_id": 5608, "company_hp": "", "company_name": "לקוח דוגמה - API",
  "contact_name": "", "address": "", "city": "עיר דוגמה", "zip": "",
  "tel": "", "cel": "", "email": "", "comments": "", "account_code": "...",
  "vat_exemption": 0, "request_reference": ""
}

מספר לא תקין מחזיר 400 "מספר כרטיס לא תקין", וכרטיס שלא קיים מחזיר 204 "כרטיס לא נמצא".

customer_list מחזירה את הלקוחות הפעילים. בלי שדות נוספים היא מחזירה את כולם בקריאה אחת, כרשימה, באותו מבנה של הכרטיס. שלושה שדות רשות משנים את זה:

  • page ו-page_size: התשובה מגיעה בעמודים. page מתחיל ב-1, ו-page_size הוא בין 1 ל-500, וברירת המחדל היא 100. בתשובה חוזרים page, page_size, total_count (כמה לקוחות יש בסך הכול) ו-customers.
  • search: חיפוש לפי שם הלקוח, לפחות 2 תווים.
  • updated_since: רק לקוחות שנוספו או השתנו מאז התאריך והשעה ששלחתם, למשל 2026-10-26T08:00:00. כשאין כאלה חוזר 204 "לא נמצאו לקוחות".

שדה לא תקין נדחה ב-400, עם הודעה שאומרת מה לא בסדר, למשל "שדה page חייב להיות 1 ומעלה", "שדה page_size חייב להיות בין 1 ל-500" או "שדה search חייב להכיל לפחות 2 תווים".

 

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

דוגמת בקשה ותשובה אמיתיות: שליפת כרטיס "לקוח דוגמה – API" והשדות שחוזרים.

 

יתרת לקוח

customer_balance מקבלת customer_id ומחזירה את היתרה הפתוחה של הלקוח, לפי המסמכים הסופיים עד היום: { "balance": -34 }. בעסק שמוגדר בו לכלול חשבוניות עסקה ביתרת הלקוח, balance כוללת גם את חשבוניות העסקה הפתוחות, כמו השורה "יתרה (כולל חשבוניות עסקה פתוחות)" בכרטיס הלקוח. לצדה חוזרות accounting_balance, "יתרה חשבונאית (כרטסת)", ו-open_transaction_invoices, הסכום של חשבוניות העסקה הפתוחות (0 כשאין).

יתרה שלילית אומרת שהלקוח חייב לכם. בכרטיס הלקוח בביג בוס אותה יתרה מוצגת כ-34.00 עם האות ח, ובתשובת ה-API היא מגיעה כ-34 במינוס. לקוח בלי מסמכים מקבל 0.

 

כותרת כרטיס לקוח בביג בוס עם היתרה 34.00 ח

בכרטיס הלקוח: יתרה של 34.00 ח. בתשובת ה-API אותה יתרה מגיעה כמספר שלילי.

 

מספר חסר או לא תקין מחזיר 400 "מספר כרטיס לא תקין או חסר", ולקוח שלא נמצא מחזיר 204 "לקוח לא נמצא או שאין נתוני יתרה".

 

כרטסת ומסמכים פתוחים

customer_ledger מחזירה את הכרטסת של לקוח. שולחים customer_id, ואפשר גם טווח ב-date_from וב-date_to. בתשובה חוזרות יתרת הפתיחה (opening_balance), סך החובה וסך הזכות (total_debit, total_credit), יתרת הסגירה (closing_balance) והתנועות עצמן ב-movements: שורה לכל מסמך, עם התאריך, סוג המסמך ומספרו, חובה, זכות והיתרה אחרי התנועה.

{
  "api_token": "<המפתח שלכם>",
  "customer_id": 4821,
  "date_from": "2026-01-01",
  "date_to": "2026-10-28"
}

בבדיקה שלנו התנועות היו זהות שורה-שורה למסך "כרטסת" של אותו לקוח, ויתרת הסגירה הייתה זהה ליתרה שמחזירה customer_balance. כשהיתרה כוללת חשבוניות עסקה פתוחות, יתרת הסגירה של כרטסת עד היום שווה ל-accounting_balance, כי חשבוניות עסקה אינן בכרטסת. לצדה חוזר balance_with_transaction_invoices, ששווה ל-balance. טווח ארוך מ-366 ימים נדחה ב-400 "טווח התאריכים המקסימלי הוא 366 ימים", ותאריך התחלה שאחרי תאריך הסיום נדחה ב-400 "שדה date_from מאוחר משדה date_to". גם תאריך שהשנה שלו אינה בין 1900 ל-9998 נדחה ב-400, למשל "שדה date_from אינו תאריך תקין – השנה חייבת להיות בין 1900 ל-9998".

customer_open_documents מקבלת customer_id ומחזירה רק את המסמכים שעוד פתוחים אצל הלקוח, כמו "פתוחים בלבד" בכרטסת: לכל מסמך הסכום שעוד פתוח, ובסוף היתרה הפתוחה ב-open_balance. לקוח בלי מסמכים פתוחים מחזיר 204 "אין מסמכים פתוחים ללקוח".

שתי הפעולות רק קוראות, ולכן הן עובדות גם במפתח "קריאה בלבד".

 

מה אין בכרטיס דרך ה-API

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

כל שכבת המדריכים מרוכזת בעמוד ממשק API בביג בוס.

 

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

כשצריך עזרה – אנחנו איתך!

צוות התמיכה שלנו ישמח

לעמוד לרשותך כאן

עוד מדריכים עבור ממשק API
עוד מאמרים עבור ממשק API

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

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

🔒 הפרטים מוצפנים ומאובטחים

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

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