כל המסמכים API

```html

מבוא
 

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

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

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

---

מי משתמש בממשק API זה
 

ממשק ה-API של כל המסמכים מיועד לשימוש על ידי:
 

• אתרי אינטרנט ופלטפורמות מסחר אלקטרוני

• יישומים ניידים

• מערכות CRM

• מערכות ERP

• אינטגרציות חשבונאות ופיננסים

• מערכות קופה

• סקריפטים לאוטומציה ומשימות רקע
   

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

---

כתובות URL בסיסיות ונקודות כניסה
 

כל האינטראקציות מתחילות מאחד מהדומיינים הבסיסיים הבאים:
 

• דומיין ייצור
  
  https://biz1.co.il/

• דומיין חלופי
  
  https://bull36.com/
   

שני הדומיינים חושפים את אותה התנהגות API.
 

---

כתובות URL עיקריות ליצירת מסמכים
 

add_order2 – נקודת קצה ראשית ליצירה
 

https://biz1.co.il/api.php?api=add_order2
 

זוהי כתובת ה-URL החיצונית הראשית המשמשת ליצירת מסמכים.
 

היא אחראית ל:

 

• יצירת חשבוניות

• יצירת קבלות

• יצירת הזמנות

• יצירת קבלות תרומה

• יצירת מסמכי זיכוי והחזרה

• הפעלת אוטומציה של תהליכי עבודה
   

מערכות חיצוניות מקיימות אינטראקציה רק עם כתובת URL זו לצורך יצירת מסמכים.
 

---

create_document – כינוי של add_order2
 

https://biz1.co.il/api.php?api=create_document
 

כתובת URL זו זהה פונקציונלית ל-add_order2.
 

היא קיימת עבור:
 

• תאימות לאחור

• מתן שם ברור יותר לאינטגרציות

• תמיכה היסטורית
   

שתי כתובות ה-URL מפנות לאותה לוגיקה פנימית.
 

---

מה משמעות “מסמכים” ב-Biz1
 

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

• עסקה פיננסית

• התחייבות למכור או לרכוש

• אישור תשלום

• משלוח או החזרה של סחורה

• תרומה או מנוי
   

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

---

סוגי מסמכים ומטרתם
 

מסמכי חשבונית
 

חשבוניות מייצגות אירועי חיוב.

חשבונית מס מונפקת בעת חיוב לקוח.
חשבונית זיכוי מבטלת או מפחיתה חשבונית קודמת.
חשבונית פרופורמה היא חשבונית ראשונית המשמשת לאישור.
חשבונית משלוח מתעדת סחורות שנשלחו.
חשבונית החזרה מתעדת סחורות שהוחזרו.
מסמך GR/IR תומך בהתאמת חשבונות של סחורות וחשבוניות.
 

מסמכי חשבונית:
 

• יכולים להכיל מוצרים

• יכולים לכלול מע"מ

• תמיד מייצרים קובצי PDF

• מופיעים ברישומי הנהלת חשבונות
   

---

מסמכי קבלה
 

קבלות מייצגות אירועי תשלום.

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

קבלות:
 

• עשויות לכלול מוצרים או רק סכום כולל

• תמיד מייצגות תנועת כסף

• מעדכנות סטטוס תשלום של מסמכים קשורים
   

---

מסמכי הזמנה
 

הזמנות מייצגות כוונה ותהליך עבודה, לא תשלום.
 

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

הזמנות:
 

• יכולות מאוחר יותר ליצור חשבוניות

• מקושרות לעיתים קרובות לקבלות

• עוקבות אחר התהליך העסקי לפני התשלום
   

---

כיצד ממשק ה-API של כל המסמכים פועל באופן פנימי

כאשר מערכת חיצונית קוראת:
 

https://biz1.co.il/api.php?api=add_order2
 

זרם הביצוע הבא מתרחש בתוך Biz1.
 

---

שלב 1: אימות
 

ממשק ה-API מאמת את ה-api_token.
 

אם לא חוקי:
 

• הבקשה נעצרת מיד

• שום מסמך לא נוצר

• שום לקוח לא משונה
   

אם חוקי:
 

• המשתמש נטען

• הגדרות הארגון מיושמות

• הרשאות נאכפות
   

---

שלב 2: רזולוציית סוג המסמך
 

ממשק ה-API קורא את ה-document_type וקובע:
 

• באיזה מנוע מסמכים פנימי להשתמש

• אילו כללי אימות חלים

• איזו תבנית PDF יש לבחור

• האם נדרשים מוצרים

• האם נדרשים נתוני תשלום
   

שלב זה שולט בכל מה שבא אחריו.
 

---

שלב 3: רזולוציית לקוח
 

ממשק ה-API קובע למי המסמך שייך.
 

קיימות שתי אפשרויות:
 

אם cust_id מסופק:
 

• הלקוח הקיים נטען ישירות
   

אם cust_id אינו מסופק:
 

• ממשק ה-API משתמש בשם, אימייל וטלפון

• לקוח קיים ממוחזר אם נמצא

• אחרת, לקוח חדש נוצר אוטומטית
   

משמעות הדבר היא שאין צורך בממשק API נפרד ליצירת לקוחות.
 

---

שלב 4: עיבוד אובייקט הזמנה
 

אובייקט ה-JSON order מגדיר את התנהגות המסמך ברמת המסמך.
 

ממשק ה-API:
 

• מגדיר את המטבע

• מגדיר את אחוז המע"מ

• מחיל הערות

• רושם הנחות גלובליות
   

זה הופך לבסיס הפיננסי של המסמך.
 

---

שלב 5: טיפול במוצרים ופריטי שורה
 

אם סוג המסמך דורש מוצרים:
 

• כל מק"ט מאומת או נוצר אוטומטית

• מחיר וכמות מאומתים

• הנחות מיושמות

• שילוב מע"מ מטופל כראוי
   

המערכת מחשבת:
 

• סכומי שורה

• השפעת הנחה

• ערכי מס
   

אם המסמך הוא קבלה המשתמשת ב-all_items_total, שלב זה מדלג.
 

---

שלב 6: טיפול בתשלום (מסמכי קבלה)
 

עבור מסמכים מבוססי קבלה:
 

• שיטת התשלום נרשמת

• מזהי כרטיס אשראי נשמרים (4 ספרות אחרונות)

• תשלומים בפריסה מטופלים

• מסמכים מסומנים כבתשלום מלא או חלקי
   

זה משפיע ישירות על:
 

• סטטוס הנהלת חשבונות

• יתרת לקוח

• מצב מסמך מקושר
   

---

שלב 7: אוטומציה של תהליכי עבודה
 

אם קיימים דגלי אוטומציה:
 

• invoice_create

• reciept_tax_invoice
   

המערכת יוצרת מסמכים נוספים באופן אוטומטי.
 

דוגמאות:
 

• הזמנה → חשבונית

• הזמנה → חשבונית → קבלה
   

כל המסמכים הם:
 

• מקושרים יחד

• מאוחסנים באופן אטומי

• מטופלים כעסקה לוגית אחת
   

---

שלב 8: שמירת מסמך
 

המסמך נשמר במסד הנתונים.
 

בשלב זה:
 

• מזהה מסמך נוצר

• קשרים נשמרים

• ערכים פיננסיים מסוכמים
   

---

שלב 9: יצירת PDF
 

עבור מסמכים סופיים:
 

• תבנית ה-PDF הנכונה נבחרת

• מיתוג ושפה מיושמים

• קובץ PDF מעובד

• הקובץ מאוחסן באופן מאובטח
   

קובץ ה-PDF הופך לפלט המסמך הרשמי.
 

---

שלב 10: מסירה (אופציונלי)
 

אם דגלי מסירה מופעלים:
 

• אימייל שולח את קובץ ה-PDF כקובץ מצורף

• וואטסאפ שולח קישור מאובטח למסמך
   

המסירה מתרחשת באופן אסינכרוני ואינה חוסמת את היצירה.
 

---

כתובת URL לאחזור מסמכים
 

כדי לאחזר מסמכים מאוחר יותר, מערכות קוראות ל:
 

https://biz1.co.il/api/get_document
 

ממשק API זה:
 

• מאמת את הבקשה

• מסנן לפי לקוח

• מסנן לפי סוג מסמך

• מחיל מסנני תאריך

• מחזיר מטא-נתונים של מסמכים ונתיבי PDF
   

משמש עבור:
 

• פורטלי לקוחות

• לוחות מחוונים למנהלים

• דוחות

• ביקורות
   

---

כתובת URL לצפייה ב-PDF
 

כדי לצפות או להוריד קובץ PDF:
 

https://biz1.co.il/dashboard/api/filesview?url=ENCODED_PDF_PATH
 

כתובת URL זו:
 

• מזרמת קובצי PDF באופן מאובטח

• מונעת גישה ישירה לקבצים

• תומכת בצפייה והורדה דרך הדפדפן
   

משמש ב:
 

• קישורי אימייל

• הודעות וואטסאפ

• ממשקי ניהול
   

---

דוגמה מהעולם האמיתי מקצה לקצה
 

תהליך עסקי טיפוסי נראה כך:
 

1. לקוח משלים רכישה

2. המערכת קוראת ל-add_order2

3. מסמך הזמנה נוצר

4. חשבונית נוצרת אוטומטית

5. תשלום מאושר

6. חשבונית מס קבלה נוצרת

7. קובץ PDF נוצר

8. קובץ PDF נשלח באימייל ובוואטסאפ

9. מנהל מערכת מאחזר מסמכים באמצעות get_document

10. קובץ PDF נצפה באמצעות filesview
     

הכל באמצעות מערכת API מאוחדת אחת.
 

---

מדוע עיצוב API זה חשוב
 

ממשק ה-API של כל המסמכים:
 

• מבטל לוגיקה חשבונאית כפולה

• מונע מסמכים לא עקביים

• מבטיח עמידה בתקני מס

• מפשט אינטגרציות

• מתאים לגדלי עסקים שונים

• שומר על שביל ביקורת נקי
   

הוא בנוי להיות חסין לעתיד, ניתן להרחבה ומאובטח.
 

---

הבנה סופית
 

אם מישהו שואל:
 

“מה עושה ממשק ה-API של כל המסמכים?”
 

התשובה הנכונה היא:
 

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

```