API לחשבוניות: מפיקים חשבונית מס וקבלה מהקוד

מה ה-API עושה

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

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

מתחילים: מפתח, טיוטה, הפקה

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

1. מבקשים מפתח Sandbox

   הפקודה מדפיסה קישור. פותחים אותו, נכנסים ל-BillOS ומאשרים, והמפתח נשמר.

   npx billos sandbox
   npx billos seed        # a demo business to work with

2. יוצרים טיוטה

   חשבונית מס קבלה (סוג 320) על 350 ₪ כולל מע״מ, ששולמה בכרטיס אשראי. הסכומים באגורות. המפתח Idempotency-Key הוא מזהה ההזמנה שלכם: קריאה שנשלחת פעמיים מחזירה את אותו מסמך.

   BASE="https://api.billos.co.il/v1"
   KEY="bk_test_..."
   BID=$(curl -s "$BASE/businesses" -H "X-Api-Key: $KEY" | jq -r '.businesses[0].id')
   
   DOC=$(curl -s -X POST "$BASE/businesses/$BID/documents" \
     -H "X-Api-Key: $KEY" -H "Content-Type: application/json" \
     -H "Idempotency-Key: order-1001" -d '{
       "docType": 320, "priceMode": "gross",
       "party": {"name": "דנה לוי", "phone": "0521111111"},
       "lines": [{"description": "איפור ערב", "quantity": 1, "unitPriceExVat": 35000}],
       "payments": [{"method": "card", "amount": 35000}]
     }' | jq -r .document.id)

3. מפיקים

   ההפקה נותנת למסמך את המספר הבא ברצף וחותמת את ה-PDF. מכאן המסמך קבוע.

   curl -s -X POST "$BASE/businesses/$BID/documents/$DOC/issue" -H "X-Api-Key: $KEY" | jq .document.docNumber
   
   curl -s -X POST "$BASE/businesses/$BID/documents/$DOC/prints" -H "X-Api-Key: $KEY" \
     -H "Content-Type: application/json" -d '{"kind":"auto"}' -o invoice.pdf

כשהכול עובד, מחליפים את המפתח במפתח live. הכתובות, הבקשות והשגיאות זהות. התיעוד המלא, עם כל נקודות הקצה, נמצא ב-docs.billos.co.il.

כמה זה עולה

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

עסק שנפתח ונסגר בתוך 24 שעות בלי שהופק בו מסמך אינו מחויב. עסק שבעליו חיבר אותו לאפליקציה שלכם דרך Connect (חיבור ב-OAuth) אינו מחויב אצלכם: הוא עובד על המנוי של בעליו.

תשלום נכנס, מסמך יוצא

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

מספר הקצאה דרך ה-API

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

מה עומד מאחורי כל מסמך

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

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

כתבנו על זה בפירוט, כולל הקוד:

ספריות, כלים וחיבורים

דוגמאות מלאות ל-Express, ל-Next.js ול-Flask, וכללים מוכנים לסוכני קוד, נמצאים ב-GitHub. אתר המפתחים המלא, עם עמוד לכל יכולת: dev.billos.co.il.

Sandbox מול live

כל תשובה נושאת את הכותרת X-BillOS-Mode, שאומרת מאיזה צד היא הגיעה. כדאי לבדוק אותה בקריאה הראשונה.