سامانه مودیان مالیاتی، هسته نظام مالیات هوشمند و شفاف ایران است. این سامانه بستر ثبت، ارسال و پردازش صورت‌حساب‌های الکترونیکی کسب‌وکارها، شرکت‌ها و اصناف ایران را فراهم می‌کند. در این فرایند، سرویس‌های وب و نرم‌افزارهای واسط باید اطلاعات را به فرمتی استاندارد و امن ارسال و دریافت کنند.
اما در این مسیر انواع خطاها ممکن است رخ دهد که «کد خطاهای سامانه مودیان» به طور رسمی همه آن‌ها را فهرست، دسته‌بندی و شرح می‌دهد. شناخت این خطاها برای رفع سریع مشکلات فنی و کاربری اهمیت بالایی دارد.
ساختار و دسته‌بندی خطاها
سند «کد خطاهای سامانه مودیان» خطاها را به چند دسته اصلی و جداول مرجع تقسیم می‌کند:
- خطاهای احراز هویت (Authentication Errors):
- مربوط به توکن‌های امضا شده، گواهی امضای دیجیتال مودی، اعتبار کلاینت و زمان‌بندی‌ها.
- کدها معمولاً با ۴۱ شروع می‌شوند (HTTP 401).
- نمونه: تطابق نداشتن کد ملی، مشکل امضا یا ساختار ناقص توکن JWT، منقضی بودن یا عدم اعتبار کلاینت.
- خطاهای وب‌سرویس ارسال صورت‌حساب و استعلام (API Request/Response Errors):
- اختلال در برقراری ارتباط، پارامترهای نامعتبر، ساختار JSON اشتباه، خطای سرور یا خطای ناشناخته.
- خطاهایی با کد ۴ (اشکال درخواست کاربر/کلاینت) و کد ۵ (اشکال سرور/سیستمی).
- خطاهای لایه انتقال:
- مشکلات تبادل داده بین نرم‌افزار و سامانه (فرمت پیام، رمزنگاری، بسته امضا شده و …).
- بررسی درست ارسال فایل، امضای دیجیتال و صحت اتصال.
- خطاهای لایه محتوا (Content Validation Errors):
- ایراد در داده‌های صورت‌حساب، مانند مقادیر اشتباه، مقادیر خالی، نوع نامعتبر و تکرار مقادیر.
- اعتبارسنجی چک لیست:
- پر یا خالی بودن فیلدها
- درستی ساختار مقادیر (رشته‌ای، عددی و …)
- انطباق با اسناد راهنما
- خطاهای پرتکرار و نکات کلیدی (Common Errors):
- مجموعه‌ای از خطاهای پرتکرار توسط کاربران (مثلاً ارسال اطلاعات ناقص، مشکلات گواهینامه، فایل ضمیمه نامعتبر و غیره).
- جدول شناسه فیلدهای صورت‌حساب:
- مشخصات و استانداردهای هر فیلد دیتای صورت‌حساب جهت اعتبارسنجی.
نمونه‌هایی از مهمترین خطاها و پیام‌های مرتبط
کد خطا شرح خطا
| ۴۱۰۱ | Bearer Token ارسال نشد یا نامعتبر است |
| ۴۱۰۲ | چالش تصادفی در JWT معتبر نیست (مصرف شده یا تاریخ گذشته) |
| ۴۱۰۳ | کد ملی گواهی امضا با شناسه کلاینت مطابقت ندارد |
| ۴۱۳۱ | ساختار JWT فرستاده‌شده معتبر نیست |
| ۵۰۰۰ | خطای سرور (مشکل سیستم مرکزی/backend) |
| ۴۲۰۰ | مقدار یکی از فیلدها معتبر نیست (اصلاً ارسال نشده یا مغایر است) |
| دیگر | هنوز بخشی از داده اجباری ارسال نشده، گواهی امضا معتبر نیست و … |
نکات کاربردی برای کاربران نرم‌افزارهای مالی و شرکت‌ها
- هنگام دریافت خطا، ابتدا کد خطا و متن پیام را یادداشت کنید.
- خطاهای احراز هویت معمولاً با توکن، نام کاربری/گواهینامه یا مدت اعتبار کلاینت مرتبط‌اند.
- در خطاهای محتوا به صحت و کامل بودن اطلاعات صورت‌حساب اهمیت دهید.
- در صورت بروز خطای سرور (کد ۵)، کمی صبر کرده و مجدداً آزمون کنید یا با پشتیبانی تماس بگیرید.
- برای کدنویسان: مستندات و اسناد استاندارد را حتماً به‌روز نگه دارید؛ تغییرات نسخه‌ها می‌تواند ساختار خطا را عوض کند.
- سامانه به صورت دوره‌ای خطاهای پرتکرار را بروزرسانی می‌کند، فایل راهنما را دریافت و مرور کنید.
این راهنما بر مبنای سند رسمی اسفند ۱۴۰۲ سازمان امور مالیاتی کشور تنظیم شده تا به زبان ساده، قابل فهم و سریع، مرجعی برای رفع خطاهای سامانه مودیان در اختیار مدیران مالی، کدنویسان، کاربران نرم‌افزارها و مشتریان سپید سیستم تهران و سپیدار قرار گیرد.
در صورت مشاهده هرگونه خطای غیرقابل رفع یا جدید، مستندات جدید را بررسی کنید یا از سامانه پشتیبانی مالیاتی کمک بگیرید.
منبع: سند رسمی «کد خطاهای سامانه مودیان» منتشرشده توسط مرکز تنظیم مقررات سازمان امور مالیاتی کشور (اسفند ۱۴۰۲)
دیدگاه خود را بنویسید