راهنمای کامل خطاهای سامانه مودیان

این راهنما شامل تمام کدهای خطای سامانه مودیان بر اساس جدول ۱۴ سند دستورالعمل فنی است. هر خطا با توضیح، علت و راه‌حل ارائه شده است.

💡 برای آشنایی با ساختار فنی سامانه، مرجع فنی کامل مودیان را مطالعه کنید.

---

فهرست دسته‌بندی خطاها

دسته	کدها	توضیح
عمومی	00XXX	خطاهای سیستمی
ساختار	00XXX	خطاهای ساختار JSON
رمزنگاری	00XXX	خطاهای امضا و رمزگذاری
صورتحساب	01XXXXX	خطاهای هدر فاکتور
کالا	03XXXXX	خطاهای شناسه کالا
مالیات	04XXXXX	خطاهای نرخ مالیات
محاسبات	05XXXXX	خطاهای مبالغ
ارجاع	06XXXXX	خطاهای صورتحساب مرجع

---

خطاهای عمومی (00XXX)

00000 - موفق ✅

پیام: عملیات با موفقیت انجام شد

توضیح: این کد نشان‌دهنده موفقیت است، نه خطا.

---

00001 - خطای داخلی سرور

پیام: Internal server error

علت:

• مشکل موقت در سرورهای سازمان مالیاتی
• بار زیاد سرور

راه‌حل:

1. ۵ دقیقه صبر کنید
2. تلاش مجدد با exponential backoff
3. در صورت تداوم، با پشتیبانی سازمان تماس بگیرید

⏱️ زمان انتظار پیشنهادی:
- تلاش ۱: ۵ ثانیه
- تلاش ۲: ۱۵ ثانیه
- تلاش ۳: ۴۵ ثانیه
- تلاش ۴: ۱۳۵ ثانیه (۲ دقیقه)

---

00002 - درخواست نامعتبر

پیام: Invalid request format

علت:

• ساختار JSON نامعتبر
• فیلدهای الزامی خالی
• نوع داده اشتباه

راه‌حل:

1. ساختار JSON را validate کنید
2. فیلدهای الزامی را بررسی کنید
3. انواع داده را مطابق مستندات تنظیم کنید

---

00003 - احراز هویت ناموفق

پیام: Authentication failed

علت:

• توکن منقضی شده
• توکن نامعتبر
• شناسه حافظه مالیاتی غیرفعال

راه‌حل:

1. توکن جدید با GET_TOKEN دریافت کنید
2. صحت شناسه حافظه مالیاتی را بررسی کنید
3. از فعال بودن حافظه مالیاتی مطمئن شوید

---

00004 - دسترسی غیرمجاز

پیام: Access denied

علت:

• مجوز ارسال صورتحساب ندارید
• محدودیت IP
• تعلیق موقت حساب

راه‌حل:

1. از داشبورد my.tax.gov.ir مجوزها را بررسی کنید
2. با پشتیبانی سازمان تماس بگیرید

---

00005 - محدودیت نرخ (Rate Limit)

پیام: Too many requests

علت:

• تعداد درخواست‌ها از حد مجاز فراتر رفته
• ارسال همزمان بیش از حد

راه‌حل:

1. بین درخواست‌ها فاصله بگذارید
2. از صف (Queue) برای ارسال استفاده کنید
3. حداکثر ۱۰ صورتحساب در دقیقه ارسال کنید

---

خطاهای رمزنگاری و امضا

00006 - خطای رمزگذاری

پیام: Encryption error

علت:

• کلید متقارن اشتباه تولید شده
• IV نامعتبر (باید ۱۲ بایت باشد)
• الگوریتم AES-GCM به درستی پیاده‌سازی نشده

راه‌حل:

1. طول کلید متقارن را ۳۲ بایت (AES-256) تنظیم کنید
2. IV را دقیقاً ۱۲ بایت تولید کنید
3. از AES-256-GCM استفاده کنید

// صحیح
const symmetricKey = crypto.randomBytes(32); // 256 bits
const iv = crypto.randomBytes(12);           // 96 bits
const cipher = crypto.createCipheriv('aes-256-gcm', symmetricKey, iv);

---

00600 - خطای امضای دیجیتال ⚠️

پیام: Signature verification failed

این یکی از شایع‌ترین خطاهاست!

علت‌های رایج:

1. نرمال‌سازی JSON اشتباه (۹۰٪ موارد)
2. کلید خصوصی نامعتبر
3. الگوریتم امضا اشتباه

راه‌حل‌های دقیق:

