اتصال به سامانه مودیان و ارسال صورتحساب الکترونیکی با سی شارپ

اتصال به سامانه مودیان و ارسال صورتحساب الکترونیکی با سی شارپ 

با گسترش الزامات مربوط به صورتحساب‌های الکترونیکی، اتصال نرم‌افزارهای حسابداری و مالی به سامانه مودیان به یکی از نیازهای مهم کسب‌وکارها و شرکت‌های نرم‌افزاری تبدیل شده است.
برای توسعه چنین سیستمی با زبان #C باید علاوه بر برنامه‌نویسی، ساختار صورتحساب، اطلاعات مالیاتی، احراز هویت و نحوه ارتباط با سرویس‌های سامانه مودیان را نیز به‌درستی شناخت.
سامانه مودیان بستری است که اطلاعات مربوط به صورتحساب‌های الکترونیکی در آن ثبت و مدیریت می‌شود برای کسب‌وکارهایی که از نرم‌افزار حسابداری، فروش یا مالی استفاده می‌کنند، اتصال نرم‌افزار به سامانه مودیان اهمیت زیادی دارد؛ زیرا در این حالت اطلاعات صورتحساب می‌تواند از داخل نرم‌افزار تولید شده و برای ارسال و پیگیری در اختیار سرویس‌های مربوط به سامانه قرار گیرد.
یکی از راه‌های پیاده‌سازی این قابلیت، استفاده از زبان برنامه‌نویسی #C است.
برنامه‌نویس می‌تواند در یک نرم‌افزار حسابداری مبتنی بر NET. ، مدل صورتحساب را ایجاد کند، اطلاعات مالیاتی را آماده کند، داده‌ها را به JSON تبدیل کند و از طریق ارتباط HTTP با سرویس‌های مربوط به سامانه ارتباط برقرار کند.

نکات مهم در طراحی نرم‌افزار

در پروژه‌های واقعی، اطلاعات حساس مانند کلید خصوصی نباید به شکل ساده داخل سورس کد قرار بگیرد.
همچنین بهتر است اطلاعات درخواست‌ها، پاسخ‌ها و سوابق ارسال در دیتابیس ذخیره شوند تا امکان پیگیری و عیب‌یابی وجود داشته باشد.
از طرف دیگر، ساختار صورتحساب و الزامات فنی ممکن است بر اساس دستورالعمل‌ها و نسخه‌های جدید تغییر کند؛ بنابراین طراحی نرم‌افزار باید به‌گونه‌ای باشد که تغییرات API و ساختار صورتحساب به‌سادگی قابل اعمال باشند.
سازمان امور مالیاتی اسناد مختلفی از جمله دستورالعمل صدور صورتحساب الکترونیکی و دستورالعمل فنی نحوه اتصال را منتشر کرده است.

آموزش اتصال به سامانه مودیان و ارسال صورتحساب الکترونیکی با #C

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

آشنایی با مفاهیم پایه مالیاتی

در این بخش ابتدا مفاهیم موردنیاز سامانه مودیان را یاد می‌گیریم، مثل:

• مودی مالیاتی و شناسه ملی/کد اقتصادی

• پرونده مالیاتی

• کارپوشه

• صورتحساب الکترونیکی

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

• الگوهای صورتحساب

• شناسه کالا/خدمت

• شناسه یکتای حافظه مالیاتی

• شماره مالیاتی صورتحساب

• مالیات بر ارزش افزوده

• وضعیت صورتحساب: ارسال‌شده، تأییدشده، ردشده و...

هدف این بخش این است که قبل از نوشتن کد، ساختار و اصطلاحات سامانه را کاملاً بشناسیم.

🚀 اتصال نرم‌افزار حسابداری به سامانه مودیان

فاکتورهای خود را سریع و مطمئن به سامانه مودیان ارسال کنید!
با راهکار تخصصی نرم‌افزار زهیر، نرم افزار تحت ویندوز سی شارپ و نرم افزار حسابداری را به سامانه مودیان متصل کنید.

🔗 [آموزش اتصال نرم‌افزار حسابداری به سامانه مودیان]

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

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

چرا باید نرم افزار را به سامانه مودیان متصل کنیم؟

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

فرآیند کلی ارسال صورتحساب به سامانه مودیان

فرآیند کلی را می‌توان به شکل زیر در نظر گرفت:

نرم افزار حسابداری
        ↓
ایجاد صورتحساب
        ↓
تولید اطلاعات مالیاتی
        ↓
