یکپارچه‌سازی سامانه مودیان با ASP.NET چیست و چرا اهمیت دارد؟

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

اما سوال اصلی اینجاست: چطور می‌توان نرم‌افزار حسابداری یا فروش موجود را که با ASP.NET توسعه یافته، به سامانه مودیان وصل کرد؟ پاسخ این سوال را در این مقاله به‌صورت کامل، گام‌به‌گام و با کد نمونه آماده کرده‌ایم.

معماری کلی سامانه مودیان و نحوه ارتباط با API

پیش از اینکه وارد کدنویسی شویم، باید معماری سامانه مودیان را درک کنیم. سازمان امور مالیاتی یک API مبتنی بر REST طراحی کرده که با استانداردهای بین‌المللی همخوانی دارد. ارتباط با این API به سه مرحله اصلی تقسیم می‌شود:

• احراز هویت (Authentication): دریافت توکن دسترسی با استفاده از امضای دیجیتال
• ساخت و امضای صورتحساب: تهیه پکت داده‌ای مطابق استاندارد JSON و امضای آن
• ارسال و پیگیری: ارسال صورتحساب و دریافت uid برای پیگیری وضعیت

نکته مهم: تمام ارتباطات با سامانه مودیان باید رمزگذاری‌شده (HTTPS) باشند و داده‌ها با کلید خصوصی شما امضا شوند. بنابراین مدیریت صحیح کلیدهای رمزنگاری یکی از حساس‌ترین بخش‌های این پروژه است.

پیش‌نیازهای فنی برای شروع

قبل از نوشتن اولین خط کد، مطمئن شوید موارد زیر را در اختیار دارید:

• شناسه یکتای مالیاتی (UID): که از سازمان امور مالیاتی دریافت می‌کنید
• کلید خصوصی (Private Key): فایل PFX یا PEM مربوط به گواهی دیجیتال شما
• .NET 6 یا بالاتر: برای استفاده از قابلیت‌های مدرن HttpClient و JSON
• پکیج‌های NuGet مورد نیاز: شامل BouncyCastle، Jose-jwt و Newtonsoft.Json
• محیط تست (Sandbox): آدرس sandbox.tax.gov.ir برای آزمایش قبل از محیط واقعی

گام اول: راه‌اندازی پروژه ASP.NET و نصب وابستگی‌ها

یک پروژه ASP.NET Core Web API جدید بسازید و پکیج‌های ضروری را نصب کنید. در Package Manager Console دستورات زیر را اجرا کنید:

Install-Package Portable.BouncyCastle

Install-Package jose-jwt

Install-Package Newtonsoft.Json

Install-Package System.Security.Cryptography.X509Certificates

این پکیج‌ها برای رمزنگاری، امضای دیجیتال، تولید JWT و کار با JSON ضروری هستند.

گام دوم: پیاده‌سازی سرویس احراز هویت

برای ارتباط با سامانه مودیان، ابتدا باید یک توکن دسترسی (Access Token) دریافت کنید. این توکن از طریق درخواست POST به endpoint احراز هویت و با ارائه امضای دیجیتال صادر می‌شود.

یک کلاس سرویس به نام MoadianAuthService بسازید:

public class MoadianAuthService