۱. نرمال‌سازی JSON صحیح

// ❌ اشتباه - کلیدها مرتب نیستند
{ "name": "test", "age": 20 }

// ✅ صحیح - کلیدها به ترتیب ASCII
{ "age": 20, "name": "test" }

// ❌ اشتباه - فاصله اضافی
{ "age" : 20 }

// ✅ صحیح - بدون فاصله
{"age":20}

۲. کد نرمال‌سازی صحیح

function normalizeJson(obj: any): string {
    if (obj === null) return 'null';
    if (typeof obj === 'boolean') return obj.toString();
    if (typeof obj === 'number') return obj.toString();
    if (typeof obj === 'string') return JSON.stringify(obj);
    
    if (Array.isArray(obj)) {
        return '[' + obj.map(normalizeJson).join(',') + ']';
    }
    
    // مرتب‌سازی کلیدها به ترتیب ASCII
    const sortedKeys = Object.keys(obj).sort();
    const parts = sortedKeys.map(key => 
        '"' + key + '":' + normalizeJson(obj[key])
    );
    return '{' + parts.join(',') + '}';
}

۳. امضای صحیح

const crypto = require('crypto');

const normalized = normalizeJson(invoiceData);
const sign = crypto.createSign('RSA-SHA256');
sign.update(normalized, 'utf8');
const signature = sign.sign(privateKey, 'base64');

---

00601 - شناسه کلید رمزگذاری نامعتبر

پیام: Invalid encryption key ID

علت:

• encryptionKeyId با کلید فعال سرور مطابقت ندارد
• کلید سرور تغییر کرده

راه‌حل:

1. کلیدهای سرور را با GET_SERVER_INFORMATION دریافت کنید
2. از آخرین keyId فعال استفاده کنید
3. کلیدها را روزانه بروزرسانی کنید

---

خطاهای صورتحساب (01XXXXX)

0100501 - شناسه یکتای مالیاتی تکراری

پیام: Duplicate tax ID (taxid)

علت:

• این taxid قبلاً ارسال شده
• شماره سریال تکراری

راه‌حل:

1. از شماره سریال یکتا استفاده کنید
2. شمارنده سریال را در دیتابیس ذخیره کنید
3. از SELECT FOR UPDATE برای جلوگیری از race condition استفاده کنید

// فرمول taxid
taxid = fiscalId(6) + serial(10 hex) + date(6)

---

0100502 - فرمت شناسه یکتا نامعتبر

پیام: Invalid tax ID format

علت:

• طول taxid برابر ۲۲ کاراکتر نیست
• کاراکترهای غیرمجاز

راه‌حل:

// taxid باید دقیقاً ۲۲ کاراکتر باشد
// fiscalId: 6 کاراکتر alphanumeric
// serial: 10 کاراکتر hex (0-9, A-F)
// date: 6 رقم (YYMMDD شمسی)

✅ A1B2C30000000001040315  (22 chars)
❌ A1B2C3000001040315      (18 chars - کوتاه)

---

0100503 - تاریخ صدور نامعتبر

پیام: Invalid invoice date (indatim)

علت:

• indatim در آینده است
• تاریخ خیلی قدیمی (بیش از ۳۰ روز)
• فرمت Unix timestamp اشتباه

راه‌حل:

1. تاریخ به میلی‌ثانیه Unix باشد
2. تاریخ نباید در آینده باشد
3. حداکثر ۱۲ روز از تاریخ صدور گذشته باشد

// صحیح
const indatim = Date.now(); // میلی‌ثانیه

// ❌ اشتباه - ثانیه به جای میلی‌ثانیه
const wrong = Math.floor(Date.now() / 1000);

---

0100504 - کد اقتصادی فروشنده نامعتبر

پیام: Invalid seller economic code (tins)

علت:

• کد اقتصادی در سامانه ثبت نشده
• فرمت کد اقتصادی اشتباه
• رقم کنترل Verhoeff نامعتبر

راه‌حل:

1. کد اقتصادی را از my.tax.gov.ir استعلام کنید
2. کد باید ۱۱ یا ۱۲ رقم باشد
3. الگوریتم Verhoeff را اجرا کنید

function validateEconomicCode(code: string): boolean {
    if (code.length !== 11 && code.length !== 12) return false;
    if (code.length === 12) {
        return validateVerhoeff(code);
    }
    return true;
}

---

0100505 - کد پستی فروشنده نامعتبر

پیام: Invalid seller postal code (sbc)

علت:

