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

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

۱– مقدمه

در این سند نحوه اتصال به سامانه مودیان، دریافت اطلاعات مورد نیاز جهت پیکربندی پایانه فروشگاهی-حافظه مالیاتی، ارسال اطلاعات صورتحساب الکترونیکی و استعلام وضعیت صورتحساب های ارسالی شرح داده شده است. برای ارسال اطلاعات صورتحساب الکترونیکی از مکانیزم غیر همگام و برای دریافت و استعلام اطلاعات از مکانیزم همگام استفاده شده است. برای هر کدام از این مکانیزم ها ، API مستقلی در نظر گرفته شده است. برای مکانیزم غیرهمگام از صف استفاده می شود.

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

۲– هدف

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

۳– دامنه کاربرد

ذینفعان این سند شامل:

• اشخاص مشمول (مودیان).
• شرکت های معتمد ارائه کننده خدمات مالیاتی نوع اول

۴– تعاریف

• شناسه یکتای حافظه مالیاتی: شناسه ای است یکتا دارای مقداری ثابت و منحصر به فرد که به هر حافظه مالیاتی در سطح کشور اختصاص داده می شود، این شناسه از مولفه های تشکیل دهنده شماره منحصر به فرد مالیاتی می باشد که پس از درخواست مودی در کارپوشه تولید و در اختیار وی قرار خواهد گرفت.
•  شماره منحصر به فرد مالیاتی: شماره ای است یکتا در سامانه مودیان که به ازای هر صورتحساب تولید شده و به صورت منحصر به فرد به آن صورتحساب تخصیص داده می شود. این شماره دارای بخش های اطلاعاتی خاص بوده که جزئیات آن در سند «قالب شناسه یکتای حافظه مالیاتی و شماره منحصر به فرد مالیاتی» ذکر شده است.
• صورتحساب الکترونیکی: صورتحسابی است دارای شماره منحصر به فرد مالیاتی که اطلاعات مندرج در آن، در حافظه مالیاتی فروشنده ذخیره می شود .

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

• حافظه مالیاتی: نوعی حافظه الکترونیکی است که برای ثبت و نگهداری اطلاعات مندرج در صورتحساب های الکترونیکی و انتقال آن به سامانه مودیان مورد استفاده قرار می گیرد .حافظه مالیاتی می تواند به شکل سخت افزاری یا نرم افزاری باشد. حافظه مالیاتی، توسط مودی برای ثبت صورتحساب الکترونیکی مورد استفاده قرار می گیرد. هر حافظه مالیاتی باید دارای شماره شناسه یکتا باشد. شناسه یکتای حافظه مالیاتی توسط سازمان اختصاص داده می شود.
•  پایانه فروشگاهی:  رایانه، دستگاه کارتخوان بانکی، درگاه پرداخت الکترونیکی یا هر وسیله دیگری که امکان اتصال به شبکه های الکترونیکی پرداخت رسمی کشور و سامانه مودیان را داشته و از قابلیت صدور صورتحساب الکترونیکی برخوردار باشد(بند ب ماده ۱ قانون).
•  شرکت های معتمد ارائه کننده خدمات مالیاتی: اشخاص حقوقی دارای پروانه هستند که حسب ضوابط و دستورالعمل های ابلاغی سازمان، نسبت به ارائه مشاوره و آموزش های لازم به مودیان، نصب و پشتیبانی تجهیزات مورد نیاز برای ارائه خدمات مالیاتی از قبیل خدمات مربوط به صدور صورتحساب و سایر امور غیرحاکمیتی با سازمان همکاری می کند(بند چ ماده ۱).
• زیرسامانه جمع آوری و پردازش اطلاعات صورتحساب: زیرسامانه ای است که داده های ارسالی از پایانه های فروشگاهی-حافظه مالیاتی یا شرکت های معتمد ارائه کننده خدمات مالیاتی نوع اول را از طریق واسطه ای نرم افزاری دریافت می کند.
• حد مجاز فروش: جمع صورتحساب های الکترونیکی صادره توسط هر مودی در هر دوره مالیاتی نمی تواند بیشتر از سه برابر فروش اظهار شده وی در دوره مشابه سال قبل، که مالیات آن به سازمان پرداخت شده یا ترتیب پرداخت آن داده شده است، باشد. جمع صورتحساب های الکترونیکی صادره شده در هر دوره مالیاتی برای واحدهای جدیدالتاسیس یا واحدهای فاقد سابقه مالیاتی نمی تواند بیش از سه برابر معافیت سالانه موضوع ماده(۱۰۱) قانون مالیات های مستقیم باشد(ماده ۶ قانون پایانه های فروشگاهی و سامانه مودیان).
• شناسه یکتای ارسال صورتحساب: شناسه ای یکتا که هنگام ارسال صورتحساب توسط ارسال کننده به صورتحساب جهت رهگیری آن اختصاص داده میشود. این شناسه با فرمت uuid به صورت رمز نشده ارسال می گردد.
• رسید یکتای دریافت صورتحساب: هنگام دریافت صورتحساب در زیرسامانه جمع آوری و پردازش اطلاعات، یک شناسه رسید یکتا با فرمت uuid به هر صورتحساب توسط این زیرسامانه اختصاص داده می شود.
• لیست صورتحساب ها: مجموعه ای از صورتحساب های صادر شده توسط پایانه فروشگاهی-حافظه مالیاتی که در قالب یک مجموعه به سامانه مودیان ارسال می شود.
• کلاینت: ارسال کننده درخواست به API زیرسامانه جمع آوری و پردازش اطلاعات که می تواند مودی یا شرکت معتمد ارائه کننده خدمات مالیاتی باشد.
• سرور: سرور سامانه مودیان
• زوج کلید عمومی و خصوصی : در این سند هرگاه برای انکارناپذیری از کلید عمومی یا خصوصی استفاده می شود منظور کلیدی است که توسط یک  مرکز میانی معتبر برای هر یک  از ذینفعان سامانه مودیان گواهی شده  باشد.
• مرکز میانی معتبر: هر مرکز میانی که از شورای سیاست گذاری گواهی الکترونیکی کشور مجوز گرفته باشد (موضوع ماده ۳۲ قانون تجارت الکترونیکی). لیست این مراکز از طریق سایت www.rca.gov.ir  بخش مراکز میانی ،قابل دسترسی است.

