مرجع فنی کامل سامانه مودیان

این راهنما بر اساس سند دستورالعمل فنی نحوه اتصال به سامانه مودیان (نسخه ۱۴۰۱۰۴۲۲) تهیه شده و شامل تمام جزئیات فنی مورد نیاز برای پیاده‌سازی اتصال به سامانه است.

---

فهرست مطالب

1. معماری کلی سامانه
2. ساختار شناسه یکتای مالیاتی (taxid)
3. فرآیند رمزنگاری و امضا
4. ساختار JSON صورتحساب
5. انواع صورتحساب
6. فیلدهای سرصورتحساب (Header)
7. فیلدهای اقلام (Body)
8. ساختار بسته (Packet)
9. API Endpoints
10. کدهای خطا
11. الگوریتم Verhoeff

---

معماری کلی سامانه

سامانه مودیان از معماری RESTful API استفاده می‌کند. ارتباط به دو صورت انجام می‌شود:

روش همگام (Sync)

• برای دریافت توکن، استعلام، دریافت لیست کالا
• پاسخ فوری دریافت می‌شود

روش غیرهمگام (Async)

• برای ارسال صورتحساب
• فقط شماره مرجع دریافت می‌شود
• استعلام وضعیت جداگانه

┌──────────────┐      ┌──────────────┐      ┌──────────────┐
│   Client     │──────▶│   Gateway    │──────▶│  Tax Core    │
│  (Your App)  │◀──────│   (tp.tax)   │◀──────│   Server     │
└──────────────┘      └──────────────┘      └──────────────┘
        │                    │                      │
        │  1. GET_TOKEN      │                      │
        │────────────────────▶                      │
        │◀────────────────────                      │
        │                    │                      │
        │  2. SEND_INVOICE   │                      │
        │────────────────────▶ (Async)              │
        │◀────────────────────                      │
        │  referenceNumber   │                      │
        │                    │                      │
        │  3. INQUIRY        │                      │
        │────────────────────▶ (Sync)               │
        │◀────────────────────                      │
        │  Final Status      │                      │

---

شناسه یکتای مالیاتی (taxid)

شناسه یکتای مالیاتی یک رشته ۲۲ کاراکتری است که برای هر صورتحساب یکتا است.

فرمول

taxid = fiscalId (6) + serial (10 hex) + date (6)

اجزاء

مثال

A1B2C3 + 0000000001 + 040315 = A1B2C30000000001040315

کد پیاده‌سازی (TypeScript)

import moment from 'moment-jalaali';

function generateTaxId(
    fiscalId: string,    // 6 chars
    serial: number       // incrementing number
): string {
    // Serial to 10-char hex
    const serialHex = serial.toString(16).toUpperCase().padStart(10, '0');
    
    // Jalali date YYMMDD
    const now = moment();
    const year = (now.jYear() % 100).toString().padStart(2, '0');
    const month = (now.jMonth() + 1).toString().padStart(2, '0');
    const day = now.jDate().toString().padStart(2, '0');
    const dateStr = `${year}${month}${day}`;
    
    return `${fiscalId}${serialHex}${dateStr}`;
}

// Example usage
const taxid = generateTaxId('A1B2C3', 1);
// Result: A1B2C30000000001040315

---

فرآیند رمزنگاری و امضا

مراحل آماده‌سازی صورتحساب

شکل ۱: نمودار آماده‌سازی صورتحساب

┌─────────────────────────────────────────────────────────────┐
│ 1. ساخت JSON صورتحساب                                       │
├─────────────────────────────────────────────────────────────┤
│ 2. نرمال‌سازی JSON (جدول ۱)                                  │
├─────────────────────────────────────────────────────────────┤
│ 3. امضای دیجیتال با RSA-SHA256                              │
├─────────────────────────────────────────────────────────────┤
│ 4. تولید کلید متقارن (AES-256) و IV (12 bytes)              │
├─────────────────────────────────────────────────────────────┤
│ 5. رمزگذاری داده با AES-256-GCM                             │
├─────────────────────────────────────────────────────────────┤
│ 6. رمزگذاری کلید متقارن با کلید عمومی سرور (RSA-OAEP)       │
├─────────────────────────────────────────────────────────────┤
│ 7. ساخت بسته نهایی                                          │
└─────────────────────────────────────────────────────────────┘

جدول ۱: نرمال‌سازی JSON

کد نرمال‌سازی

