יצירת מסמך מכירה דרך ה-API: סוגים, שורות, מע״מ והנחה

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

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

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

עסקה שנסגרה באתר, ומסמך שנוצר בביג בוס

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

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

 

שמונה סוגי מסמכים

את סוג המסמך קובעים בשדה document_type:

document_type המסמך תקבולים
3 הצעת מחיר אסור
100 הזמנה אסור
200 תעודת משלוח אסור
300 חשבונית עסקה אסור
305 חשבונית מס אסור
320 חשבונית מס קבלה חובה
330 חשבונית זיכוי אסור
400 קבלה חובה, ובלי שורות

המסמך נוצר סופי מיד, בלי שלב טיוטה. מי שרוצה שאדם יעבור על המסמך לפני שהוא יוצא שולח את אותו גוף ל-document_draft_new, ונשמרת טיוטה (בסעיף "טיוטה במקום מסמך סופי" למטה). הוא מקבל את המספר הבא בסדרה של אותו סוג מסמך, אותה סדרה של המסמכים שמפיקים מתוך ביג בוס, והמסמך הראשון מסוג מסוים מקבל את מספר ההתחלה שהוגדר. בקשת מספר ההקצאה מתבצעת לפי אותם כללים כמו במסמך שמופק מהמערכת, והתשובה כוללת את השדות allocation_number ו-allocation_status.

 

הלקוח במסמך

לקוח שיש לו כרטיס מזהים ב-company_id, והכרטיס צריך להיות פעיל. בלי כרטיס שולחים company_name, והמסמך נרשם ללקוח מזדמן. כדי לפתוח באותה בקשה כרטיס לקוח חדש, שולחים גם "create_customer": 1: נפתח כרטיס חדש בשם שנשלח, המסמך נרשם עליו, וה-customer_id החדש חוזר בתשובה. בלי אף אחד מהם הבקשה נדחית עם "לא הועבר מספר לקוח וגם לא שם חברה". ללקוח קבוע כדאי לפתוח קודם כרטיס ולשלוח את המספר שלו: לקוחות דרך ה-API: הוספה, עדכון, שליפה ויתרה.

כשלא יודעים אם ללקוח כבר יש כרטיס, שולחים "create_customer": 2 (מצא או צור לקוח). המערכת מחפשת כרטיס קיים לפי company_hp (ח.פ. או ת.ז.), לפי cel מול הנייד שבכרטיס, או לפי tel מול הטלפון שבכרטיס. בח.פ. לא משנה אם יש 0 בהתחלה או מקפים, ובטלפון לא משנים מקפים או 972+ במקום ה-0. ח.פ. שכולו ספרות וקצר מ-9 ספרות נשמר בכרטיס ובמסמך עם אפסים בהתחלה, למשל 41380138 נשמר כ-041380138. נמצא כרטיס: המסמך נרשם עליו, השם ואיש הקשר שבכרטיס לא משתנים, ושדה שריק בכרטיס, למשל מיקוד, מתמלא מהבקשה. לא נמצא: נפתח כרטיס חדש, כמו ב-1. כשבבקשה יש ח.פ., וכרטיס שיש לו אותו נייד רשום עם ח.פ. אחר, הכרטיס הזה לא נלקח ונפתח כרטיס חדש. עם 2 מגיע בתשובה גם customer_status: 1 נמצא כרטיס קיים, 2 נפתח כרטיס חדש. כשנמצא יותר מכרטיס אחד שמתאים, חוזר גם customer_match_note, שמסביר על איזה כרטיס נרשם המסמך, למשל: "נמצאו 2 כרטיסי לקוח פעילים עם אותו מספר נייד – המסמך נרשם על הכרטיס החדש ביותר (מספר 5722)".

אי אפשר לשלוח 2 יחד עם company_id: הבקשה נדחית עם "לא ניתן להעביר מס' לקוח ובנוסף להעביר create_customer ל-2". ערך שאינו 0, 1 או 2 נדחה עם "שדה create_customer יכול להיות 0, 1 או 2", ובשני המקרים לא נוצר מסמך.

customer_new או create_customer 2?

  customer_new create_customer 2
מתי צריך כרטיס לקוח, בלי מסמך מפיקים מסמך ולא יודעים אם ללקוח כבר יש כרטיס
לפי מה מזהים לקוח קיים ח.פ., ו-request_reference כשהוא נשלח ח.פ., נייד או טלפון
כשהלקוח כבר קיים הבקשה נדחית, ולא נפתח כרטיס נוסף המסמך נרשם על הכרטיס הקיים
מה חוזר customer_id customer_id ו-customer_status, ולפעמים גם customer_match_note

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

 

