שליחת המסמך במייל, קישור הצפייה ומניעת כפילויות

המסמך נוצר, ועכשיו הוא צריך להגיע ללקוח

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

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

שליחה במייל

ברירת המחדל היא שהמסמך לא נשלח. בלי השדה send_mail, או עם הערך 0, המסמך נוצר ונחתם, ונשאר בביג בוס.

1. מבקשים שליחה
שולחים send_mail עם הערך 1.

2. כותבים לאן
ב-email_to שולחים כתובת מייל תקינה, ובלעדיה הבקשה נדחית. זה חובה גם כשבכרטיס הלקוח כבר רשום מייל. ב-email_bcc אפשר להוסיף כתובת לעותק מוסתר, למשל של המשרד.

3. בודקים את התשובה
בשדה sent_status מופיע 1 רק אם המייל נשלח בהצלחה. אם חזר 0 וציפיתם לשליחה, שלחו את המסמך מתוך ביג בוס.

"send_mail": 1,
"email_to": "[email protected]",
"email_bcc": "[email protected]"

קישור הצפייה

בכל תשובה של יצירת מסמך חוזר השדה document_link. זה קישור לעמוד צפייה במסמך החתום, ובו אפשר להוריד ולהדפיס אותו. ה-API לא מחזיר את המסמך כקובץ.

בעמוד הצפייה שאליו מוביל document_link: הורדה והדפסה של המסמך.

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

מניעת מסמך כפול

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

1. שולחים מזהה קבוע
ב-request_reference שולחים מזהה מהמערכת שלכם, עד 255 תווים, למשל מספר ההזמנה. לכל מסמך מזהה משלו: אם מאותה הזמנה יוצאים שני מסמכים, מוסיפים למזהה סיומת שונה לכל אחד.

2. בשליחה חוזרת שולחים אותו מזהה
אם כבר קיים בחברה מסמך עם אותו מזהה, הבקשה נדחית בקוד 400 עם ההודעה "נמצא מסמך בעל אותו מזהה – request_reference", ולא נוצר מסמך נוסף.

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

המניעה הזו קיימת במסמכים בלבד. ב-customer_new וב-item_new השדה request_reference נשמר אבל אינו מונע כפילות. שם הכפילות נבדקת לפי ח.פ. של הלקוח ולפי מק״ט של הפריט.

הכול יחד: הזמנה ששולמה באתר

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

1. יוצרים את המסמך
המערכת שלכם שולחת את בקשת היצירה עם מספר ההזמנה ב-request_reference, עם send_mail 1 ועם המייל של הלקוח ב-email_to.

2. בודקים את התשובה
אם result_code הוא 200, שומרים את document_number ואת document_link לצד ההזמנה, ובודקים ש-sent_status הוא 1.

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

מה לא חוזר בתשובה

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

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