README

کلاینت PHP سبک و مستقل (بدون وابستگی به کتابخانه‌ی جانبی) برای اتصال به سامانه مودیان (سازمان امور مالیاتی کشور) جهت صدور، ابطال، استعلام وضعیت و ثبت پرداخت صورتحساب‌های الکترونیکی.

A lightweight, dependency-free PHP client for Iran's e-invoicing system (سامانه مودیان / tax.gov.ir). Handles invoice signing (JWS), encryption (JWE), unique TaxID generation with Verhoeff checksum, sending, cancellation, status inquiry, and payment registration.

✨ امکانات

ساخت و امضای دیجیتال صورتحساب (JWS) و رمزنگاری آن (JWE / RSA-OAEP-256 + AES-256-GCM) دقیقاً طبق پروتکل سامانه مودیان — بدون نیاز به کتابخانه‌ی JOSE جانبی.
تولید شماره منحصربه‌فرد مالیاتی (taxId) مطابق سند رسمی RC_DCPS.SN_V1.3 سازمان امور مالیاتی، شامل محاسبه‌ی صحیح رقم کنترلی با الگوریتم Verhoeff.
ارسال صورتحساب اصلی، اصلاحی، ابطالی و برگشت از فروش.
ارسال گروهی صورتحساب‌ها (تا ۱۰۰۰ عدد در هر درخواست).
استعلام وضعیت پردازش با uid یا با taxId، به همراه ترجمه‌ی خطاهای هفت‌رقمی سامانه به فیلد، نوع اعتبارسنجی و شدت خطا.
اعتبارسنجی محلی کامل صورتحساب (validateInvoice) پیش از ارسال، تا خطاهای ساختاری زودتر و بدون نیاز به تماس شبکه‌ای شناسایی شوند.
ثبت پرداخت صورتحساب (registerPayment).
لاگ‌گیری اختیاری برای دیباگ (enableLogging).

⚠️ درباره‌ی این ریپازیتوری

این کلاس بر پایه‌ی مستندات فنی رسمی سامانه مودیان (RC_DCPS.SN_V1.3, خرداد ۱۴۰۱) و آزمایش عملی روی محیط sandbox و production نوشته و اصلاح شده است. با این حال:

این یک پروژه‌ی غیررسمی و متن‌باز است و به سازمان امور مالیاتی کشور وابسته نیست.
قبل از استفاده در محیط عملیاتی (production)، حتماً با چند صورتحساب آزمایشی در محیط sandbox تست کنید.
مسئولیت صحت اطلاعات مالیاتی ارسالی (مبالغ، شناسه‌های کالا، اطلاعات طرفین معامله) بر عهده‌ی استفاده‌کننده است.

📋 پیش‌نیازها

PHP >= 7.4
اکستنشن‌های curl، openssl، json
گواهی دیجیتال (Certificate) و کلید خصوصی (Private Key) معتبر که از طریق کارپوشه‌ی مودیان دریافت کرده‌اید.
شناسه یکتای حافظه مالیاتی (clientId / memoryId، ۶ کاراکتری).

📦 نصب

با Composer

composer require masooumi/php-modyan-client

نام پکیج را پیش از انتشار روی Packagist، در composer.json مطابق نام‌کاربری/ریپازیتوری خودتان در گیت‌هاب اصلاح کنید.

بدون Composer

کافی‌ست فایل src/ModyanClient.php را در پروژه‌ی خود کپی و require کنید:

require_once 'path/to/ModyanClient.php';

🚀 شروع سریع

require_once 'src/ModyanClient.php';

$client = new ModyanClient(
    'AXXXXX',                              // شناسه یکتای حافظه مالیاتی
    file_get_contents('private.pem'),      // کلید خصوصی
    file_get_contents('certificate.pem'),  // گواهی دیجیتال
    1                                      // 1 = sandbox, 0 = production
);

$items = [[
    'sstid' => '1101101001001',
    'sstt'  => 'خدمات مشاوره فنی',
    'am'    => 1,
    'mu'    => '1701',
    'fee'   => 1000000,
    'vra'   => 10,
]];

$invoiceData = $client->buildInvoiceData(
    'AXXXXX',        // memoryId
    1,               // شماره سریال داخلی صورتحساب (خودتان مدیریت می‌کنید)
    '11111111111',   // شناسه اقتصادی فروشنده (tins)
    '2222222222',    // شناسه خریدار (bid)
    $items
);

$result = $client->sendInvoice($invoiceData);

