השירות לא החזיר מספר הקצאה. איך מבדילים בין באג בבקשה לבין החלטה של רשות המסים, מה אומרים קודים 460, 461 ו-462, ואילו ארבע חלופות התוכנה צריכה להציג.
עיקרי הדברים
- שירות ה-Approval יכול להחזיר HTTP 200 ועדיין לא לאשר את החשבונית: הסימן הוא `confirmation_number` בערך "0" ו-`approved` בערך false.
- קוד 460 מתועד כ-"Invoice not approved" - הנתונים תקינים והחשבונית לא אושרה. קוד 461 מציין שהחשבונית הלא-מאושרת קיימת ולא נשלחה החלטה, וקוד 462 שהחשבונית קיימת וההחלטה כבר נשלחה.
- שגיאות משפחת 400, למשל 431 ל-`vat_number` שגוי או 434 ל-"Invoice date is too old for approval", מצביעות על תוכן הבקשה.
- כשלא מתקבל מספר הקצאה מסיבה מהותית, המפרט מגדיר ארבע חלופות שהתוכנה מציגה למשתמש, ושירות `Invoice-decision` נפרד לעדכון הבחירה.
- כל פנייה חייבת לשאת מזהה חד-ערכי `INVOICE_ID`, וזה המזהה שמחזיק את כל הסיפור יחד לאורך שימוע, ביטול או פנייה חוזרת.
כשהשירות לא מחזיר מספר הקצאה, הדבר הראשון הוא להבחין בין דחייה טכנית לבין החלטה של רשות המסים. תשובת 400 עם קוד שדה היא באג בבקשה שלכם. תשובת 200 שבה approved הוא false היא החלטה, ואז תוכנת החשבונות אמורה להציג למשתמש ארבע חלופות ולעדכן את הרשות בבחירה.
זהו תיאור טכני של ממשק ושל תהליך עבודה, ולא ייעוץ מס, משפטי או חשבונאי.
מה השירות מחזיר בפועל כשחשבונית לא מאושרת
שירות קבלת מספר ההקצאה בצד הספק פועל בכתובות https://ita-api.taxes.gov.il/shaam/production/Invoices/v2/Approval בייצור ובכתובת מקבילה תחת tsandbox בסביבת הבדיקות, עם הזדהות בפרוטוקול OAuth2. תשובה מוצלחת מכילה status 200, הודעה "Invoice approved", confirmation_number ארוך ו-approved בערך true.
הכשל שמפיל מימושים חדשים הוא שהתשובה השלילית מגיעה גם היא כ-200. לפי המפרט, אם ערך מספר האישור הוא 0 או שערך שדה הפלט approved הוא false, יש לבדוק את רשימת השגיאות. קוד שמניח ש-HTTP 200 פירושו הצלחה ידפיס חשבונית בלי מספר הקצאה ולא ידע על כך.
איזה כשל הוא באג שלכם ואיזה הוא החלטה?
ההבחנה עוברת בין מבנה הבקשה לבין תוכן ההחלטה, וגם המיקום בתשובה שונה: אובייקט השגיאה נושא שדה location בערך "request" בשגיאות תוכן ובערך "approval" בשגיאות ההחלטה.
| קוד | היכן מופיע | מה מתועד | לאן זה מפנה |
|---|---|---|---|
| 431 | HTTP 400 | "VAT Number is incorrect" על vat_number | תקינות המספר שנשלח |
| 434 | HTTP 400 | "Invoice date is too old for approval" על invoice_date | תאריך המסמך בבקשה |
| 460 | HTTP 200 | "Invoice not approved" | החלטה, לא נתונים |
| 461 | HTTP 200 | החשבונית הלא-מאושרת קיימת, לא נשלחה החלטה | המתנה או פנייה חוזרת |
| 462 | HTTP 200 | החשבונית קיימת וההחלטה נשלחה | אין פעולה נוספת |
| 401 | HTTP 401 | לא עוברים בדיקות אבטחה | הטוקן ופרוטוקול OAuth2 |
| 406 | HTTP 406 | השרת לא יכול לקיים את הבקשה | הרשאה למספר העוסק |
| 422 | HTTP 422 | פרמטרים שלא תואמים לסכימה | ולידציה מול המפרט |
ארבע החלופות שהתוכנה צריכה להציג
לפי המפרט, כאשר השירות לא החזיר מספר הקצאה מסיבה מהותית ולא טכנית, תוכנת הנהלת החשבונות מציגה למשתמש ארבע חלופות ומעדכנת את רשות המסים בבחירה:
- נטישה או ביטול החשבונית. הביטול מתבצע באופן הרגיל. במפרט מצוין שההנחיה במקרה של ביטול חשבונית מס היא לא לכלול את החשבונית ואת הביטול בקובץ PCN874.
- המשך הפקת החשבונית ללא מספר הקצאה. המפרט קובע שהחשבונית תכלול בצורה בולטת את המשפט "אין לנכות מס תשומות בגין חשבונית זו".
- היפוך החיוב. מתבצע בפנייה נוספת לשירות עם חשבונית בשיעור אפס, אותם פרטים, אותו
Invoice_Idוהערך 3 בשדהaction. - בקשה לשימוע. מוגשת דרך אפיקי השירות של הרשות. אם בעקבותיה החשבונית הותרה, פונים שוב לשירות ההקצאה.
לשלוש מהחלופות יש שירות ייעודי: Invoice-decision בגרסה v1 עם שלוש נקודות קצה - /Cancel, /Continue ו-/FurtherObjection. חלופת היפוך החיוב לא עוברת שם אלא חוזרת לשירות Approval עצמו.
מה עושים בפועל בזמן אמת
- עוצרים את ההדפסה. חשבונית שיצאה למסך או למדפסת לפני שהתשובה נבדקה היא הנזק העיקרי.
- מסווגים את התשובה: קוד HTTP, ערך
approved, ערךconfirmation_numberוקוד השגיאה הפנימי. - אם זו משפחת 400, מתקנים את הבקשה ומשדרים מחדש עם אותו
INVOICE_ID. - אם זו החלטה, מציגים למשתמש את ארבע החלופות ומתעדים מי בחר ומתי.
- מעדכנים את הרשות בבחירה דרך
Invoice-decision, או דרךApprovalבהיפוך חיוב.
למה INVOICE_ID הוא השדה הכי חשוב בכל הזרימה
INVOICE_ID מוגדר כמזהה חד-ערכי באורך של עד 50 תווים, והוא מלווה את החשבונית בכל פנייה. המפרט מציין במפורש שכאשר הוגשה בקשה לשימוע והחשבונית הותרה, יש לחזור ולבצע בקשה נוספת למספר ההקצאה עם אותו Invoice_Id של החשבונית המקורית. אותו מזהה משמש גם בהיפוך החיוב ובשירות עדכון ההחלטה.
המשמעות ההנדסית: המזהה הזה לא יכול להיות מספר רץ שנוצר בזמן ההדפסה. הוא חייב להישמר ברשומת המסמך לפני הפנייה הראשונה, לשרוד ריסטארט, ולהיות ניתן לאחזור שבוע אחרי כן כשמישהו שואל מה קרה לחשבונית הזאת. אם המערכת הישנה שלכם לא מחזיקה שדה כזה, זה השדה הראשון להוסיף - ראו איך מכינים מערכת ישנה לחשבונית ישראל.
מה נשבר במורד הזרם כשאין מספר הקצאה?
מספר ההקצאה לא נגמר בהדפסה. במפרט מוגדר "מספר הקצאה קצר" - תשעת התווים האחרונים של מספר ההקצאה - ובדיווח המפורט הוא נדרש ברשומת התנועה, הן בצד העסקה והן בצד התשומה, בשדה מספרי באורך תשע ספרות.
- חשבונית שהודפסה בלי מספר הקצאה משאירה חור בקובץ הדיווח המפורט.
- המפרט מציין שההנחיה בביטול חשבונית מס היא לא לכלול את החשבונית ואת הביטול ב-PCN874.
- מסמך מקדים מסוג חשבון עסקה או פרופורמה מקבל קוד מסמך 332, ושיוך חשבוניות מס אליו נעשה בפנייה עם
ACTION=4. - המפרט מציין שהדפסת מספר ההקצאה תבליט את תשע הספרות הימניות תחת הכותרת "מספר הקצאה", בנוסף למספר האסמכתא הפנימי.
רקע על הקובץ עצמו ועל מה שנכנס אליו נמצא בקובץ PCN874 לדיווח מע\"מ מפורט.
מה כדאי לתעד כדי לענות מחר לרואה החשבון
- ה-
INVOICE_IDוגוף הבקשה המדויק שנשלח, בלי מספרי הזדהות בלוג. - קוד ה-HTTP, ערך
approved,confirmation_numberוכל אובייקטיerrorsכפי שהתקבלו. - שעת הפנייה ומספר הניסיונות, כדי להבדיל בין תקלה רגעית לבין החלטה יציבה.
- החלופה שנבחרה, מי בחר אותה, והתשובה משירות
Invoice-decision. - קישור בין רשומת החשבונית לבין הרשומה שנשלחה בדיווח המפורט.
בלי היומן הזה, שאלה פשוטה כמו "למה החשבונית הזאת יצאה בלי מספר" הופכת לחקירה של שעה. עם היומן הזה, היא שאילתה אחת.
מקורות
שאלות נפוצות
האם HTTP 200 אומר שהחשבונית אושרה?
לא בהכרח. המפרט מתאר תשובת 200 שבה `confirmation_number` הוא "0" ו-`approved` הוא false, ומורה לבדוק במקרה כזה את רשימת השגיאות. הבדיקה בקוד צריכה להיות על שדות הפלט עצמם ולא על קוד ה-HTTP בלבד.
מה ההבדל בין קוד 461 לקוד 462?
לפי המפרט, 461 מציין שהחשבונית הלא-מאושרת קיימת ולא נשלחה בגינה החלטה, ו-462 מציין שהחשבונית קיימת וההחלטה כבר נשלחה ולא נדרשת פעולה נוספת. השניים מבדילים בין מצב פתוח שממתין להחלטה לבין מצב סגור.
אפשר לשדר מחדש חשבונית אחרי תיקון?
כן. בתיקון של שגיאת תוכן משדרים מחדש. גם אחרי שימוע שבו החשבונית הותרה, המפרט מנחה לפנות שוב לשירות ההקצאה עם אותו `Invoice_Id` של החשבונית המקורית, כך שמספר ההקצאה שיתקבל יעודכן במערכת.
איך מטפלים בהמון חשבוניות בבת אחת?
המפרט מתאר שירות `MultiApproval` שמקבל מקבץ חשבוניות בפנייה אחת ומחזיר מספרי הקצאה משויכים ל-`INVOICE_ID` של כל חשבונית. חשבונית שקיבלה קוד שגיאה בתוך המקבץ מתוקנת ומשודרת מחדש בנפרד, ולא מחדש כמקבץ.
להמשך קריאה
שירות רלוונטי
אינטגרציות
לגרום למערכות שאתם כבר משלמים עליהן לדבר זו עם זו.
על הכותב
יהונתן סעדיה
מפתח פרילנסר לאוטומציה, אתרים ו-MVP
אני יהונתן סעדיה, מפתח בכיר שבונה אוטומציה עסקית, אתרים מותאמים ומוצרי MVP לעסקים קטנים ובינוניים בארה"ב, אירופה וישראל. המדריכים האלה נכתבים מתוך עבודה אמיתית עם לקוחות, לא מתיאוריה.
בוא נעבוד יחדיש לך פרויקט דומה?
ספר לי מה אתה רוצה לבנות או איזה תהליך להפוך לאוטומטי. אני חוזר תוך 24 שעות עסקים עם כמה שאלות ממוקדות, ואז עוברים על זה יחד בשיחת היכרות חינמית של 30 דקות, בלי התחייבות. בסוף יש לך היקף עבודה, לוח זמנים ומחיר קבוע - או תשובה כנה שלא שווה לבנות את זה.