۵– پیکربندی پایانه فروشگاهی-حافظه مالیاتی

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

مودی جهت صدور و ارسال صورتحساب الکترونیکی نیاز به دریافت شناسه یکتا حافظه مالیاتی دارد .

بنابراین میبایست به بخش عضویت و ثبت نام کارپوشه خود مراجعه نموده و مراحل زیر را طی نماید:

1. به ازای هر شناسه یکتا حافظه مالیاتی، یکی از سه حالت ارسال اطلاعات صورتحساب را به شرح ذیل انتخاب کند:

• توسط خود مودی (به روش مستقیم)
• ارسال اطلاعات صورتحساب توسط شرکت معتمد ارائه کننده خدمات مالیاتی (به روش غیرمستقیم)
•  ارسال اطلاعات صورتحساب توسط شرکت معتمد ارائه کننده خدمات مالیاتی (به روش غیرمستقیم و با استفاده از زیرساخت های اختصاصی)

۲. کلید عمومی (RSA) دریافتی از مراکز میانی معتبر با طول کلید ۲۰۴۸ بیت را بارگذاری نماید.  

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

۳ .ارتباط شناسه یکتای حافظه مالیاتی درخواستی با کدپستی(های) محل فعالیت تعیین گردد.

۵-۲ پیکربندی و ثبت مشخصات

مودی برای راه اندازی پایانه فروشگاهی-حافظه مالیاتی خود باید از طریق فراخوانی متدهای “دریافت اطلاعات سرور”و “دریافت اطلاعات حافظه مالیاتی”، شماره اقتصادی، نام تجاری، ساعت و تاریخ، کلید عمومی سازمان و شناسه یکتای حافظه مالیاتی را از سرور دریافت کند . جزئیات اقلام اطلاعاتی لازم در جدول ۱۰ توضیح داده شده است.

۶ –امنیت اطلاعات

مکانیزم های امنیتی جهت ارسال صورتحساب مطابق با نمودار ارائه شده در شکل(۱) می باشند.

۶-۱ توکن

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

۶-۲ امضا

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

 ۶–۲–۱ نرمالسازی درخواست