{

private readonly HttpClient _httpClient;

private readonly IConfiguration _config;

private string _cachedToken;

private DateTime _tokenExpiry;

public MoadianAuthService(HttpClient httpClient, IConfiguration config)

{

_httpClient = httpClient;

_config = config;

}

public async Task GetAccessTokenAsync()

{

if (!string.IsNullOrEmpty(_cachedToken)

&& DateTime.UtcNow < _tokenExpiry)

return _cachedToken;

var privateKey = LoadPrivateKey(_config[“Moadian:PrivateKeyPath”]);

var uid = _config[“Moadian:UID”];

// ساخت payload برای JWT

var payload = new Dictionary

{

{ “uid”, uid },

{ “iat”, DateTimeOffset.UtcNow.ToUnixTimeSeconds() },

{ “exp”, DateTimeOffset.UtcNow.AddMinutes(30).ToUnixTimeSeconds() }

};

var token = JWT.Encode(payload, privateKey, JwsAlgorithm.RS256);

var requestBody = new { token = token };

var response = await _httpClient.PostAsJsonAsync(

“https://tp.tax.gov.ir/req/api/self-tsp/token”, requestBody);

var result = await response.Content.ReadFromJsonAsync();

_cachedToken = result.Token;

_tokenExpiry = DateTime.UtcNow.AddMinutes(25);

return _cachedToken;

}

private RSA LoadPrivateKey(string keyPath)

{

var pem = File.ReadAllText(keyPath);

var rsa = RSA.Create();

rsa.ImportFromPem(pem);

return rsa;

}

}

گام سوم: ساخت مدل صورتحساب الکترونیکی

سامانه مودیان دو نوع صورتحساب پشتیبانی می‌کند: نوع اول (فروش به اشخاص حقوقی) و نوع دوم (فروش به اشخاص حقیقی). ساختار JSON هر دو مشابه است. مدل اصلی را به این شکل تعریف کنید:

public class InvoiceHeader

{

[JsonProperty(“taxid”)]

public string TaxId { get; set; } // شناسه یکتای مالیاتی

[JsonProperty(“indatim”)]

public long InDateTime { get; set; } // تاریخ و ساعت صورتحساب (Unix timestamp)

[JsonProperty(“indati2m”)]

public long InDateTime2 { get; set; }

[JsonProperty(“inno”)]

public string InvoiceNumber { get; set; } // شماره صورتحساب

[JsonProperty(“irtaxid”)]

public string SellerTaxId { get; set; } // شناسه مالیاتی فروشنده

[JsonProperty(“inp”)]

public int InvoicePattern { get; set; } // الگوی صورتحساب (1 یا 2)

[JsonProperty(“ins”)]

public int InvoiceSubject { get; set; } // موضوع صورتحساب

}

public class InvoiceBody

{

[JsonProperty(“sstid”)]

public string GoodServiceId { get; set; } // شناسه کالا/خدمت

[JsonProperty(“sstt”)]

public string GoodServiceName { get; set; }

[JsonProperty(“am”)]

public decimal Amount { get; set; } // مقدار

[JsonProperty(“mu”)]

public int Unit { get; set; } // واحد

[JsonProperty(“fee”)]

public long UnitPrice { get; set; } // مبلغ واحد (ریال)

[JsonProperty(“tsstam”)]

public long TotalAmount { get; set; } // جمع مبلغ کالا

}

گام چهارم: رمزگذاری و ارسال صورتحساب

مهم‌ترین بخش پیاده‌سازی، رمزگذاری محتوای صورتحساب است. سامانه مودیان از رمزگذاری ترکیبی استفاده می‌کند: ابتدا داده‌ها با AES رمز می‌شوند، سپس کلید AES با RSA عمومی سامانه رمزگذاری می‌شود.

public class MoadianInvoiceService

{

private readonly HttpClient _httpClient;

private readonly MoadianAuthService _authService;

public async Task SendInvoiceAsync(Invoice invoice)

{

var token = await _authService.GetAccessTokenAsync();

// سریال‌سازی صورتحساب

var invoiceJson = JsonConvert.SerializeObject(invoice);

var invoiceBytes = Encoding.UTF8.GetBytes(invoiceJson);

// تولید کلید AES تصادفی

using var aes = Aes.Create();

aes.KeySize = 256;

aes.GenerateKey();

aes.GenerateIV();

// رمزگذاری با AES

var encryptedData = EncryptWithAes(invoiceBytes, aes.Key, aes.IV);

// رمزگذاری کلید AES با RSA عمومی سامانه

var encryptedKey = EncryptKeyWithRsa(aes.Key, GetServerPublicKey());

// امضای صورتحساب با کلید خصوصی

var signature = SignData(invoiceBytes, LoadPrivateKey());

var packet = new

{

header = new { },

body = new

{

encryptedInvoice = Convert.ToBase64String(encryptedData),

symmetricKey = Convert.ToBase64String(encryptedKey),

iv = Convert.ToBase64String(aes.IV),

fiscalId = invoice.Header.TaxId,

dataSignature = Convert.ToBase64String(signature)

}

};

_httpClient.DefaultRequestHeaders.Authorization =

new AuthenticationHeaderValue(“Bearer”, token);

var response = await _httpClient.PostAsJsonAsync(

“https://tp.tax.gov.ir/req/api/self-tsp/async/normal-enqueue”,

new { packets = new[] { packet } });

return await response.Content.ReadFromJsonAsync();

}

}

گام پنجم: پیگیری وضعیت صورتحساب‌های ارسال‌شده

ارسال صورتحساب به سامانه مودیان آسنکرون (Asynchronous) است. یعنی پس از ارسال، یک uid دریافت می‌کنید و باید بعداً وضعیت آن را پیگیری کنید. برای این کار از endpoint زیر استفاده می‌شود:

public async Task CheckInvoiceStatusAsync(string referenceId)

{

var token = await _authService.GetAccessTokenAsync();

_httpClient.DefaultRequestHeaders.Authorization =

new AuthenticationHeaderValue(“Bearer”, token);

var response = await _httpClient.GetAsync(

$“https://tp.tax.gov.ir/req/api/self-tsp/inquiry/invoice-status” +

$“?referenceNumber={referenceId}”);

var statusResult = await response.Content

.ReadFromJsonAsync();

return statusResult?.Data?.Status switch

{

“SUCCESS” => InvoiceStatus.Confirmed,

“FAILED” => InvoiceStatus.Rejected,

“PENDING” => InvoiceStatus.Processing,

_ => InvoiceStatus.Unknown

};

}

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

در پروژه‌های واقعی، مدیریت خطا اهمیت حیاتی دارد. سامانه مودیان کدهای خطای استانداردی دارد که باید آن‌ها را به درستی handle کنید:

• خطای 401: توکن منقضی شده؛ باید توکن تجدید شود
• خطای 429: rate limit؛ با Polly برای retry سیاست تعریف کنید
• خطای 400: داده‌های نامعتبر؛ پیام خطا را parse کنید تا فیلد مشکل‌دار را بیابید
• timeout: حتماً CancellationToken و timeout مناسب تنظیم کنید

توصیه می‌شود از پکیج Polly برای پیاده‌سازی الگوی Retry با exponential backoff استفاده کنید:

// در Program.cs

builder.Services.AddHttpClient()

.AddPolicyHandler(GetRetryPolicy());

static IAsyncPolicy GetRetryPolicy()

{

return HttpPolicyExtensions

.HandleTransientHttpError()

.OrResult(msg => msg.StatusCode == HttpStatusCode.TooManyRequests)

.WaitAndRetryAsync(3, retryAttempt =>

TimeSpan.FromSeconds(Math.Pow(2, retryAttempt)));

}

ثبت و ذخیره‌سازی صورتحساب‌ها در دیتابیس

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

• شناسه داخلی صورتحساب
• taxId (شناسه مالیاتی یکتا)
• referenceId (uid دریافت‌شده از سامانه)
• وضعیت: Pending / Sent / Confirmed / Rejected
• تاریخ ارسال و تاریخ تأیید
• متن خطا در صورت رد شدن

پیاده‌سازی Background Service برای پردازش صف ارسال

در سیستم‌های با بار بالا، بهتر است ارسال صورتحساب را به یک Background Service یا Queue Worker واگذار کنید. این کار از timeout شدن request کاربر جلوگیری می‌کند و قابلیت retry اتوماتیک را فراهم می‌آورد:

public class MoadianWorkerService : BackgroundService

{

private readonly IServiceProvider _serviceProvider;

private readonly ILogger _logger;

protected override async Task ExecuteAsync(CancellationToken stoppingToken)

{

while (!stoppingToken.IsCancellationRequested)

{

using var scope = _serviceProvider.CreateScope();

var invoiceRepo = scope.ServiceProvider

.GetRequiredService();

var moadianService = scope.ServiceProvider

.GetRequiredService();

// دریافت صورتحساب‌های pending

var pendingInvoices = await invoiceRepo

.GetPendingInvoicesAsync(batchSize: 50);

foreach (var invoice in pendingInvoices)

{

try

{

var result = await moadianService

.SendInvoiceAsync(invoice);

await invoiceRepo.UpdateStatusAsync(

invoice.Id, InvoiceStatus.Sent, result.ReferenceId);

}

catch (Exception ex)

{

_logger.LogError(ex,

“Error sending invoice {InvoiceId}”, invoice.Id);

await invoiceRepo.IncrementRetryCountAsync(invoice.Id);

}

}

await Task.Delay(TimeSpan.FromSeconds(30), stoppingToken);

}

}

}

تست در محیط Sandbox قبل از Production

هیچ‌وقت مستقیم روی سامانه اصلی (production) تست نکنید! سازمان امور مالیاتی یک محیط sandbox در آدرس sandbox.tax.gov.ir فراهم کرده است. برای مدیریت راحت‌تر محیط‌ها، از appsettings.json استفاده کنید:

// appsettings.Development.json

{

“Moadian”: {

“BaseUrl”: “https://sandbox.tax.gov.ir”,

“UID”: “your-test-uid”,

“PrivateKeyPath”: “keys/test-private.pem”,

“ServerPublicKeyPath”: “keys/sandbox-server-public.pem”

}

}

// appsettings.Production.json

{

“Moadian”: {

“BaseUrl”: “https://tp.tax.gov.ir”,

“UID”: “your-production-uid”,

“PrivateKeyPath”: “/secure/path/private.pem”,

“ServerPublicKeyPath”: “/secure/path/server-public.pem”

}

}

نکات امنیتی حیاتی که نباید فراموش کنید

امنیت در یکپارچه‌سازی با سامانه مودیان یک الزام قانونی و فنی است. رعایت موارد زیر ضروری است:

• کلید خصوصی را هرگز در سورس کد commit نکنید؛ از Azure Key Vault، HashiCorp Vault یا Environment Variables استفاده کنید
• TaxId هر صورتحساب باید یکتا و یکبار مصرف باشد؛ از GUID با فرمت مشخص استفاده کنید
• IP سرور خود را در سامانه ثبت کنید؛ سامانه مودیان whitelist IP دارد
• گواهی دیجیتال را به‌موقع تمدید کنید؛ انقضای گواهی برابر است با توقف کامل سیستم
• تمام درخواست‌ها و پاسخ‌ها را log کنید اما اطلاعات حساس مثل کلیدها را mask کنید

بهینه‌سازی Performance در پروژه‌های بزرگ

اگر روزانه هزاران صورتحساب دارید، این نکات performance را جدی بگیرید:

• از IHttpClientFactory استفاده کنید و HttpClient را singleton نگه ندارید
• توکن را cache کنید و تا انقضا مجدداً request نزنید
• ارسال batch: سامانه مودیان ارسال دسته‌ای تا ۵۰ صورتحساب در یک request را پشتیبانی می‌کند
• از Semaphore برای کنترل همزمانی استفاده کنید تا rate limit سامانه نقض نشود
• عملیات رمزنگاری را async کنید تا thread pool block نشود

جمع‌بندی: یکپارچه‌سازی موفق با سامانه مودیان

در این مقاله مسیر کامل یکپارچه‌سازی سامانه مودیان با ASP.NET را پیمودیم. از راه‌اندازی پروژه گرفته تا احراز هویت، ساخت مدل صورتحساب، رمزگذاری، ارسال، پیگیری وضعیت و بهینه‌سازی Performance.

اگر همین الان روی یک پروژه مشابه کار می‌کنید، پیشنهاد می‌کنیم:

• ابتدا در sandbox کامل تست کنید
• مدیریت خطا و retry را جدی بگیرید
• سیستم monitoring مناسبی داشته باشید
• مستندات سازمان امور مالیاتی را مرتب چک کنید چون API در حال تکامل است

سوالات متداول (FAQ)