כל מה שקראתם כאן, המערכת עושה בשבילכם בקליק
45 יום לנסות את ביג בוס בחינם. בלי כרטיס אשראי, בלי התקנה: מייל וסיסמה וזהו.
לקוח שנרשם באתר מקבל כרטיס גם בביג בוס
כשלקוח נרשם באתר או מבצע הזמנה ראשונה, המערכת שלכם יכולה לפתוח לו כרטיס בביג בוס, לעדכן את הפרטים שלו כשהם משתנים ולהציג לו את היתרה שלו. כך לא מקלידים את אותם פרטים פעמיים, ומסמכים שנוצרים אחר כך נרשמים על הכרטיס הנכון.
המדריך מפרט את הפעולות על לקוחות: הוספה, עדכון, שליפה, רשימה, יתרה, כרטסת ומה שעוד פתוח אצל הלקוח. מבנה הבקשה והתשובה הכללי מוסבר במדריך הקריאה הראשונה ל-API: מבנה הבקשה, התשובה וקודי התשובה.
הוספת לקוח
הפעולה customer_new פותחת כרטיס לקוח חדש. שדה החובה היחיד הוא שם הלקוח:
| שדה | מה הוא | כללים |
|---|---|---|
| company_name | שם הלקוח | חובה, עד 200 תווים |
| company_hp | מספר עוסק או ח.פ. | 9 תווים בדיוק |
| contact_name | איש קשר | עד 200 תווים |
| address | כתובת | עד 255 תווים |
| city · zip · tel · cel | עיר, מיקוד, טלפון, נייד | עד 50 תווים כל אחד |
| מייל | עד 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" והשדות שחוזרים.
יתרת לקוח
customer_balance מקבלת customer_id ומחזירה את היתרה הפתוחה של הלקוח, לפי המסמכים הסופיים עד היום: { "balance": -34 }. בעסק שמוגדר בו לכלול חשבוניות עסקה ביתרת הלקוח, balance כוללת גם את חשבוניות העסקה הפתוחות, כמו השורה "יתרה (כולל חשבוניות עסקה פתוחות)" בכרטיס הלקוח. לצדה חוזרות accounting_balance, "יתרה חשבונאית (כרטסת)", ו-open_transaction_invoices, הסכום של חשבוניות העסקה הפתוחות (0 כשאין).
יתרה שלילית אומרת שהלקוח חייב לכם. בכרטיס הלקוח בביג בוס אותה יתרה מוצגת כ-34.00 עם האות ח, ובתשובת ה-API היא מגיעה כ-34 במינוס. לקוח בלי מסמכים מקבל 0.

בכרטיס הלקוח: יתרה של 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 בביג בוס.