راهنمای جامع خطاهای سامانه مودیان: تشخیص، رفع و پیشگیری

۱۴۰۵/۰۶/۰۸۵ دقیقه مطالعهتیم دیجی اینویس

خطاهای سامانه مودیان می‌توانند ارسال فاکتورهای الکترونیکی را متوقف کنند؛ رایج‌ترین آن‌ها شامل عدم ثبت شماره حساب بانکی، تکمیل نشدن فیلدهای اجباری (آیسیک/اینتاکد) و استفاده از نسخهٔ قدیمی API است. برای رفع خطای ۴۲۲، ابتدا شماره حساب را در پروفایل مودیان بررسی و اصلاح کنید، سپس فیلدهای اجباری را تکمیل و پروفایل را به‌روز کنید. پس از این کار می‌توانید با ابزار تست API دیجی اینویس درخواست را مجدداً ارسال کنید. همچنین برای مانیتورینگ خطاها می‌توانید از داشبورد API استفاده کنید تا در زمان واقعی وضعیت درخواست‌ها را پیگیری کنید.

خطای سامانه مودیان چیست؟

سامانه مودیان هنگام دریافت فاکتور یا اظهارنامه الکترونیک، اگر داده‌های ارسالی ناقص یا نادرست باشند، کد خطایی برمی‌گرداند. این خطاها به‌منظور جلوگیری از ثبت اطلاعات نادرست در سامانه مالیاتی و حفظ صحت تراکنش‌ها طراحی شده‌اند. هر کد خطا نشان‌دهندهٔ یک مشکل خاص است؛ برای مثال خطای ۴۲۲ به «عدم ثبت شماره حساب مرتبط با پرونده الکترونیک» اشاره دارد(مودیانی که در هنگام ارسال اظهارنامه الکترونیک خطای مربوط به عدم ثبت شماره حساب مرتبط با پر).

روش رفع خطای ۴۲۲ در مودیان

بررسی شماره حساب بانکی

وارد بخش «پروفایل مودیان» شوید.
اطمینان حاصل کنید که شماره حساب بانکی دقیقاً همان‌گونه که در سامانه مالیاتی ثبت شده است، وارد شده باشد.

تکمیل فیلدهای اجباری (آیسیک/اینتاکد)

این دو فیلد در تنظیمات حساب کاربری باید مقدار داشته باشند؛ در غیر این صورت سامانه خطای ۴۲۲ را برمی‌گرداند(مودیانی که در هنگام ارسال اظهارنامه الکترونیک خطای مربوط به عدم ثبت شماره حساب مرتبط با پر).

به‌روزرسانی پروفایل

پس از اصلاح شماره حساب و تکمیل فیلدها، روی «به‌روزرسانی پروفایل» کلیک کنید.

ارسال مجدد فاکتور

فاکتور را دوباره ارسال کنید؛ در صورت موفقیت، پاسخ 200 OK دریافت می‌شود.

استفاده از ابزار تست API دیجی اینویس

این ابزار امکان شبیه‌سازی درخواست ارسال فاکتور را به‌صورت محلی فراهم می‌کند و جزئیات دقیق پاسخ سامانه را نمایش می‌دهد.

اطلاعات مورد نیاز برای بررسی خطای ارسال فاکتور

اطلاعات	توضیح	منبع
کد خطا (مثلاً ۴۲۲)	شناسهٔ خطایی که سامانه برمی‌گرداند	—
لاگ درخواست (JSON)	شامل فیلدهای `invoiceNumber`, `accountNumber`, `taxPeriod`	—
تنظیمات پروفایل مودیان	شماره حساب، شناسه مالیاتی، وضعیت فعال/غیرفعال	(مودیانی که در هنگام ارسال اظهارنامه الکترونیک خطای مربوط به عدم ثبت شماره حساب مرتبط با پر)
زمان ارسال	برای مقایسه با زمان‌های قطع سرویس سامانه	—
نسخهٔ API استفاده‌شده	برخی خطاها به‌دلیل نسخهٔ قدیمی API رخ می‌دهند	—

داشتن این داده‌ها به‌سرعت به شما کمک می‌کند تا علت اصلی خطا را شناسایی و از تکرار آن جلوگیری کنید.