آماده‌سازی و امضای اطلاعات
        ↓
ارسال به API
        ↓
دریافت پاسخ
        ↓
ثبت شماره پیگیری
        ↓
استعلام وضعیت
        ↓
ذخیره نتیجه در SQL Server

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

پیش نیازهای اتصال نرم افزار به سامانه مودیان

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

شناسه یکتا حافظه مالیاتی چیست؟

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

دریافت شناسه یکتا حافظه مالیاتی

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

کلید خصوصی چیست؟

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

در محیط واقعی باید از روش‌های امن مدیریت Secret استفاده شود.

کلید عمومی چیست؟

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

گواهی امضای دیجیتال چیست؟

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

CSR چیست؟

CSR مخفف Certificate Signing Request است و به درخواستی گفته می‌شود که برای دریافت گواهی دیجیتال ایجاد می‌شود.
CSR معمولاً شامل اطلاعات شناسایی و کلید عمومی است. نکته مهم این است که کلید خصوصی مرتبط نباید همراه CSR یا برای صدور گواهی در اختیار دیگران قرار گیرد.

شماره اقتصادی چیست؟

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

شناسه ملی و کد ملی در سامانه مودیان

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

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

اطلاعات مورد نیاز برای اتصال به API سامانه مودیان

بسته به روش و نسخه سرویس مورد استفاده، اطلاعات مورد نیاز می‌تواند شامل موارد زیر باشد:

• اطلاعات مودی

• شناسه یکتا حافظه مالیاتی

• اطلاعات مربوط به کلید عمومی

• کلید خصوصی

• گواهی دیجیتال

• اطلاعات احراز هویت

• اطلاعات فروشنده

•  اطلاعات خریدار

• اطلاعات کالا و خدمات

• اطلاعات پرداخت

• تنظیمات محیط ارتباطی

این اطلاعات باید از منابع رسمی و تنظیمات مربوط به مودی تهیه شوند و نباید مقادیر نمونه موجود در اینترنت بدون بررسی در نرم‌افزار عملیاتی استفاده شوند. 

پیاده سازی احراز هویت سامانه مودیان در #C

دریافت Token از سامانه مودیان

در سرویس‌هایی که احراز هویت مبتنی بر Token دارند، ابتدا باید درخواست احراز هویت ارسال شود و Token دریافتی برای درخواست‌های بعدی استفاده شود.
ساختار دقیق Endpoint و پارامترهای احراز هویت باید بر اساس نسخه فعلی API انتخاب شود.

 ارسال اطلاعات احراز هویت

اطلاعات احراز هویت باید دقیقاً مطابق قرارداد API ارسال شوند. کوچک‌ترین تفاوت در نام فیلد، نوع داده یا ساختار درخواست می‌تواند باعث رد شدن درخواست شود.

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

مدیریت Token

پس از دریافت Token بهتر است آن را همراه با زمان دریافت و زمان انقضا نگهداری کنید.
قبل از ارسال درخواست جدید، نرم‌افزار می‌تواند بررسی کند که Token معتبر است یا باید دوباره دریافت شود.

 اعتبارسنجی اطلاعات اتصال

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

ذخیره امن کلید خصوصی و اطلاعات حساس

اطلاعاتی مانند کلید خصوصی، رمز عبور گواهی و Token نباید داخل Git، سورس کد یا فایل‌های عمومی قرار بگیرند.
در محیط‌های واقعی می‌توان از Secret Store، متغیرهای محیطی، Windows Certificate Store یا راهکارهای مدیریت امن Secret استفاده کرد.

ساخت صورتحساب الکترونیکی در #C

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

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

اطلاعات فروشنده

اطلاعات فروشنده باید از پرونده مودی یا تنظیمات شرکت دریافت شود.

این اطلاعات نباید برای هر فاکتور به‌صورت دستی توسط کاربر وارد شوند.

اطلاعات خریدار

اطلاعات خریدار نیز باید از پرونده مشتری خوانده شود.

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

اطلاعات کالا و خدمات

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

مبلغ، تخفیف و مالیات

محاسبات مالی باید قبل از ساخت JSON انجام شوند. 

اطلاعات پرداخت

اطلاعات پرداخت باید متناسب با روش پرداخت ثبت‌شده در فاکتور ایجاد شود.

بنابراین ساختار پرداخت بهتر است مستقل از اطلاعات کالا باشد.

تولید شماره منحصر به فرد صورتحساب

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

