ה-API של Invoice4U: הפקת חשבוניות אוטומטית מהאתר או מה-CRM

ה-API של Invoice4U מאפשר לאתר, לחנות מקוונת או ל-CRM להפיק ב-Invoice4U חשבוניות, קבלות וחשבוניות זיכוי אוטומטית. זה שירות WCF של .NET עם נקודת כניסה ב-JSON: שולחים POST לכתובת https://api.invoice4u.co.il/Services/ApiService.svc/{Operation}, למשל CreateDocument, עם הפרמטרים ועם token. שני הדברים שמכשילים את רוב החיבורים הם מעטפת התשובה {"d": ...} ושגיאות שמגיעות עם סטטוס HTTP 200.

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

איך עובד ה-API של Invoice4U?

השירות חושף נקודת קצה אחת עם 157 פעולות, שרשומות ב-WSDL שלו בכתובת ApiService.svc?singleWsdl. הוא מדבר SOAP מטבעו, אבל לא צריך לקוח SOAP: נקודת כניסה של ASP.NET מקבלת גוף JSON בנתיב של הפעולה עצמה.

שמות הפרמטרים של כל פעולה באים מהחוזה ורגישים לאותיות גדולות וקטנות. CreateDocument, CreateDocumentWithIdentifierValidation ו-SendDocumentByMail מקבלות doc ו-token. CreateCustomer מקבלת cu ו-token. FetchAllocationNumber מקבלת docId ו-token.

דוגמה: חשבונית מס קבלה בבקשה אחת ל-API של Invoice4U

חשבונית מס קבלה שלמה על הזמנה ששולמה היא בקשת POST אחת. שמות השדות והטיפוסים שלמטה לקוחים מחוזה השירות: DocumentType, ClientID ו-PaymentType הם מספרים שלמים, Quantity, Price ו-Amount הם מספרים עשרוניים, ו-Date הוא תאריך בפורמט של WCF. 12345 מייצג את מזהה הלקוח ב-Invoice4U שאיתרתם או יצרתם קודם.

POST https://apiqa.invoice4u.co.il/Services/ApiService.svc/CreateDocumentWithIdentifierValidation
Content-Type: application/json

{
  "token": "<token>",
  "doc": {
    "DocumentType": 3,
    "ClientID": 12345,
    "Subject": "Order 1042",
    "TaxIncluded": true,
    "ApiIdentifier": "order-1042",
    "IsSendUserMail": true,
    "Items": [
      { "Name": "Monthly plan", "Code": "PLAN-M", "Quantity": 1, "Price": 300 }
    ],
    "Payments": [
      { "PaymentType": 1, "Amount": 300, "Date": "\/Date(1793952000000)\/" }
    ]
  }
}

מה כל חלק עושה: DocumentType: 3 הוא חשבונית מס קבלה, ולכן הבקשה כוללת גם את הפריט וגם את התשלום, ושני הסכומים חייבים להתאים. PaymentType: 1 הוא כרטיס אשראי. ApiIdentifier הוא מספר ההזמנה שלכם, וכך ניסיון חוזר אחרי פסק זמן נדחה במקום להפיק מסמך שני. IsSendUserMail שולח את המסמך ללקוח במייל. התשובה היא אותו אובייקט Document בתוך d: קוראים קודם את d.Errors, ורק כשהוא ריק שומרים על ההזמנה את d.DocumentNumber (מספר ארוך) ואת d.ID (GUID).

למה קריאה שנכשלה ב-Invoice4U מחזירה 200?

Invoice4U מדווחת על שגיאות עסקיות בתוך התוכן, לא בסטטוס ה-HTTP. קריאה בלי טוקן תקין מחזירה סטטוס 200 עם הגוף הזה:

{"d": {"Errors": [{"Error": "UnauthorizedUser", "ID": 80, "Paramters": null}], "TaxRate": -1}}

כך שחיבור שבודק רק את response.ok רושם כל כישלון כהצלחה, והזמנה מסומנת "הופקה חשבונית" כשאין שום חשבונית. הכלל: קוראים את d, וכל מערך Errors שאינו ריק הוא כישלון. שימו לב לשם השדה Paramters - הוא מאוית לא נכון בחוזה עצמו, ולכן מפענח קפדני צריך להתאים אותו בדיוק.