برای یکسان کردن ساختار تمامی درخواست ها به API های زیرسامانه جمع آوری اطلاعات، برای تمامی بسته های ارسالی شامل همگام و غیرهمگام امضا بر روی درخواست صورت می پذیرد. برای امضا میبایست ابتدا  Header وBody درخواست ادغام و JSON واحد تولید گردد. ضروری است JSON تولید شده مطابق شکل(۲) به رشته تبدیل، سپس امضا و ارسال شود.

 

فرآیند تبدیل JSON به رشته، مطابق گام های جدول(۱)می باشد:

– شی به فرمت کلید-مقدار تبدیل شده به طوری که کلید، عمق جایگاه مقدار را مشخص می نماید.

– کلیدها بر اساس حروف الفبا مرتب شوند.

– سپس مقدارها به ترتیب با هم ادغام شوند:

• از کاراکتر # به عنوان جداکننده مقادیر(اقلام اطلاعاتی)استفاده شود.
• در صورتی که کاراکتر# در متن وجود داشته باشد، با ## مشخص می گردد.
• در صورتی که مقدار فیلدی در رشته، null یا “” باشد؛ با ### مشخص می گردد.

– در آخر آرایه ای از روی این رشته ایجاد می شود.

 

نکات:

•  در صورتی که داخل JSON آرایه وجود داشته باشد، ترتیب عناصر آرایه دستکاری نشده و با همان ترتیب در نظر گرفته می شود.
•  در صورتی که ریشه JSON آرایه باشد، داخل فیلد packets قرارگرفته و تبدیل به شی می شود.

روش پیاده سازی نرمالسازی JSON در پیوست های ۱-۱ و ۱-۲ ارائه شده است.

۶-۲-۲ فرآیند امضا صورتحساب

برای امضا صورتحساب باید اطلاعات JSON صورتحساب به روشی که برای نرمالسازی بیان شد نرمال شوند. به عنوان مثال اطلاعات JSON صورتحساب زیر را در نظر بگیرید:

◊ تمام اطلاعات پر شده در JSON غیرواقعی و تستی می باشد.

بعد از نرمال سازی JSON صورتحساب مورد نظر، رشته نرمال شده به صورت زیر بدست می آید:

۱۰۰۰۰۰۰#۱#########۹۰۰۰۰###۰###۱۰۰۰۰۰۰#۹۶#############۱۰۰۰۰۰۰###۲۱۵۳۲۶۵
پاستیل میوه ای #۹۸۹۶۳۶
۱#۱۶۵۵۶۲۰۸۲۱۲۷۴#######۹۰۰۰۰###############۰.۰۹#۹۰۰۰۰#۹۰۰۰۰#۱۰۹۰۰۰۰###شیبابا
۶۵۵۶۲۰۸۲۱۲۷۴#۰۰۰۲F2B4E7#1#1#0.0#2#########1#1000000###AA56CD0E0620002F2
B4E78#1090000#0###32652362589632#1#0.0#1000000#90000#90000#5656565#5646556
#۶۰۳۷ – ۹۹۷۲ – ۹۸۵۶ – ۹۸۶۵#۱۶۵۵۶۲۰۸۲۱۲۷۴#null#54554224#544542424

رشته تولید شده در مراحل بالا به وسیله کلید خصوصی (مودی/شرکت معتمد) با الگوریتم SHA256-RSA2048هش وامضا می شود و خروجی آن در فیلد dataSignature در شی packet قرارمی گیرد.

◊کد روش امضا در پیوست شماره ۱-۳ ارائه شده است.

۶-۳ نحوه رمزگذاری صورتحساب

برای رمزگذاری صورتحساب میبایست یک کلید متقارن (به روش AES/GCM/NoPADDING) با طول ۲۵۶ بیت تولید شود. برای رمزگذاری از طریق AES/GCM نیاز به یک کلید دیگر به نام IV به طول ۱۲۸ بیت می باشدکه این کلید به صورت تصادفی تولید می گردد. بعد از تولید کلیدهای مورد نیاز، JSON صورتحساب را ابتدا با کلید متقارن XOR کرده و سپس به روش AES/GCM رمزگذاری می گردد.