• کد پستی ۱۰ رقم نیست
• کد پستی با ۰ شروع شده
• رقم سوم برابر ۲ است

راه‌حل:

function validatePostalCode(code: string): boolean {
    if (code.length !== 10) return false;
    if (code[0] === '0') return false;
    if (code[2] === '2') return false;
    return /^\d{10}$/.test(code);
}

---

0100506 - کد اقتصادی خریدار الزامی

پیام: Buyer economic code required for Type 1

علت:

• صورتحساب نوع ۱ (B2B) بدون اطلاعات خریدار

راه‌حل: برای inty = 1:

• tinb (کد اقتصادی خریدار) یا
• bid (شناسه ملی خریدار) الزامی است.

---

0100507 - نوع صورتحساب نامعتبر

پیام: Invalid invoice type (inty)

راه‌حل:

// مقادیر مجاز inty
1 = نوع ۱ (B2B - خریدار شناخته شده)
2 = نوع ۲ (B2C - خریدار ناشناس)
3 = نوع ۳ (صادراتی)

---

0100508 - الگوی صورتحساب نامعتبر

پیام: Invalid invoice pattern (inp)

راه‌حل:

// مقادیر مجاز inp
1 = فروش
2 = برگشت از فروش
3 = ابطالی
4 = اصلاحی

---

0100509 - موضوع صورتحساب نامعتبر

پیام: Invalid invoice subject (ins)

راه‌حل:

// مقادیر مجاز ins
1 = اصلی
2 = الحاقی
3 = ابطالی
4 = اصلاحی
5 = برگشت از فروش

---

0100510 - شماره داخلی نامعتبر

پیام: Invalid internal number (inno)

راه‌حل:

• inno باید دقیقاً ۱۰ کاراکتر hex باشد

// صحیح
"0000000001"
"ABCDEF1234"

// اشتباه
"1234"        // کوتاه
"GHIJ123456"  // کاراکتر غیرمجاز

---

خطاهای کالا (03XXXXX)

0303301 - عدم تطابق شناسه کالا و نرخ مالیات ⚠️

پیام: Commodity ID and tax rate mismatch

این خطای بسیار رایج است!

علت:

• شناسه کالا (sstid) با نرخ مالیات (vra) همخوانی ندارد
• کالای معاف با نرخ غیرصفر ارسال شده

راه‌حل:

1. شناسه کالا را از stuffid.tax.gov.ir استعلام کنید
2. نرخ مالیات را مطابق نوع کالا تنظیم کنید

// نرخ‌های رایج
کالای معمولی: vra = 10%
کالای معاف: vra = 0%
کالای لوکس: نرخ خاص

---

0303302 - شناسه کالا یافت نشد

پیام: Commodity ID not found (sstid)

علت:

• شناسه کالا در پایگاه داده سازمان وجود ندارد
• اشتباه تایپی

راه‌حل:

1. از سامانه stuffid.tax.gov.ir شناسه را استعلام کنید
2. از شناسه عمومی استفاده کنید

// شناسه‌های عمومی پرکاربرد
"2720000044801" // کالای عمومی
"2720000046201" // خدمات عمومی

---

0303303 - واحد اندازه‌گیری نامعتبر

پیام: Invalid measurement unit (mu)

راه‌حل:

// واحدهای پرکاربرد
"164" = عدد
"116" = کیلوگرم
"118" = گرم
"112" = متر
"161" = بسته
"175" = جفت

---

خطاهای مالیات (04XXXXX)

0401001 - مبلغ مالیات قلم اشتباه

پیام: Item VAT amount incorrect (vam)

فرمول صحیح:

vam = round(adis × vra / 100)

مثال:

adis = 950000  // مبلغ بعد از تخفیف
vra = 10       // نرخ مالیات ۱۰٪

vam = round(950000 × 10 / 100)
vam = 95000    // ✅ صحیح

---

0401002 - نرخ مالیات نامعتبر

پیام: Invalid tax rate (vra)

راه‌حل:

• vra باید بین ۰ تا ۱۰۰ باشد
• معمولاً ۰، ۹ یا ۱۰

---

خطاهای محاسبات (05XXXXX)

0501001 - مبلغ بعد از تخفیف اشتباه

پیام: Amount after discount incorrect (adis)

فرمول:

adis = prdis - dis

---

0501002 - مبلغ قبل از تخفیف اشتباه

پیام: Amount before discount incorrect (prdis)

فرمول:

prdis = fee × am

مثال:

fee = 500000   // قیمت واحد
am = 2         // تعداد