שורות המסמך

השורות נשלחות ברשימה items, והיא חובה בכל סוג חוץ מקבלה. בכל שורה:

  • description: תיאור השורה. חובה, עד 4,000 תווים.
  • catalog_number: מק״ט, לא חובה. בלעדיו השורה חופשית.
  • quantity ו-price_unit_nis: כמות ומחיר ליחידה. המחיר עד 2 ספרות אחרי הנקודה, והוא כולל או לא כולל מע״מ לפי סוג המע״מ של המסמך.

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

 

מע״מ, הנחה ועיגול

  • document_vat_type: חובה בכל סוג חוץ מקבלה. 1 המחירים לא כוללים מע״מ, 2 המחירים כוללים מע״מ, 3 בלי מע״מ. שיעור המע״מ לפי הגדרות החברה.
  • הנחה: הנחה על כל המסמך, באחוזים ב-discount_percentage (ספרה אחת אחרי הנקודה) או בסכום ב-discount_amount (2 ספרות), לא שניהם יחד. אין הנחה לשורה בודדת.
  • circle_pennies: עיגול אגורות. ברירת המחדל היא 1, כלומר לעגל.
  • due_date ו-comments: תאריך פירעון, שלא יכול להיות לפני היום, והערות למסמך.

 

הבקשה והתשובה

כך נראית בקשה אמיתית שנשלחה בבדיקה, בשורה חופשית אחת ובמחיר שכולל מע״מ:

{
  "api_token": "xxxxxxxx",
  "request_reference": "DEMO-API-0110-1",
  "document_type": 3,
  "document_vat_type": 2,
  "company_id": 5608,
  "send_mail": 0,
  "comments": "מסמך דוגמה - בדיקת API",
  "items": [
    { "description": "שירות דוגמה - בדיקת API", "quantity": 1, "price_unit_nis": 50 }
  ]
}

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

"data": {
  "document_type": 3,
  "document_number": 2800,
  "customer_id": 5608,
  "sent_status": 0,
  "document_link": "https://www.bigboss.co.il/bigbossweb?vpid=...",
  "allocation_number": "",
  "allocation_status": 0
}

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

 

טיוטה במקום מסמך סופי

document_draft_new מקבלת את אותם שדות כמו יצירת מסמך, אבל לא מפיקה מסמך: נשמרת טיוטה עם מספר זמני שלילי, והתשובה מחזירה אותה עם status "draft". גם כאן document_vat_type הוא חובה, ובלעדיו הבקשה נדחית ב-400 "לא הועבר סוג מע"מ".

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

 

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

טיוטה שנוצרה דרך ה-API, ברשימת הצעות המחיר בסינון "טיוטה בלבד".

 

  • טיוטה ממסמך קיים: במקום items שולחים source_document_ids, עם ה-document_id של המסמך הפתוח. בבדיקה שלנו טיוטת חשבונית מס מהצעת מחיר פתוחה קיבלה את השורות שלה, המקור נשמר בטיוטה, וההצעה נשארה פתוחה. לפי קובץ המפרט אפשר לשלוח עד 20 הצעות מחיר, הזמנות או תעודות משלוח פתוחות של לקוח אחד. עם items הבקשה נדחית ב-400 "טיוטה ממסמכי מקור לוקחת את השורות מהמסמכים עצמם – אין להעביר items / payments. שינויים עושים בטיוטה באפליקציה", ומסמכים של שני לקוחות נדחים ב-400 "כל מסמכי המקור צריכים להיות של אותו לקוח".
  • אותה בקשה פעמיים: טיוטה עם request_reference שכבר נשלח מחזירה את אותה טיוטה, ולא נוצרת טיוטה שנייה.
  • document_draft_get: מחזירה את הטיוטה לפי document_id, עם ה-status שלה.
  • document_draft_delete: מוחקת את הטיוטה. מחיקה חוזרת מחזירה את אותה תשובה, ואחרי המחיקה document_draft_get מחזירה 204 "טיוטה לא נמצאה".

במפתח "קריאה בלבד" אפשר לשלוף טיוטה, אבל לא ליצור אותה.

 

מה עוד קובע את המסמך

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

 

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

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

 

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

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

 

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

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

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

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

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

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

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

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

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

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