جزئیات XOR به این شکل است که باید متنی که میخواهیم XOR کنیم (در اینجا JSON صورتحساب) باید به بلاک های ۲۵۶ بیتی تبدیل شود و هر بلاک با کلید متقارن که ۲۵۶ بیت است XOR شود .با این روش ممکن است که بلاک آخر تعداد بیت کمتر از ۲۵۶ داشته باشد که با همان تعداد از کلید متقارن XOR انجام می شود . برای صورتحساب تستی بخش قبل کلید متقارن رمز شده و IV به صورت hex در زیر نمایش داده شده است :

AES key : 4fda3c622e966e0839441401bbd3b8f191d4267bf5f19b40812a34b212fd3ed9
IV : 4fda3c622e966e0839441401bbd3b8f191d4267bf5f19b40812a34b212fd3ed9

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

کد روش رمزگذاری به روش متقارن GCM/AES در پیوست ۱-۴ ارائه شده است.

پس از رمزگذاری صورتحساب، از طریق الگوریتم GCM/AES ،باید کلید متقارن رمز شده و IV در کنار صورتحساب رمزشده قرار گیرد. برای رمزگذاری کلید متقارن باید از روش نامتـقارن SHA256-OAEP-RSA استفاده شودکه برای این منظور از کلید/های عمومی سازمان با طول ۴۰۹۶ بیت اخذ شده از یک مرکز میانی معتبر استفاده می شود (کلید عمومی سازمان با استفاده از متدINFORMATION_SERVER_GET به دست می آید).

کد روش رمزگذاری به روش نامتقارن ۲۵۶RSA-OAEP-SHA در پیوست ۱-۵ ارائه شده است.

۷– فراخوانی متدهای API جمع آوری اطلاعات سامانه مودیان

۷-۱ آدرس API ها 

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

https://tp.tax.gov.ir/req/

آدرس هایی که با tsp شروع می شوند برای شرکت های معتمد ارائه کننده خدمات مالیاتی در نظر گرفته شده و آدرس هایی که با self-tsp شروع می شوند برای مودیانی که قصد دارند خودشان صورتحساب ارسال کنند در نظر گرفته شده است.

دومکانیزم برای درخواستهای با اولویت عادی و درخواستهای با اولویت بالا وجود دارد. آدرسnormal-enqueue برای درخواست های معمولی و fast-enqueue برای درخواستهای با اولویت بالا در نظر گرفته شده است.

متدها همراه با آدرس API در جدول(۲) ارائه شده اند.

۷-۲ ساختار درخواست ها

در این بخش ساختار درخواست ها به API شرح داده شده است. در جدول (۳)ساختار کلی درخواست ارائه شده است.

ساختار کلی سرویس همگام مشابه با سرویس غیرهمگام بوده و تفاوت آن درفیلد packet است. بطوری که در حالت همگام به جای آرایه ای از درخواست، فقط یک درخواست میتوان ارسال نمود (packet .)در درخواست غیرهمگام میتوان مجموعه ای از بسته ها (packets )را ارسال نمود.

دستورالعمل فنی نحوه اتصال به سامانه مودیان ۴۸

◊فیلد signatureKeyId اختیاری بوده و مقدار پیش فرض آن برابر با null خواهد بود.

اطلاعات تکمیلی فیلدها در جدول (۴)آورده شده است:

جدول ۴ .توضیحات مربوط به فیلدهای درخواست

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

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

ساختار بسته های ارسالی به سرور و فیلدهای مربوطه به ترتیب مطابق جداول (۵) و(۶) می باشد.

۷-۳ سرویس های جمع آوری و پردازش اطلاعات

درخواست همگام و غیرهمگام دو سرویس اصلی زیر سامانه جمع آوری و پردازش اطلاعات می باشند:

۷–۳–۱ متد غیرهمگام 

۷-۳-۱-۱ سرویس درخواست غیرهمگام (ارسال صورتحساب)

ارسال صورتحساب به صورت غیرهمگام انجام می شود و جهت ارسال به احراز هویت و امضا دیجیتال صورتحساب و کل لیست ارسالی و همچنین رمزگذاری نیاز است.

برای اینکه ساختار مناسبی برای رهگیری تغییرات بسته ها وجود داشته باشد، نوع بسته( PacketType)در صورتحساب به دو بخش تقسیم بندی می شود.