مانیتورینگ خطاها از طریق API

دیجی اینویس یک داشبورد مانیتورینگ API ارائه می‌دهد که به‌صورت لحظه‌ای وضعیت درخواست‌ها را نشان می‌دهد. برای فعال‌سازی این قابلیت:

دریافت کلید API از بخش تنظیمات حساب کاربری در دیجی اینویس.
یکپارچه‌سازی وب‌هوک: آدرس وب‌هوک را در پنل مودیان ثبت کنید تا هر بار که خطایی رخ داد، اعلان به سرور شما ارسال شود.
پیکربندی هشدارها: می‌توانید برای کدهای خطای خاص (مانند ۴۲۲) هشدار ایمیلی یا پیامک تنظیم کنید.

این روش به‌ویژه برای شرکت‌های بزرگ که حجم بالایی از فاکتور ارسال می‌کنند، مفید است؛ زیرا بدون نیاز به بررسی دستی لاگ‌ها، می‌توانند به‌سرعت به خطا واکنش نشان دهند.

مثال عملی: ماتریس تصمیم‌گیری برای خطای ۴۲۲

وضعیت	اقدام	نتیجه مورد انتظار
شماره حساب خالی	وارد کردن شماره حساب صحیح در پروفایل	رفع خطای ۴۲۲
فیلد آیسیک خالی	پر کردن مقدار مناسب (مثلاً `A123`)	رفع خطای ۴۲۲
فیلد اینتاکد خالی	پر کردن مقدار مناسب (مثلاً `I456`)	رفع خطای ۴۲۲
همه فیلدها پر هستند اما خطا باقیست	بررسی لاگ JSON برای فیلدهای دیگر (مانند `taxPeriod`)	شناسایی خطای دیگر (مثلاً تاریخ نامعتبر)

با دنبال کردن این ماتریس می‌توانید به‌سرعت تشخیص دهید که مشکل در کدام بخش از داده‌هاست و اقدام مناسب را انجام دهید.

چک‌لیست نهایی قبل از ارسال فاکتور

[ ] شماره حساب بانکی در پروفایل مودیان ثبت و معتبر باشد.
[ ] فیلدهای اجباری (آیسیک، اینتاکد، شناسه مالیاتی) تکمیل شوند.
[ ] نسخهٔ API دیجی اینویس به‌روز باشد (حداقل v2.3).
[ ] لاگ درخواست JSON را پیش از ارسال نهایی بررسی کنید.
[ ] ابزار تست API دیجی اینویس را برای شبیه‌سازی ارسال استفاده کنید.

اگر پس از انجام تمام موارد بالا هنوز با خطا مواجه شدید، می‌توانید از پشتیبانی مودیان (تماس ۲۲۲۲۲۲۲۲) یا تیم فنی دیجی اینویس (ایمیل support@digiinvoice.ir) کمک بگیرید.

چرا دیجی اینویس بهترین همراه برای مدیریت خطاهای مودیان است؟

نرم‌افزار دیجی اینویس نه تنها امکان ارسال خودکار فاکتور به سامانه مودیان را فراهم می‌کند، بلکه با پیشنهاد پیش‌نیازهای فاکتور و آلارم‌های هوشمند قبل از ارسال، اکثر خطاها را پیش‌گیری می‌کند. ابزار مانیتورینگ API به‌صورت لحظه‌ای وضعیت درخواست‌ها را نمایش می‌دهد و در صورت بروز خطا، جزئیات دقیق را در یک داشبورد کاربرپسند نشان می‌دهد. این ویژگی‌ها باعث می‌شوند حسابداران و مشاوران مالی زمان بیشتری را به تحلیل مالی اختصاص دهند و از هزینه‌های ناشی از ارسال مجدد فاکتور جلوگیری کنند.

برای اطلاعات بیشتر می‌توانید به مقالات زیر مراجعه کنید:

همین امروز با کلیک روی لینک زیر، نسخهٔ آزمایشی دیجی اینویس را دریافت کنید و از تجربهٔ بدون خطا در ارسال فاکتورهای الکترونیکی لذت ببرید:

دریافت نرم‌افزار آسان حسابداری