prdis = 500000 × 2
prdis = 1000000  // ✅ صحیح

---

0501003 - جمع کل صورتحساب اشتباه

پیام: Total bill amount incorrect (tbill)

فرمول:

tbill = tadis + tvam + todam

مثال:

tadis = 950000   // جمع بعد از تخفیف
tvam = 95000     // جمع مالیات
todam = 0        // سایر مالیات‌ها

tbill = 950000 + 95000 + 0
tbill = 1045000  // ✅ صحیح

---

0501004 - جمع تخفیفات اشتباه

پیام: Total discount incorrect (tdis)

فرمول:

tdis = Σ(dis)  // مجموع تخفیف تمام اقلام

---

0501005 - جمع مالیات اشتباه

پیام: Total VAT incorrect (tvam)

فرمول:

tvam = Σ(vam)  // مجموع مالیات تمام اقلام

---

خطاهای ارجاع (06XXXXX)

0600001 - شناسه مرجع الزامی

پیام: Reference tax ID required (irtaxid)

علت:

• صورتحساب ابطالی/اصلاحی/برگشتی بدون مرجع

راه‌حل: برای الگوهای ۲، ۳ و ۴:

irtaxid = "taxid صورتحساب اصلی"

---

0600002 - صورتحساب مرجع یافت نشد

پیام: Reference invoice not found

علت:

• irtaxid در سیستم موجود نیست
• صورتحساب اصلی هنوز تأیید نشده

راه‌حل:

1. صبر کنید تا صورتحساب اصلی تأیید شود
2. taxid صحیح را وارد کنید

---

0600003 - صورتحساب مرجع قبلاً ابطال شده

پیام: Reference invoice already cancelled

علت:

• قصد ابطال صورتحساب ابطال شده را دارید

راه‌حل: هر صورتحساب فقط یک بار قابل ابطال است.

---

جدول خلاصه کدهای خطا

کد	نوع	پیام فارسی	قابل تلاش مجدد
00000	موفق	موفق	-
00001	سیستم	خطای داخلی سرور	✅
00002	ساختار	درخواست نامعتبر	❌
00003	احراز	احراز هویت ناموفق	✅
00004	احراز	دسترسی غیرمجاز	❌
00005	سیستم	محدودیت نرخ	✅
00006	رمزنگاری	خطای رمزگذاری	❌
00600	امضا	خطای امضا	❌
0100501	صورتحساب	taxid تکراری	❌
0100504	صورتحساب	کد اقتصادی فروشنده	❌
0303301	کالا	عدم تطابق کالا و نرخ	❌
0303302	کالا	شناسه کالا نامعتبر	❌
0401001	مالیات	مبلغ مالیات اشتباه	❌
0501002	محاسبه	prdis اشتباه	❌
0501003	محاسبه	tbill اشتباه	❌
0600001	ارجاع	مرجع الزامی	❌

---

نکات مهم

۱. استراتژی تلاش مجدد

// فقط برای خطاهای قابل تلاش مجدد
const RETRYABLE_ERRORS = ['00001', '00003', '00005'];

async function submitWithRetry(invoice, maxRetries = 3) {
    for (let i = 0; i < maxRetries; i++) {
        try {
            return await submit(invoice);
        } catch (error) {
            if (!RETRYABLE_ERRORS.includes(error.code)) {
                throw error; // خطای غیرقابل تلاش
            }
            await sleep(Math.pow(2, i) * 5000); // exponential backoff
        }
    }
}

۲. اعتبارسنجی قبل از ارسال

با اعتبارسنجی محلی، ۹۰٪ خطاها قبل از ارسال قابل شناسایی هستند.

۳. لاگ‌گذاری

تمام خطاها را با جزئیات ذخیره کنید تا در صورت نیاز قابل پیگیری باشند.

---

سوالات متداول

چرا خطای ۰۰۶۰۰ می‌گیرم؟

نرمال‌سازی JSON را بررسی کنید. کلیدها باید به ترتیب ASCII مرتب باشند.

چرا خطای ۰۳۰۳۳۰۱ می‌گیرم؟

شناسه کالا با نرخ مالیات مطابقت ندارد. از سامانه stuffid.tax.gov.ir استعلام کنید.

آیا می‌توان صورتحساب ابطال شده را دوباره ابطال کرد؟

خیر، هر صورتحساب فقط یک بار قابل ابطال است.

---

منابع

• سند دستورالعمل فنی - جدول ۱۴
• سامانه استعلام کالا
• مرجع فنی کامل مودیان

---

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