function normalizeJson(data: any): string {
    if (data === null) return 'null';
    if (typeof data === 'boolean') return data ? 'true' : 'false';
    if (typeof data === 'number') return data.toString();
    if (typeof data === 'string') return JSON.stringify(data);
    
    if (Array.isArray(data)) {
        const items = data.map(item => normalizeJson(item));
        return `[${items.join(',')}]`;
    }
    
    // Sort keys alphabetically
    const sortedKeys = Object.keys(data).sort();
    const parts = sortedKeys.map(key => {
        const value = normalizeJson(data[key]);
        return `"${key}":${value}`;
    });
    
    return `{${parts.join(',')}}`;
}

امضای دیجیتال (RSA-SHA256)

import * as crypto from 'crypto';

function signData(normalizedJson: string, privateKey: string): string {
    const sign = crypto.createSign('RSA-SHA256');
    sign.update(normalizedJson, 'utf8');
    const signature = sign.sign(privateKey, 'base64');
    return signature;
}

رمزگذاری AES-256-GCM

function encryptData(
    data: string, 
    symmetricKey: Buffer,  // 32 bytes
    iv: Buffer             // 12 bytes
): { encrypted: string; authTag: string } {
    const cipher = crypto.createCipheriv('aes-256-gcm', symmetricKey, iv);
    
    let encrypted = cipher.update(data, 'utf8', 'base64');
    encrypted += cipher.final('base64');
    
    const authTag = cipher.getAuthTag().toString('base64');
    
    return { encrypted, authTag };
}

رمزگذاری کلید متقارن با RSA

function encryptSymmetricKey(
    symmetricKey: Buffer, 
    serverPublicKey: string
): string {
    const encrypted = crypto.publicEncrypt(
        {
            key: serverPublicKey,
            padding: crypto.constants.RSA_PKCS1_OAEP_PADDING,
            oaepHash: 'sha256',
        },
        symmetricKey
    );
    return encrypted.toString('base64');
}

---

ساختار JSON صورتحساب

فرمت کلی

{
    "header": {
        "taxid": "A1B2C30000000001040315",
        "indatim": 1702800000000,
        "indati2m": 1702800000000,
        "inty": 1,
        "inp": 1,
        "ins": 1,
        "tins": "14001234567",
        "tob": 2,
        "bid": "1234567890",
        "tinb": "14009876543",
        "sbc": "1234567890",
        "bbc": "0987654321",
        "bpc": "1234567890",
        "ft": 1,
        "bpn": "09121234567",
        "scln": "خیابان ولیعصر",
        "scc": "",
        "crn": "",
        "billid": "",
        "tprdis": 1000000,
        "tdis": 50000,
        "tadis": 950000,
        "tvam": 95000,
        "todam": 0,
        "tbill": 1045000,
        "setm": 1,
        "cap": 1045000,
        "insp": 0,
        "tvop": 0,
        "tax17": 0,
        "inno": "0000000001"
    },
    "body": [
        {
            "sstid": "2720000044801",
            "sstt": "محصول نمونه",
            "am": 2,
            "mu": "164",
            "fee": 500000,
            "cfee": 0,
            "cut": 0,
            "exr": 0,
            "prdis": 1000000,
            "dis": 50000,
            "adis": 950000,
            "vra": 10,
            "vam": 95000,
            "odt": null,
            "odr": 0,
            "odam": 0,
            "olt": null,
            "olr": 0,
            "olam": 0,
            "consfee": 0,
            "spro": 0,
            "bros": 0,
            "tcpbs": 0,
            "cop": 0,
            "vop": 0,
            "bsrn": "",
            "tsstam": 1045000
        }
    ],
    "payments": []
}

---

انواع صورتحساب

نوع صورتحساب (inty)

الگوی صورتحساب (inp)

موضوع صورتحساب (ins)

---

فیلدهای سرصورتحساب (Header)

---

فیلدهای اقلام (Body)

فرمول‌های محاسبه

prdis = fee × am                    # مبلغ قبل از تخفیف
adis = prdis - dis                  # مبلغ بعد از تخفیف
vam = round(adis × vra / 100)       # مالیات بر ارزش افزوده
tsstam = adis + vam + odam + olam   # جمع کل قلم

# سرجمع:
tprdis = Σ(prdis)                   # جمع مبلغ قبل از تخفیف
tdis = Σ(dis)                       # جمع تخفیفات
tadis = tprdis - tdis               # جمع مبلغ بعد از تخفیف
tvam = Σ(vam)                       # جمع مالیات
tbill = tadis + tvam + todam        # جمع کل صورتحساب