if ($result['success']) {
    echo "ارسال موفق. taxId: {$result['taxId']} | uid: {$result['uid']}";
} else {
    print_r($result['error']);
}

مثال کامل‌تر (شامل استعلام وضعیت و ابطال) در examples/basic-usage.php موجود است.

📖 مرجع متدهای اصلی

متد	توضیح
`buildInvoiceData(...)`	ساخت آرایه‌ی کامل صورتحساب (header + body) از روی داده‌های خام، شامل محاسبه‌ی خودکار مالیات و taxId
`sendInvoice($invoiceData)`	اعتبارسنجی محلی، امضا، رمزنگاری و ارسال صورتحساب به سامانه
`sendCorrectiveInvoice($refTaxId, $data)`	ارسال صورتحساب اصلاحی با ارجاع به صورتحساب قبلی
`sendCancellationInvoice($sellerTin, $refTaxId, $serial)`	ابطال یک صورتحساب صادرشده
`sendReturnInvoice($refTaxId, $data)`	ثبت برگشت از فروش
`sendBatchInvoices($invoicesArray)`	ارسال گروهی تا ۱۰۰۰ صورتحساب در یک درخواست
`inquiryByUid($uid)`	استعلام نتیجه‌ی پردازش با شناسه‌ی پیگیری (`uid`)
`inquiryInvoiceStatus($taxId)`	استعلام وضعیت نهایی صورتحساب با شماره مالیاتی
`pollInvoiceProcessing($uid, ...)`	صبر خودکار و استعلام مکرر تا رسیدن به نتیجه نهایی
`registerPayment(...)`	ثبت اطلاعیه‌ی پرداخت روی یک صورتحساب
`validateInvoice($invoiceData)`	اعتبارسنجی محلی صورتحساب (بدون تماس شبکه‌ای)
`generateTaxId($memoryId, $serial, $dateTime)`	تولید شماره منحصربه‌فرد مالیاتی ۲۲ رقمی طبق سند رسمی

پارامترهای دقیق هر متد (و ثابت‌های inty، inp، ins، tob، setm، pmt و ...) در بالای فایل src/ModyanClient.php مستند شده‌اند.

🧩 ساختار شماره منحصربه‌فرد مالیاتی (taxId)

طبق سند رسمی RC_DCPS.SN_V1.3 سازمان امور مالیاتی، این شماره‌ی ۲۲ کاراکتری از ۴ بخش تشکیل شده:

[شناسه حافظه: 6 کاراکتر][تاریخ Hex: 5 رقم][سریال Hex: 10 رقم][رقم کنترلی: 1 رقم]

رقم کنترلی با الگوریتم Verhoeff و بر پایه‌ی ترکیب کد UTF-8 حروف شناسه‌ی حافظه + مقدار دهدهی پَدشده تاریخ (۶ رقم) و سریال (۱۲ رقم) محاسبه می‌شود. جزئیات کامل در بخش «تاریخچه‌ی نسخه‌ها» زیر.

🐞 مدیریت خطا

پاسخ اکثر متدها شامل کلید success (بولین) و در صورت خطا، error (شامل code، message، description) است. کلاس شامل جدول کامل کدهای خطای رایج سامانه مودیان (ModyanClient::ERROR_CODES) و رمزگشای کدهای هفت‌رقمی خطا (decodeSevenDigitError) است که فیلد مربوطه، نوع اعتبارسنجی (وجودی/ساختاری/قاعده‌ای/تطبیقی/...) و شدت (خطا/هشدار) را مشخص می‌کند.

📝 تاریخچه‌ی نسخه‌ها

نگاه کنید به CHANGELOG.md.

🤝 مشارکت

Issue و Pull Request خوش‌آمد است. لطفاً پیش از تغییرات بزرگ، ابتدا یک Issue باز کنید تا درباره‌ی رویکرد هماهنگ شویم.

📄 مجوز

این پروژه تحت مجوز MIT منتشر شده است.

سلب مسئولیت

این نرم‌افزار «همان‌طور که هست» ارائه می‌شود و هیچ ضمانتی (صریح یا ضمنی) درباره‌ی تطابق کامل و همیشگی آن با آخرین تغییرات سامانه مودیان وجود ندارد. همواره پیش از استفاده در محیط عملیاتی، با مستندات رسمی و جدیدترین نسخه‌ی آن در tp.tax.gov.ir مطابقت را بررسی کنید.

masooumi / php-modyan-client

Package info

Security

Statistics