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

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

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

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

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

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

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

הלקוח במסמך

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

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

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

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

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

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

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