برای مثال اگر صورتحسابی با نسخه بسته ۰۱ داشته باشیم، نوع بسته به صورت زیر خواهد بود:

INVOICE.V01

فرآیند ارسال صورتحساب مطابق شکل(۳)و به شرح ذیل می باشد:

1. مودی یا TSP با ارسال درخواست توکن به سرور جمع آوری فرآیند ارسال صورتحساب را شروع می کند .
2. توکن دریافت شده در سرآیند درخواست قرار می گیرد و صورتحساب ارسال می شود.
3. مودی یا TSP رسید یکتای دریافت صورتحساب درخواست خود را از سامانه مودیان دریافت می کند .
4. مودی یا TSP می تواند به وسیله فراخوانی متدهای استعلام از وضعیت ارسال صورتحساب خود با خبر شود.

در صورتی که وضعیت درخواست به صورت “PENDING “باشد به این معنی است که هنوز درخواست پردازش نشده است.

نمونه CURL درخواست درپیوست ۲-۱ ارائه شده است.

۷–۳–۱–۲ ساختار بسته صورتحساب

شناسنامه همه اقلام اطلاعاتی که در انواع و الگوهای صورتحساب وجود دارند به شرح جدول(۷) می باشد:

 

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

۷–۳–۱–۳ پاسخ درخواست غیرهمگام

پس از دریافت درخواست توسط سرور و بررسی مربوط به لایه انتقال پاسخ مناسب مطابق جداول(۸) و (۹)به کلاینت ارائه می شود.

۷-۳-۲متدهای همگام

۷-۳-۲-۱سرویس درخواست های همگام

در جدول(۱۰) جزئیات ورودی و خروجی بسته های همگام بیان شده است.

لازم به ذکر است در متدهای همگام امضای درخواست ارسالی نیاز است و داده ها به رمزگذاری نیاز ندارند.

۷-۳-۲-۲ پاسخ درخواست های همگام

۷–۳–۲–۳ متد دریافت توکن 

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

برای ارسال توکن ابتدا عبارت Bearer اضافه شده سپس توکن ارسال می شود. نمونه CURL درخواست در پیوست ۲-۲ ارائه شده است.

۷–۳–۲–۴ متد استعلام اطلاعات حافظه مالیاتی مودی و حد مجاز فروش مودی

با استفاده از این متد میتوان اطلاعات حافظه مالیاتی مودی را دریافت نمود.این متد نیاز به احراز هویت دارد.

نمونه CURL درخواست در پیوست ۲-۳ ارائه شده است.

۷-۳-۲-۵ متد استعلام بستههای ارسالی غیرهمگام 

برای استعلام وضعیت صورتحساب های ارسال شده میتوان از متدهای ذیل استفاده کرد: این متدها به احراز هویت نیاز دارند.

• Inquiry_by_uid: کلاینت می تواند با آرایه ای از UID ها، صورتحساب های مورد نظر خود را استعلام نماید. در پاسخ وضعیت آنها باز گردانده می شود.

نمونه CURL درخواست در پیوست ۲-۴-۱ ارائه شده است  .

نکته : وجود fiscalId در ورودی درخواست کنار هر uid ضروری می باشد.

• Inquiry_by_reference_number: در این متد،    کلاینت   میتواند   با آرایه ای از reference_number ها ،صورتحساب های مورد نظر خود را استعلام نماید. در پاسخ وضعیت آنها باز گردانده می شود.

نمونه CURL درخواست در پیوست ۲-۴-۲ ارائه شده است.

• Inquiry_by_time: با این متد صورتحساب های دارای خطا از یک زمان مشخص تا زمان حال مشخص می شوند.

نمونه CURL درخواست در پیوست ۲-۴-۳ ارائه شده است.

• Inquiry_by_time_range: با این متد صورتحساب های دارای خطا در یک بازه زمانی مشخص می شوند.

نمونه CURL درخواست در پیوست ۲-۴-۴ ارائه شده است.

نکته: فیلد ^“time^“ ، تاریخ شمسی با فرمت YYYYMMDD است و دقت شود فقط در خروجی این درخواست بسته هایی که وضعیت FAILED دارند برگشت داده می شوند.