מפתח לא תקין הוא מקרה נוסף של אותו כלל. VerifyLoginApiKey עם מפתח שלא קיים החזירה {"d": null}, גם כן עם סטטוס 200, גם בייצור וגם ב-QA, כשבדקנו ב-7 בנובמבר 2026. כלומר d ריק הוא כישלון, לא הצלחה ריקה.

הפקת חשבונית מהזמנה, שלב אחר שלב

1. מקבלים מפתח API מבעל החשבון ב-Invoice4U, ובודקים קודם מול נקודת הקצה של QA.
2. מאתרים או יוצרים את הלקוח. GetCustomerByEmail מאתרת לקוח; CreateCustomer מקבלת אובייקט cu עם Name, Email, Phone או Cell, Address, City ו-UniqueID (ת"ז או ח"פ).
3. בונים את אובייקט doc: DocumentType, ClientID, Subject, Currency, TaxIncluded, ו-Items עם Name, Code, Quantity ו-Price.
4. לחשבונית מס קבלה מוסיפים Payments עם PaymentType, Amount ו-Date. סכום הפריטים וסכום התשלומים חייבים להתאים.
5. מגדירים ApiIdentifier למספר ההזמנה וקוראים ל-CreateDocumentWithIdentifierValidation.
6. בודקים את Errors. בהצלחה, שומרים על ההזמנה את DocumentNumber ואת מזהה המסמך שחזרו.
7. שולחים ללקוח, או עם IsSendUserMail על המסמך או עם SendDocumentByMail אחר כך.

באילו קודי DocumentType משתמשת Invoice4U?

DocumentType הוא מספר, והחוזה מגדיר את הערכים האלה:

קודים 11 ו-12 לא קיימים, כך שחיבור שסופר כלפי מעלה מ-10 שולח סוג לא תקין. גם אמצעי התשלום מספריים, ב-PaymentTypes: 1 כרטיס אשראי, 2 צ'ק, 3 העברה בנקאית, 4 מזומן, 8 ביט, 9 PayBox. איזה מסמך להפיק לאיזו מכירה מוסבר בקבלה, חשבונית מס או חשבונית מס קבלה.

מה משתבש בחיבור ל-Invoice4U

• חשבוניות כפולות. פסק זמן ב-CreateDocument לא אומר ששום דבר לא הופק. המסלול עם ApiIdentifier קיים כדי שניסיון חוזר יידחה במקום להפיק מסמך ממוספר שני, שאחר כך צריך לבטל בחשבונית זיכוי.
• פורמט תאריכים. תאריכי JSON של WCF נראים כך: /Date(milliseconds)/, ולא מחרוזות ISO. שולחים תאריכים בצורה הזו, ומפענחים אותם כך בחזרה.
• שני שדות סכום. כל סכום מופיע פעמיים, למשל Total ו-TotalDecimal, לצד הדגל UseDecimalValues. מחליטים איזה מהם החיבור קורא, ובודקים מול מסמך אמיתי לפני שסומכים עליו.
• מספרי הקצאה. על המסמך יש AllocationNumber, AllocationMessage ו-ForceGenerateAllocationNumber, ו-FetchAllocationNumber מבקשת מספר למסמך קיים. מתי נדרש מספר הקצאה נקבע על ידי רשות המסים, לא על ידי ה-API - ראו ה-API של מספרי הקצאה.
• הטוקן בלוגים. הטוקן נוסע בגוף הבקשה, כך שלוג דיבאג של גופי בקשות מלאים חושף אותו.

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

מה להכין לפני שמתחילים

• מפתח API של Invoice4U, וגישה לסביבת QA לבדיקות.
• החלטה איזה מסמך כל מכירה מפיקה - חשבונית מס קבלה בזמן התשלום, או חשבונית קודם וקבלה אחר כך.
• כרטיסי לקוח עם ת"ז או ח"פ, כשהעסק צריך אותם.
• טיפול במע"מ שהוחלט לכל מוצר: מחירים כולל מע"מ או לפני מע"מ (TaxIncluded).
• מקום לשמור את מספר המסמך של Invoice4U מול כל הזמנה.

מקורות

• חוזה ה-WSDL של ApiService ב-Invoice4U
• תיעוד המפתחים של Verifone - מסמכי Invoice4U