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

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

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

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

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

המדריך מפרט את חמש הפעולות על לקוחות: הוספה, עדכון, שליפה, רשימה ויתרה. מבנה הבקשה והתשובה הכללי מוסבר במדריך הקריאה הראשונה ל-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 עם "לא ניתן להוסיף לקוח חדש: לקוח עם ח.פ. זה כבר קיים". כפילות נבדקת לפי ח.פ. בלבד.

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

עדכון לקוח

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

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

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

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

customer_get מקבלת customer_id ומחזירה את הכרטיס, גם של לקוח לא פעיל:

"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 מקבלת רק את api_token ומחזירה את כל הלקוחות הפעילים בקריאה אחת, באותו מבנה. אין בה סינון, ואין חיפוש לפי שם או לפי ח.פ.

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

יתרת לקוח

customer_balance מקבלת customer_id ומחזירה את היתרה הפתוחה של הלקוח, לפי המסמכים הסופיים עד היום: { "balance": -34 }.

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

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

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

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

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

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