۷–۳–۲–۶ متد دریافت اطلاعات سرور

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

نمونه CURL درخواست در پیوست ۲-۵ ارائه شده است.

۷-۳-۲-۷ متد دریافت لیست کامل شناسه کالا/خدمات و نرخ مالیاتی

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

نمونه CURL درخواست در پیوست ۲-۶ ارائه شده است.

◊ارسال فیلد فیلتر و مرتب سازی در ورودی اختیاری است. شماره صفحه از یک شروع می شود.

برای مثال اگر ۱۰ رکورد اول را بخواهیم دریافت کنیم ورودی به صورت زیر خواهد بود:

۷–۳–۲–۸ متد استعلام اطلاعات شماره اقتصادی

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

نمونه CURL درخواست در پیوست ۲-۷ ارائه شده است.

۸– لیست خطاها

۸-۱ مدل داده خطاها

۸-۲ لیست خطاهای لایه انتقال

 8-3لیست خطاهای لایه محتوا

پیوست۱

۱-۱ کد نرمالسازی JSON به زبان java

⇐ در کلاس CryptoUtils در کد بالا می توانید از متد استاتیک normalJson استفاده کنید.

۲-۱ کد DotNet برای نرمالسازی JSON

⇐کد بالا از کلاس دیگری به نام JSONHelper استفاده می کند که در ادامه آورده شده:

 

⇐ در کلاس CryptoUtils می توانید از متد NormalJson برای نرمالسازی JSON مدنظر استفاده کنید.

۱–۳ روش امضا رشته( string)

۱-۳-۱ کد جاوا

۱-۳-۲ کد #C

 

۱–۴ کد روش رمزگذاری به روش متقارن AES/ GCM 

۱–۴–۱ کد جاوا :  

⇐ متد نحوه ایجاد کلید متقارن Random:

⇐ متد ایجاد یک مقدار Random مورد استفاده در رمزنگاری متقارن(IV)

⇐ نحوه رمزنگاری با استفاده از SecretKey و IV

⇐ کد نحوه XOR کردن دو آرایه

۱–۴–۲ کد #C

در #C می توانید با [ ]byte به صــورت کاملا تصــادفی دو کلید IV و Secret Key را ایجاد کنید و از روش زیر متن خود را encrypt کنید :

۵– کد روش رمزگذاری به روش نامتقارن RSA_OAEP_SHA256

۱-۵-۱ کد جاوا

۲-۵-۱ کد #C

پیوست ۲

۱-۲ دریافت صورتحساب

• نمونه CURL :

 

• نمونه پاسخ درخواست بالا

• نمونه پاسخ درخواست در صورت رخداد خطا

 

۲-۲ متد دریافت توکن

• نمونه CURL:

• نمونه پاسخ درخواست

 

 

۲-۳ استعلام اطلاعات حافظه مالیاتی مودی و حد مجاز فروش مودی

• نمونه CURL:

• نمونه پاسخ سرویس بالا:

۴-۲ دریافت پاسخ بسته های ارسالی غیر همگام (استعلام)

۱-۴-۳ استعلام از طریق :UID (Inquiry_by_uid)

• نمونه CURL:

 

۲-۴-۲ استعلام با رسید یکتای دریافت صورتحساب (Inquiry_by_reference_number):

•  نمونه ارسال درخواست CURL :  

۲–۴–۳ دریافت خطاهای بسته های ارسالی غیرهمگام با استفاده از زمان(INQUIRY_BY_TIME):

• نمونه CURL:

۲-۴-۴ دریافت خطاهای بسته های ارسالی غیر همگام با استفاده از بازه زمانی(NQUIRY_BY_TIME_RANGE)

• نمونه CURL:

 

۲-۴-۵ نمونه پاسخ درخواست های استعلام

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

۵-۲ دریافت اطلاعات سرور (GET_SERVER_INFORMATION)

• نمونه CURL:

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

۶-۲ دریافت لیست کامل شناسه کالا/خدمات و نرخ مالیاتی (GER_SERVER_STUFF_LIST)

• نمونه CURL:

• نمونه پاسخ

۷-۲ استعلام اطلاعات شماره اقتصادی (GET_ECONOMIC_CODE_INFORMATION)

• نمونه CURL