---

ساختار بسته (Packet)

ساختار Request

{
    "packets": [
        {
            "uid": "550e8400-e29b-41d4-a716-446655440000",
            "packetType": "INVOICE.V01",
            "retry": false,
            "data": "BASE64_ENCRYPTED_DATA",
            "encryptionKeyId": "server-key-id-123",
            "symmetricKey": "BASE64_ENCRYPTED_SYMMETRIC_KEY",
            "iv": "BASE64_IV_12_BYTES",
            "fiscalId": "A1B2C3",
            "dataSignature": "BASE64_SIGNATURE"
        }
    ],
    "signature": "BASE64_REQUEST_SIGNATURE"
}

ساختار Response (Async)

{
    "signature": "",
    "signatureKeyId": "",
    "timestamp": 1702800000000,
    "result": {
        "uid": "550e8400-e29b-41d4-a716-446655440000",
        "referenceNumber": "REF-12345",
        "errorCode": null,
        "errorDetail": null
    }
}

---

API Endpoints

آدرس پایه

Production: https://tp.tax.gov.ir/req/api/self-tsp
Sandbox:    https://sandboxrc.tax.gov.ir/req/api/self-tsp

متدهای غیرهمگام (Async)

متدهای همگام (Sync)

---

کدهای خطا

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

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

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

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

---

الگوریتم Verhoeff

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

جداول الگوریتم

// جدول ضرب d
const d = [
    [0, 1, 2, 3, 4, 5, 6, 7, 8, 9],
    [1, 2, 3, 4, 0, 6, 7, 8, 9, 5],
    [2, 3, 4, 0, 1, 7, 8, 9, 5, 6],
    [3, 4, 0, 1, 2, 8, 9, 5, 6, 7],
    [4, 0, 1, 2, 3, 9, 5, 6, 7, 8],
    [5, 9, 8, 7, 6, 0, 4, 3, 2, 1],
    [6, 5, 9, 8, 7, 1, 0, 4, 3, 2],
    [7, 6, 5, 9, 8, 2, 1, 0, 4, 3],
    [8, 7, 6, 5, 9, 3, 2, 1, 0, 4],
    [9, 8, 7, 6, 5, 4, 3, 2, 1, 0],
];

// جدول جایگشت p
const p = [
    [0, 1, 2, 3, 4, 5, 6, 7, 8, 9],
    [1, 5, 7, 6, 2, 8, 3, 0, 9, 4],
    [5, 8, 0, 3, 7, 9, 6, 1, 4, 2],
    [8, 9, 1, 6, 0, 4, 3, 5, 2, 7],
    [9, 4, 5, 3, 1, 2, 6, 8, 7, 0],
    [4, 2, 8, 6, 5, 7, 3, 9, 0, 1],
    [2, 7, 9, 3, 8, 0, 6, 4, 1, 5],
    [7, 0, 4, 6, 9, 1, 3, 2, 5, 8],
];

// جدول معکوس
const inv = [0, 4, 3, 2, 1, 5, 6, 7, 8, 9];

اعتبارسنجی

function validateVerhoeff(num: string): boolean {
    let c = 0;
    const numArray = num.split('').reverse().map(Number);
    
    for (let i = 0; i < numArray.length; i++) {
        c = d[c][p[i % 8][numArray[i]]];
    }
    
    return c === 0;
}

---

چک‌لیست پیاده‌سازی

قبل از شروع

• دریافت شناسه حافظه مالیاتی (fiscalId) از سازمان
• ساخت جفت کلید RSA (2048 یا 4096 بیت)
• بارگذاری کلید عمومی در سامانه
• دریافت کلید عمومی سرور

پیاده‌سازی

• پیاده‌سازی نرمال‌سازی JSON
• پیاده‌سازی امضای RSA-SHA256
• پیاده‌سازی رمزگذاری AES-256-GCM
• پیاده‌سازی تولید taxid
• پیاده‌سازی اعتبارسنجی Verhoeff
• مدیریت شماره سریال با DB

تست

• تست در محیط Sandbox
• بررسی محاسبات صورتحساب
• تست ابطال و اصلاح
• تست مدیریت خطا

---

منابع

• سند دستورالعمل فنی سامانه مودیان (PDF)
• سامانه استعلام کالا
• پرتال مودیان

---

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