برای این منظور می‌توان از شماره سریال، شماره سند یا یک شناسه داخلی استفاده کرد.
نکته مهم این است که شماره داخلی نرم‌افزار را نباید بدون بررسی با شناسه‌های مالیاتی مورد نیاز API یکسان فرض کرد. 

ارسال صورتحساب الکترونیکی به سامانه مودیان با #C

آدرس API سامانه مودیان

 ارسال صورتحساب

دریافت پاسخ سامانه مودیان

دریافت شماره پیگیری صورتحساب

ذخیره نتیجه ارسال در دیتابیس

استعلام وضعیت صورتحساب از سامانه مودیان

چرا باید وضعیت صورتحساب را استعلام کنیم؟

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

 ارسال درخواست استعلام با #C

 بررسی شماره پیگیری

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

ذخیره وضعیت در دیتابیس

بهتر است هر تغییر وضعیت ثبت شود تا تاریخچه قابل بررسی باشد. 

مدیریت خطاهای سامانه مودیان در #C

مدیریت خطا یکی از مهم‌ترین قسمت‌های یکپارچه‌سازی است.
نرم‌افزار نباید صرفاً در صورت موفقیت API کار کند؛ بلکه باید Timeout، پاسخ نامعتبر، خطای داده و خطاهای اعتبارسنجی را نیز مدیریت کند.

خطای عدم پاسخگویی سامانه مودیان

در صورت عدم پاسخگویی سرویس، نباید صورتحساب را بلافاصله به‌عنوان «رد شده» ثبت کرد.
ابتدا باید مشخص شود مشکل از Timeout، شبکه یا خود سرویس بوده است.
استفاده از CancellationToken و Timeout مناسب در HttpClient می‌تواند از معطل ماندن طولانی برنامه جلوگیری کند.

خطای اطلاعات صورتحساب

اگر یکی از فیلدهای صورتحساب نادرست باشد، نرم‌افزار باید پیام خطای سرویس را ذخیره کند و آن را به کاربر نمایش دهد.
بهتر است پیام خام API نیز در دیتابیس نگهداری شود تا بررسی خطا امکان‌پذیر باشد.

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

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

خطای شناسه ملی یا کد ملی

در صورت اشتباه بودن اطلاعات خریدار، ابتدا باید پرونده مشتری اصلاح شود.
سپس صورتحساب مطابق وضعیت آن و قوانین مربوطه مدیریت شود.

خطای شناسه یکتا حافظه مالیاتی

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

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

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

ارسال اطلاعات پرداخت صورتحساب به سامانه مودیان

اطلاعات پرداخت چیست؟

اطلاعات پرداخت مشخص می‌کند مبلغ صورتحساب چگونه تسویه شده یا قرار است تسویه شود.
این اطلاعات باید در ساختار مربوط به صورتحساب قرار گیرد.

روش‌های پرداخت

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

پرداخت نقدی

در پرداخت نقدی، نرم‌افزار باید مبلغ پرداخت‌شده را مطابق ساختار مورد نیاز ثبت کند.

 پرداخت چکی

در پرداخت چکی علاوه بر مبلغ، ممکن است اطلاعات مرتبط با چک نیز در سیستم حسابداری نگهداری شود.
این اطلاعات باید طبق فیلدهای مورد نیاز صورتحساب مدیریت شوند.

 کارتخوان و درگاه اینترنتی

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

 انتقال وجه

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

 جمع‌بندی

اتصال یک نرم‌افزار حسابداری به سامانه مودیان فقط به نوشتن یک درخواست HTTP محدود نمی‌شود.
برای پیاده‌سازی صحیح باید از مرحله آماده‌سازی اطلاعات مودی و شناسه یکتا شروع کرد، مدل صورتحساب را در #C ساخت، اطلاعات فروشنده، خریدار، کالا، مبلغ، مالیات و پرداخت را تکمیل کرد و سپس داده‌ها را طبق Schema مورد نیاز به JSON تبدیل کرد.

در مرحله بعد، نرم‌افزار باید فرآیند احراز هویت و ارتباط با  API سامانه مودیان  را مدیریت کند.
پس از ارسال نیز دریافت پاسخ، نگهداری Tax ID، شماره پیگیری، وضعیت صورتحساب و پیام‌های خطا اهمیت زیادی دارد.
ذخیره این اطلاعات در SQL Server باعث می‌شود نرم‌افزار بتواند سوابق ارسال را مدیریت کرده و صورتحساب‌های ناموفق را دوباره پردازش کند.

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