جدول تغییرات سند
نسخه	ورژن	شرح تغییرات	تاریخ
0	2	فیلد Cashofpayment حذف و فیلد creditPaymentAmount در هدر صورتحساب اضافه شد.	1401/10/03
		افزودن Api ثبت کالا/خدمات	1401/11/26
		تغییر URL سرویس ثبت صورتحساب	1401/11/26
		تغییر قالب خروجی دریافت اطلاعات صورتحساب	1401/12/05
		تغییر سمپل کد ورودی و افزودن جدول فیلدهای اختصاصی الگوها	1401/12/15
		تغییر برخی فیلدهای API	1401/12/16
		افزودن کد شعبه خریدار و فروشنده	1401/12/27
		افزودن متد استعلام و حذف صورتحساب	1402/01/22
3	6	اطلاعات خریدار (کد اقتصادی، شناسه ملی/ کد ملی/ شناسه مشارکت/ کد اتباع و کدپستی خریدار) در الگوی قبوض خدماتی اختیاری شد.	1402/03/01
		کد شعبه خریدار و فروشنده در الگوی قبوض خدماتی اختیاری شد.
		نوع پرواز و شماره گذرنامه خریدار به الگوی فروش بدون اطلاعات خریدار اضافه شد و این فیلدها اختیاری است.
		شماره گذرنامه خریدار در الگوی بلیت هواپیما اختیاری شد.
		فیلدهای شماره کوتاژ اظهارنامه گمرکی، تاریخ کوتاژ اظهارنامه گمرکی و وزن خالص در الگوی صادرات اختیاری شد.
		در مورد صورتحسابهای الکترونیکی با الگوی صادرات، جهت بهره‌مندی از معافیت نرخ صفر و مشوق‌های مالیاتی میبایست فیلدهای شماره کوتاژ اظهارنامه گمرکی و تاریخ کوتاژ اظهارنامه گمرکی تکمیل گردند.
		در صورتحسابهای الکترونیکی با الگوی صادرات، ارزش ارزی کالا می بایست دقیقا منطبق با اظهارنامه گمرکی در صورتحساب ثبت شود.
		در مورد صورتحسابهای الکترونیکی با الگوی صادرات، جهت بهره مندی از معافیت نرخ صفر و مشوق‌های مالیاتی میبایست تناظر یک به یک رعایت شود و به ازای هر اظهارنامه گمرکی، یک صورتحساب الکترونیکی صادر و به سامانه مودیان ارسال گردد.
		بهبود توضیحات تشریح فیلدها
		افزودن فیلد کد همکاری
		افزودن فیلد اطلاعات اضافی شرح کالا
4.1	6	امکان دریافت گزارش صورتحساب‌های خرید	1402/05/09
		امکان دریافت گزارش سرجمع صورتحساب‌ها
		افزودن فیلد ExtendStuffTitle در بدنه صورتحساب
		افزودن متد استعلام ثبت کالا/خدمت
		افزودن متد استعلام خریدار
		اختیاری شدن فیلد نوع خریدار در صورتحساب های نوع 2
4.2	6	به جای مبلغ واحد، ارزش ریالی طبق اظهارنامه تکمیل می‌شود	1402/06/07
4.2	6	اضافه شدن فیلد شماره ملی / کد اتباع مسافر در الگوی هواپیما	1402/06/07
4.3	6	افزودن متد ویرایش (ارسال مجدد) صورتحساب	1402/06/19
5.0	6	افزودن فیلد «تفاوت نرخ خرید و فروش ارز» در الگوی فروش ارز	1402/07/04
		تغییر قاعده مربوط به شناسه یکتای قرارداد فروشنده و حق‌العمل‌کاری
		فیلدهای «مبلغ واحد»، «روش تسویه»، «واحد اندازه گیری»، «تعداد/مقدار» و «مبلغ نسیه» در الگوی ارزی و فیلد «شماره پروانه گمرکی فروشنده» در الگوی صادرات ignore شدند.
6.0	6	افزودن متد استعلام صورتحساب بر اساس شماره منحصربه‌فرد مالیاتی	1402/08/24
7.0	7	تغییر در قواعد کنترلی اختصاصی فیلد مبلغ مالیات بر ارزش افزوده -مرتبط با الگوی طلا، جواهر و پلاتین/استعلام از طریق شماره داخلی صورتحساب	1403/03/01
7.1	7	تغییر در متد های استعلام شناسه کالا/خدمت تغییرات قواعد شماره اقتصادی	1403/03/03
7.2	7	تغییر در متد دریافت توکن و دسترسی به سرویس ها برای کاربرانی که با یک نام کاربری چند پرونده دارند. روش تسویه در الگوهای فروش ارز و بلیت هواپیما الزامی شده است. تمامی فیلدهای ریالی به جز مبلغ واحد و تفاوت نرخ خرید و فروش/کارمزد اعشار نمی پذیرند. فیلد تفاوت نرخ خرید و فروش ارز/کارمزد حداکثر 8 رقم اعشار می‌پذیرد.

نحوه اتصال سرویس خارجی به API

فرآیند دریافت و دسترسی به سرویس‌ها

– متقاضی (مؤدی) از طریق تماس با شرکت با ارائه اطلاعات لازم، درخواست دریافت خدمات اتصال به سرویس و دریافت نام کاربری و رمز عبور تستی را اعلام می‌کند.

– تعریف کاربر تستی از نوع سرویس خارجی در سامانه کیسان توسط تیم فنی کیسان صورت می‌پذیرد.

– تخصیص نقش و دسترسی‌های موردنیاز به کاربر تستی توسط تیم فنی کیسان به انجام می‌رسد.

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

در صورتی که تست با موفقیت انجام شد کاربر میتواند با نام کاربری و رمز عبور مالیاتی خود (my.tax.gov.ir) روال اصلی ثبت صورتحساب‌هایش را پیگیری کند.

جزئیات دریافت دسترسی (توکن)

ارسال درخواست

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

دريافت توكن

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

نمونه یک توکن

BearereyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJqdGkiOiIyYzEyZDNjMy1jNTYxLTQ2YTgtOWVjNy1kNGNhZGVhYzQ2OTkiLCJ1aWQiOiIwMWVhNmU1ZS04YzExLTRlZWItYjMwNy1kM2JjYjUxNmRkOTYiLCJ1Y2lkIjoiZWIwYzlhYjktMzk4Zi00NDI4LThhNjgtYWY2Y2EwMWUyOTVkIiwicHVpZCI6IjAxZWE2ZTVlLThjMTEtNGVlYi1iMzA3LWQzYmNiNTE2ZGQ5NiIsInB1Y2lkIjoiZWIwYzlhYjktMzk4Zi00NDI4LThhNjgtYWY2Y2EwMWUyOTVkIiwibmF0aW9uYWxjb2RlIjoiMTExMTExIiwibmFtZSI6ImFkbWluIiwiaXNhZG1pbiI6IlRydWUiLCJicmFuY2hpZCI6IiIsImNvbXBhbnlpZCI6IiIsImV4cCI6MTY0MzQ1NzkxNywiaXNzIjoiV2luZG93TGluay5TZWN1cml0eS5CZWFyZXIiLCJhdWQiOiJXaW5kb3dMaW5rLlNlY3VyaXR5LkJlYXJlci5Vc2VyIn0.rK3tg1p2oxKMsbr9CgV5F_gua3rs5JL59GgEr_8CHyA

سرویس دریافت توکن دسترسی

URL سرویس دریافت توکن دسترسی به سامانه برای کاربر

[server-url]/identity/api/servicetoken

مقادیر ورودی

نام	نوع	توضیحات
ServiceLoginViewModel	object

ServiceLoginViewModel
نام	نوع	توضیحات
UserName	String	نام کاربری
Password	String	کلمه عبور
EconomicCode	String	کد اقتصادی

مقادیر خروجی

نام	نوع	توضیحات
Result	object

Result
نام	نوع	توضیحات
Error	Bool	آیا عملیات با خطا مواجه شده است
Message	String	پیام خطا
Data	ServiceAuthenticationModel	توکن

Result
نام	نوع	توضیحات
Error	Bool	آیا عملیات با خطا مواجه شده است
Message	String	پیام خطا
Data	ServiceAuthenticationModel	توکن

ServiceAuthenticationModel
Token	string	توکن
RefreshToken	string	رفرش توکن

توضیحات:

در صورت موفق بودن فراخوانی و ایجاد توکن، مقدار فیلد error برابر False می‌شود و در بخش دیتا، توکن قرار داده می‌شود. توجه داشته باشید که هر توکن تا 10 دقیقه معتبر خواهد بود و هر 10 دقیقه یکبار باید درخواست دریافت توکن ارسال شود.

سرویس دریافت توکن دسترسی برای کاربرانی که با یک نام کاربری در کیسان چند پرونده مالیاتی دارند

[server-url]/identity/api/servicetoken

مقادیر ورودی

نام	نوع	توضیحات
ServiceLoginViewModel	object

ServiceLoginViewModel
نام	نوع	توضیحات
UserName	String	نام کاربری
Password	String	کلمه عبور
EconomicCode	String	کد اقتصادی

مقادیر خروجی

نام	نوع	توضیحات
Result	object

Result
نام	نوع	توضیحات
Error	Bool	آیا عملیات با خطا مواجه شده است
Message	String	پیام خطا
Data	ServiceAuthenticationModel	توکن

ServiceAuthenticationModel
Token	string	توکن
RefreshToken	string	رفرش توکن

ارسال اطلاعات به سامانه جمع ‌آوری کیسان

صورتحساب شامل سه بخش سرآمد، بدنه و پرداخت می‌باشد. با توجه به همین سه بخش فایل json ارسالی به کیسان نیز شامل سه بخش invoice، invoice Items و invoice Payment می‌باشد.

تشریح فیلدها

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

هدر صورتحساب
توضیح	نوع فیلد	نام فیلد
شماره صورتحساب	string		invoiceNumber
این ستون در بر گیرنده تاریخ (میلادی) صدور صورتحساب صادر شده از طرف فروشنده است.	string		invoiceDate
تاریخ و زمان ایجاد صورتحساب	Timespan		invoiceTime
نوع انجام معامله(لیست شماره8)	int		saleType
شماره منحصر به فرد مالیاتی صورتحساب مرجع: همان شماره مالیاتی صورتحساب اصلی می‌باشد؛ تنها در صورتی که صورتحساب ارسالی با موضوع اصلاحی، ابطالی و یا برگشت از فروش باشد، ثبت این فیلد الزامی است. رعایت بازه‌های زمانی مجاز جهت صدور صورتحساب باموضوع: اصلاحی، ابطالی یا برگشت از فروش ابلاغ شده از سوی سازمان، الزامی است.	string		referenceTaxSerialNumber
مشخص کننده نوع صورتحساب که شامل نوع ۱ و ۲ است می‌باشد و با کد 1 یا 2 مقدار دهی می شود. هر فایل باید تنها شامل یک نوع صورتحساب باشد. صورتحساب الکترونیکی نوع اول (1)همراه با اطلاعات خریدار. صورتحساب الکترونیکی نوع دوم (2) صورتحسابی با اطلاعات کامل از کالا/ خدمت و بدون اطلاعات خریدار است. صورتحساب الکترونیکی نوع دوم (2) صورتحساب نقدی تلقی شده، از بابت آن اعتبار مالیاتی برای خریدار قابل احتساب نمی‌باشد.	int		invoiceType
مشخص کننده الگوی صورتحساب (لیست شماره 5)	int		invoicePattern
موضوع صورتحساب (لیست شماره6)	int		invoiceSubject
روش تسویه (لیست شماره 3)	Int		paymentType
شناسه منحصر به فردی که صورتحساب با این شناسه در سیستم ثبت شده است. اگر صورتحساب با موفقیت ثبت شود، در پاسخ شماره منحصر به فرد مالیاتی همراه با این شناسه برای شما ارسال خواهد شد.	Guid		uniqueId
کد شعبه فروشنده	int		SellerBranch
نوع خریدار(لیست شماره9)	int		buyerType
نام شرکت خریدار	string		buyerCompanyName
نام خریدار	string		buyerFirstName
نام خانوادگی خریدار	string		buyerLastName
شناسه ملی خریدار: در صورتی که خریدار فعال اقتصادی باشد و صورتحساب از نوع اول باشد، تطابق اطلاعات مربوط به خریدار الزامی است (لیست شماره 11)	string		buyerNationalCode
شماره اقتصادی خریدار: در صورتی که خریدار فعال اقتصادی باشد و صورتحساب از نوع اول باشد، تطابق اطلاعات مربوط به خریدار الزامی است.(لیست شماره 11)	string		buyerEconomicCode
شماره گذرنامه خریدار (پاسپورت) (لیست شماره 11)	string		buyerPassportNumber
کد پستی خریدار.(لیست شماره 11)	string		buyerPostalCode
شماره همراه خریدار	String		buyerPhoneNumber
کد گمرک محل اظهار فروشنده	string		sellerCustomsDeclarationNumber
شماره پروانه گمرکی فروشنده	string		sellerCustomsLicenseNumber
شناسه یکتای ثبت قرارداد فروشنده باید دقیقا مطابق با شماره قرارداد موجود در کارپوشه باشد. همچنین توجه به نکات زیر الزامی است: فروشنده پیمانکار بوده و خریدار کارفرما است. تاریخ صدور صورتحساب پس از تاریخ شروع قرارداد پیمانکار و کارفرما است. هر دو طرف قرارداد، پیمانکار و کارفرما، باید قرارداد مذکور را در کارپوشه خود تایید کنند.	string		sellerContractRegistrationNumber
نوع پرواز (لیست شماره10)	int		flightType
اگر در الگوی بلیت هواپیما، نوع خریدار حقوقی و یا مشارکت باشد، تکمیل فیلد کد ملی/ کد اتباع غیرایرانی مسافر اجباری است.	string		PassengerNationalCode
میزان مبلغ نسیه در روش نقدی/نسیه که طبق فرمول زیر است: Cr=Xs-W2_W_C :Cمبلغ پرداختی نقدی W:مجموع مالیات بر ارزش افزوده :مجوع سایر مایات،عوارض و وجوه قانونیW2 :مجموع صورتحسابXs	Decimal		creditPaymentAmount
شماره اشتراک /شناسه قبض بهره بردار	string		billId
در صورت مشمول بودن، مالیات موضوع ماده 17 (قانون پایانه های فروشگاهی و سامانه مؤدیان) می بایست کوچکتر یا حداکثر برابر با مجموع مالیات برارزش افزوده و مجموع سایر مالیات، عوارض و وجوه قانونی در صورتحساب باشد.	decimal		tax17
شماره کوتاژ اظهارنامه گمرکی	string		CustomsDeclarationCottageNumber
تاریخ کوتاژ اظهارنامه گمرکی	string		CustomsDeclarationCottageDate
توضیحات صورتحساب (حداکثر ۵۰۰ کاراکتر)	string		description

اقلام صورتحساب
توضیح	نوع فیلد	نام فیلد
برای کالاها و خدمات این فیلد مقدار 1 می‌گیرد	int	commodityType
قبل از ثبت صورتحساب باید لیست شناسه‌های کالاها یا خدمات خود را در کیسان و در بخش (سرویس‌ها -> کالا/خدمات) ثبت کنید. “یا از طریق سرویس ثبت کالا و خدمات که در همین سند توضیح داده شده است.” این فیلد شامل شناسه های داخلی است. توجه مهم: هر کالا یک شناسه 13 رقمی و یک شناسه داخلی دارد که می‌تواند با شناسه 13 رقمی یکسان یا متفاوت باشد. در این ستون مقدار شناسه داخلی قرار می‌گیرد.	string	commodityCode
تعداد یا مقدار کالا یا خدمت مورد معامله است. این فیلد مقادیر اعشاری نیز می‌پذیرد.	decimal	amount
“این فیلد فقط مقدار عددی می‌پذیرد. از فایل کد واحد های اندازه گیری، کد واحد مورد نظر را یافته و در این ستون وارد کنید. نمونه صحیح برای واحد کیلوگرم: 164(پیوست شماره 1)	int	unitType
این ستون فقط مقدار عددی می‌پذیرد. نوع ارز مورد معامله را نشان می‌دهد. این ستون با کدهای مربوط به iso 4217 تکمیل می‌شود. نمونه صحیح برای ریال ایران: 364 در صورت خالی ماندن این ستون مقدار آن 364 که به معنای ریال ایران است در نظر گرفته می‌شود.(پیوست شماره 2)	int	moneyType
مبلغ واحد کالا/ خدمات ین ستون نشان می‌دهد هر واحد کالا یا خدمت چه قیمتی دارد. مبلغ واحد میبایست بزرگتر از صفر باشد. در مورد صورتحساب‌های الکترونیکی با الگوی صادرات نیز، نیازی به ارسال فیلد مبلغ واحد نیست و به جای آن باید ارزش ریالی ارسال گردد. در این صورت مبلغ واحد برابر می‌شود با ارزش ریالی تقسیم بر تعداد/مقدار.	decimal	unitPrice
میزان تخفیف کالا/خدمات؛ این تخفیف روی کل تعداد قلم کالاست؛ یعنی اگر 5 عدد کالا با تخفیف هرکدام 100 ریال مدنظر باشد، مبلغ تخفیف 500 می‌باشد. این فیلد اعشار نمی‌پذیرد. در صورتی که مبلغ تخفیف صفر باشد، مقدار این فیلد صفر ثبت می‌شود. حتی در فروش با نوع ارز غیر ریالی این فیلد باید با معادل ریالی تکمیل شود.	decimal	discount
نرخ مالیات بر ارزش‌افزوده : درصد مالیات بر ارزش افزوده را نشان می‌دهد و باید به صورت عددی بدون درصد تکمیل شود. نمونه مقدار صحیح: 9 یعنی 9 درصد مالیات بر ارزش افزوده برای کالا/خدمت لحاظ شده است.	decimal	taxPercent
مبلغ مالیات بر ارزش‌افزوده: حاصل‌ضرب مبلغ کالا پس از کسر تخفیفات در نرخ مالیات بر ارزش‌افزوده است. مبلغ مالیات بر ارزش افزوده باید با نرخ آن همخوانی داشته باشد. در صورت خالی بودن بر اساس درصد مالیات محاسبه می‌شود.( این فیلد میتواند خالی نیز باشد)	decimal	taxPrice
درصد سایر عوارض و مالیات: در صورت تکمیل این فیلد باید موضوع سایر مالیات و عوارض الزاما تکمیل شود.	decimal	dutyPercent
مبلغ سایر عوارض و مالیات: مبلغ سایر عوارض و مالیات که باید با درصد آن همخوانی داشته باشد. در صورت خالی بودن مقدار آن بر اساس درصد سایر عوارض و مالیات محاسبه می‌شود.	decimal	dutyPrice
موضوع سایر عوارض و مالیات: در صورت تکمیل فیلد نرخ سایر مالیات و عوارض باید موضوع سایر مالیات و عوارض الزاما تکمیل شود.	string	dutyTitle
شماره قرارداد بورسی: در صورتی که برای صورتحساب مشخصی در بخش صورتحساب، فیلد «نوع انجام معامله» با اعداد 2 تا 4 تکمیل شود یا به عبارت دیگر معامله بورسی باشد، باید دو ستون «شماره قرارداد» و «تاریخ قرارداد» حتما تکمیل شوند.	String	ExchangeContractNumber
تاریخ قرارداد بورسی: در صورتی که برای صورتحساب مشخصی در بخش صورتحساب، فیلد «نوع انجام معامله» با اعداد 2 تا 4 تکمیل شود یا به عبارت دیگر معامله بورسی باشد، باید دو ستون «شماره قرارداد» و «تاریخ قرارداد» حتما تکمیل شوند.	String	exchangeContractDate
میزان ارز: در مورد صورتحسابهای الکترونیکی با الگوی فروش ارزی میزان ارز معادل تعداد/مقدار ارز مورد معامله می‌باشد. در صورتحسابهای با الگوی غیر از فروش ارزی، میزان ارز برابر است با: حاصل تقسیم مبلغ واحد بر نرخ برابری ارز با ریال. مبلغ واحد نرخ برابری ارز با ریال	decimal	currencyAmount
موضوع سایر وجوهات قانونی : در صورت مقدار داشتن مبلغ و یا نرخ سایر وجوهات قانونی موضوع آن باید در این ستون درج شود.	string	otherLegalFundsTitle
نرخ سایر وجوهات قانونی: در صورت خالی بودن این ستون و پر بودن مبلغ سایر وجوهات قانونی نرخ آن محاسبه خواهد شد.	decimal	otherLegalFundsPercent
مبلغ سایر وجوهات قانونی: مبلغ سایر وجوهات قانونی که باید با نرخ آن همخوانی داشته باشد.در صورت خالی بودن مقدار آن بر اساس نرخ سایر وجوهات قانونی محاسبه می‌شود.	decimal	otherLegalFundsPrice
اجرت ساخت: هزینه‌ای است که طلا فروش برای ساخت و طراحی طلا از مشتری دریافت می‌نماید. مقدار این فیلد ریالی است. به عنوان اجرت ساخت معادل یک گرم به قیمت خام افزوده می‌شود و از مبلغ واحد کمتر است.	decimal	constructionWages
سود فروشنده: هزینه‌ای است که فروشنده بابت سود خود در صورتحساب‌های با الگوی طلا، جواهر وپلاتین لحاظ می‌نماید. به بیان دیگر، ما به التفاوت مبلغ فروش و هزینه است. مقدار این فیلد ریالی است.	decimal	saleProfit
حق العمل: مبلغی که بابت فروش حق‌العمل کاری طلا از خریدار دریافت می‌گردد(ریال) در صورتی که شناسه کالا/خدمت متعلق به فعالیت‌های حق‌العمل‌کاری طلا و جواهر باشد درصورتحساب ثبت می‌شود.	decimal	brokerCommission
شناسه یکتای ثبت قرارداد حق العمل کاری : اگر کالا از طریق حق‌العمل‌کار فروخته می‌شود می‌توان شماره قرارداد حق‌العمل‌کاری را در این ستون وارد کرد. این فیلد باید دقیقا مطابق با شماره قرارداد موجود در کارپوشه باشد و همچنین رعایت نکات زیر الزامی است: تاریخ صدور صورتحساب پس از تاریخ شروع قرارداد حق‌العمل‌کاری است. هر دو طرف قرارداد باید قرارداد مذکور را در کارپوشه خود تایید کنند.	string	brokerContractNumber
وزن خالص در الگوی صادرات برای صادرات کالا اجباری است و بر حسب کیلوگرم‌طبق اظهارنامه گمرکی ثبت می‌شود. در صادرات خدمت این مقدار را می‌توان صفرارسال کرد.	decimal	NetWeight
ارزش ارزی: ارزش هر قلم کالا/خدمت موجود در اظهارنامه گمرکی بر حسب ارز و طبق ارزش مندرج در پروانه گمرکی است. حداکثر تعداد رقم صحیح ،15حداکثر تعداد رقم اعشار 4 است. ارزش ارزی کالا می‌بایست بزرگتر از صفر باشد. در صورتحساب‌های الکترونیکی با الگوی صادرات، ارزش ارزی کالا می بایست دقیقا منطبق با اظهارنامه گمرکی در صورتحساب ثبت شود.	decimal	StuffCurrencyValue
این مقدار نشان می‌دهد هر سطر از کالاها یا خدمات مجموعا چه قیمتی به ریال دارد. ارزش ریالی کالا باید بزرگتر از صفر باشد و مطابق با اظهارنامه گمرکی تکمیل گردد. توجه: در مورد صورتحساب‌های الکترونیکی با الگوی صادرات، مقدار فیلد مبلغ واحد محاسباتی است و از تقسیم ارزش ریالی به تعداد/مقدار توسط سامانه کیسان بدست می‌آید.	decimal	StuffIRRValue
اطلاعات اضافی شرح کالا: با توجه به اعلام نیاز کاربران مبنی بر این که به ازای هر قلم کالا بتوان مقدار یا توضیح مازادی را نیز به سامانه مودیان ارسال کرد، این فیلد طراحی شده است. هر مقداری که در این فیلد وارد کنید به « عنوان کالا یا خدمت» شما اضافه شده و به کارپوشه مودیان ارسال خواهد شد. برای نمونه می‌توان شماره بیمه‌نامه را در این قسمت وارد نمود.	string	ExtendStuffTitle
تفاوت نرخ خرید و فروش ارز/ کارمزد فروش ارز: قدار این فیلد در فروش اسکناس/حواله برابر است با تفاوت نرخ خرید ارز اعلامی بانک مرکزی جمهوری اسلامی ایران از نرخ فروش آن در تاریخ معامله.(تاریخ صدور صورتحساب) یا حاشیه سود اضافه شده به قیمت خرید (مطابق بخشنامه‌های بانک مرکزی جمهوری اسلامی).	decimal	PurchaseSalePriceDifference
عیار در صورت حساب های الکترونیکی با الگوی طلا، جواهر و پلاتین از این فیلد برای نمایش درجه خلوص طلای فروخته شده استفاده میگردد.	string	cutie
شماره اقتصادی آزانس/ در صورتحسابهای الکترونیکی با الگوی بلیط هواپیما در صورتیکه عامل فروش بلیط هواپیما، آژانس مسافرتی بوده و لی صورتحساب فروش بلیط توسط شرکتهای هواپیمایی صادر شود در این فیلد شماره اقتصادی آژانس مسافرتی عامل وارد میشود.	string	agencyEconomicCode

پرداخت صورتحساب
نام فیلد	نوع فیلد	توضیح
مبلغ پرداخت نقدی: مبلغ پرداخت را مشخص می‌کند حتی در فروش با نوع ارز غیر ریالی این فیلد باید با معادل ریالی تکمیل شود. این فیلد را طبق راهنمای تکمیل فیلد مبلغ پرداخت، تکمیل نمایید.	decimal	paymentAmount
روش پرداخت((لیست شماره 1)	int	paymentMethod
تاریخ پرداخت به میلادی	DateTime	paymentDate
شماره سوییچ در صورت پرداخت با کارت اعتباری	string	switchNumber
شماره پذیرنده در صورت پرداخت با کارت اعتباری	string	acceptanceNumber
شماره ترمینال در صورت پرداخت با کارت اعتباری	string	terminalNumber
کد رهگیری در صورت پرداخت با کارت اعتباری	string	traceNumber
شماره کارت پرداخت‌کننده در صورت پرداخت با کارت اعتباری	string	payerCardNumber
شماره ملی/کد فراگیر پرداخت‌کننده	string	payerNationalCode

تغییرات در ارقام اعشار اقلام صورتحساب
تمامی فیلدهای ریالی به جز مبلغ واحد و تفاوت نرخ خرید و فروش/کارمزد اعشار نمی پذیرند.
ردیف	نام فیلد	مقدار اعشار
1	تعداد/مقدار	8 رقم اعشار
2	مبلغ واحد	8 رقم اعشار
3	تفاوت نرخ خرید و فروش/کارمزد ارز	8 رقم اعشار
4	میزان ارز	4 رقم اعشار
5	ارزش ارزی	4 رقم اعشار

جدول 1- شرایط فیلدها در الگوهای صورتحساب

قالب ورودی اطلاعات

URl سرویس ثبت صورتحساب:

[server-url] /taxpayer/api/InvoiceExternalService_v6

قالب ورودی اطلاعات به صورت جیسون بر اساس نمونه تکمیل‌شده شامل موارد زیر است:

Header:

{ ‘Content-Type’: ‘application/json ; charset=utf-8’,

‘Authorization’ : “Bearer ” + token }

Body:

[

{

“invoiceNumber”: “string”,

“invoiceDate”: “2024-05-28T13:39:01.639Z”,

“invoiceTime”: “string”,

“saleType”: 0,

“referenceTaxSerialNumber”: “string”,

“invoicePattern”: 0,

“invoiceType”: 0,

“invoiceSubject”: 0,

“paymentType”: 0,

“uniqueId”: “3fa85f64-5717-4562-b3fc-2c963f66afa6”,

“sellerBranch”: “string”,

“buyerType”: 0,

“buyerCompanyName”: “string”,

“buyerFirstName”: “string”,

“buyerLastName”: “string”,

“buyerNationalCode”: “string”,

“buyerEconomicCode”: “string”,

“buyerPassportNumber”: “string”,

“buyerPostalCode”: “string”,

“buyerBranch”: “string”,

“buyerPhoneNumber”: “string”,

“sellerCustomsDeclarationNumber”: “string”,

“sellerCustomsLicenseNumber”: “string”,

“sellerContractRegistrationNumber”: “string”,

“flightType”: 0,

“creditPaymentAmount”: 0,

“passengerNationalCode”: “string”,

“passengerPassportNumber”: “string”,

“billId”: “string”,

“tax17”: 0,

“customsDeclarationCottageNumber”: “string”,

“customsDeclarationCottageDate”: “2024-05-28T13:39:01.639Z”,

“cooperationCode”: “string”,

“description”: “string”,

“isUpdate”: true,

“invoiceItems”: [

{

“commodityCode”: “string”,

“extendStuffTitle”: “string”,

“amount”: 0,

“unitType”: 0,

“moneyType”: 0,

“equivalentToRial”: 0,

“unitPrice”: 0,

“discount”: 0,

“taxPercent”: 0,

“taxPrice”: 0,

“dutyPercent”: 0,

“dutyPrice”: 0,

“dutyTitle”: “string”,

“exchangeContractNumber”: “string”,

“exchangeContractDate”: “2024-05-28T13:39:01.639Z”,

“currencyAmount”: 0,

“otherLegalFundsTitle”: “string”,

“otherLegalFundsPercent”: 0,

“otherLegalFundsPrice”: 0,

“constructionWages”: 0,

“saleProfit”: 0,

“brokerCommission”: 0,

“brokerContractNumber”: “string”,

“netWeight”: 0,

“stuffIRRValue”: 0,

“stuffCurrencyValue”: 0,

“purchaseSalePriceDifference”: 0,

“cutie”: 0,

“agencyEconomicCode”: “string”

}

“invoicePayments”: [

{

“paymentMethod”: 0,

“paymentAmount”: 0,

“paymentDate”: “2024-05-28T13:39:01.639Z”,

“switchNumber”: “string”,

“acceptanceNumber”: “string”,

“terminalNumber”: “string”,

“traceNumber”: “string”,

“payerCardNumber”: “string”,

“payerNationalCode”: “string”

}

]

}

]

قالب خروجی ثبت صورتحساب:

[

{

“status”: “int”,

“uniqueId”: “string”,

“trakingId”: “string”,

“taxSerialNumber”: “string”,

“description”: ” string “,

“title”: ” string “

}

]

نتیجه دریافت اطلاعات توسط سامانه جمع‌آوری اطلاعات کیسان

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

قالب خروجی نتیجه دریافت اطلاعات

قالب خروجی نتیجه دریافت اطلاعات به صورت جیسون شامل موارد زیر است:

{

“status”: “int”,

“uniqueId”: “string”,

“commodityCode”: “string”,

“TaxSerialNumber”: “string”,

“TrackingId”: “string”,

“description”: “string”,

“title”: “string”

}

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

فیلد	عنوان فیلد	توضیح
status	وضعیت استعلام	(لیست شماره 2)
uniqueId	کد یکتای ثبت صورتحساب	کد یکتایی است که کاربر آن را تولید کرده و صورتحساب را با توجه به این کد برای سامانه کیسان ارسال کرده است.
commodityCode	شناسه داخلی کالا	در صورتی که صورتحسابی حاوی خطا در بخش اقلام صورتحساب، شناسه داخلی کالای خطادار برگردانده می‌شود.
TaxSerialNumber	شماره منحصر به فرد مالیاتی 22 رقمی	در صورتی که صورتحساب به درستی ثبت شود و فیلد status مقدار 3 داشته باشد، شماره منحصر به فرد مالیاتی به آن اختصاص داده می‌شود.
TrackingId	کد رهگیری	کدی منحصر بفرد درسامانه کیسان و سامانه مودیان است.
description	توضیحات	در صورت وجود خطا توضیحات خطا در این بخش نمایش داده می‌شود.
title	عنوان	عنوان فیلد دارای خطا است.

تشریح نتیجه

در حالت کلی 2 نوع خطا ممکن است دریافت شود که به شرح ذیل است:

خطا در مقدار های ارسالی به طور مثال شناسه کالا /خدمت

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

{

“status”: 1,

“uniqueId”: “8b8a3877-a7cf-4d8c-bdd9-ec5d599dfab9”,

“commodityCode”: “0831100692420001”,

“description”: “کد کالا نامعتبر است”,

“title”: “CommodityCode”

}

خطا در ثبت صورتحساب تکراری

اگر کاربر صورتحساب تکراری ثبت نماید، UniqeId صورتحساب به همراه شماره صورتحساب به وی نمایش داده می‌شودو status برابر با 2 می شود:

{

“status”: 2,

“uniqueId”: “8b8a3877-xxxx-xxxx-xxxx-ec5d599dfab9,

“description, “یک صورتحساب با این شماره و تاریخ وجود دارد”:”

“title”: “InvoiceNumber”

}

اگر صورتحسابی به‌صورت موفق ثبت و ارسال گردد، مقدار فیلد status برابر با 3 شده و شماره منحصربه‌فرد مالیاتی آن به کاربر نمایش داده می‌شود.

{

“status”: 3,

“uniqueId”: “8b8a3877-xxxx-xxxx-xxxx-ec5d599dfab9”,

“TaxSerialNumber”: “XXXXXXXXXXXXXXXXXXXXXX”,
“description”:””,

“title”: “”

}

ثبت کالا/خدمات

جهت ثبت اطلاعات کالا و خدمات می‌توان از URL زیر جهت اتصال به وب‌سرویس استفاده نمود:

[server-url] /taxpayer/api/CommodityServiceExternalService

اطلاعات کالا/خدمات می‌بایست بر اساس نمونه زیر تکمیل و ارسال گردد.

Header:

header = {

‘Content-Type’: ‘application/json ; charset=utf-8’,

‘Authorization’ : “Bearer ” + token

}

Body:

[

{

“stuffCode”: “string”,

“commodityCode”: “string”,

“stuffTitle”: “string”,

“type”: “string”,

“specialOrGeneral”: “string”,

“taxableOrFree”: “string”,

“defaultTaxPercent”: 0,

“defaultBaseUnitTypeCode”: 0,

“title”: “string”

}

]

در جدول زیر توضیحاتی در رابطه با فیلدهای موجود در json ثبت کالا/خدمات ارائه شده است.

توضیحات	اجباری/اختیاری	فیلد
شناسه 13رقمی کالا و خدمات که از وزارت صمت یا آدرس اینترنتی stuffid.tax.gov.ir دریافت شده است. در صورت اخذ شناسه اختصاصی کالا/خدمت، همان درج شود و در غیر اینصورت شناسه عمومی کالا/ خدمت ثبت گردد.	اجباری	stuffCode
کدی که شرکت در صورتحساب‌های خود از آن استفاده می‌کند که منحصربه فرد است. (ایرانکد، IRC، GTIN، کدینگ داخلی و …)	اجباری	commodityCode
شرح عمومی کالا/خدمت که از وزارت صمت یا آدرس اینترنتی stuffid.tax.gov.ir دریافت شده است. دریافت شده است.	اجباری	stuffTitle
شناسه عمومی وارداتی یا تولید داخل	اختیاری	type
عمومی یا اختصاصی	اختیاری	specialOrGeneral
مشمول یا غیر مشمول بودن کالا ها با درج کلمه مشمول و یا غیر مشمول صورت میگیرد	اختیاری	taxableOrFree
مقدار نرخ مالیات کالا/خدمات در سامانه به‌صورت پیش‌فرض قرارداده می‌شود.	اختیاری	defaultTaxPercent
این کد متناسب با کدهای موجود در سامانه و تایید شده مالیات تکمیل می گردد.	اختیاری	defaultBaseUnitTypeCode
نام کالا یا خدمتی که در سیستم حسابداری مؤدی اعتبار داشته و بر اساس آن برای خریدار صورتحساب صادر می‌شود. به عبارت دیگر شرحی که فروشنده مایل است خریدار آن را در صورتحساب صادره شده ببیند.	اجباری	title

قالب خروجی نتیجه دریافت اطلاعات کالا/خدمت

قالب خروجی نتیجه دریافت اطلاعات به صورت جیسون شامل موارد زیر است:

ناموفق:

{

“data”: [

{

“rowIndex”: 0,

“status”: 1,

“commodityCode”: “string”,

“description”: “string”,

“title”: “string”

}

“error”: false

}

موفق:

{

“data”: [

{

“rowIndex”: 0,

“status”: 3,

“commodityCode”: “string”,

“description”: “کالا / خدمات ثبت شد.”,

“title”: “string”

}

“error”: false

}

به ازای هر قلم کالا که ثبت شود، مطابق کد بالا در قسمت دیتا اطلاعات مربوطه برگردانده می‌شود؛ که مقادیر آن در جدول زیر آمده است:

فیلد	عنوان فیلد	توضیح
error	خطا دارد یا خیر؟	False: خطا ندارد True: خطا دارد
message	پیام‌های سیستمی	پیام‌های سیستمی را نمایش می‌دهد.
description	توضیح	پیام ثبت موفق یا عدم ثبت کالا/خدمت
CommodityCode	شناسه داخلی کالا/خدمت	کدی که شرکت در صورتحساب‌های خود از آن استفاده می‌کند که منحصربه فرد است. (ایرانکد، IRC، GTIN، کدینگ داخلی و …)

استعلام صورتحساب‌های ثبت‌شده

جهت استعلام صورتحساب‌های ثبت شده می‌توان از روش‌های زیر استفاده نمود:

استعلام بر اساس شماره منحصربه‌فرد مالیاتی TaxSerialNumber

کاربران می‌توانند جهت استعلام صورتحساب‌های ثبت‌شده در سامانه کیسان، از طریق URL زیر اقدام نموده و وضعیت صورتحساب خود را مشاهده نمایند:

[server-url] /taxpayer/ api/InvoiceExternalService_v6/InquiryByTaxSerialNumber

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

Header:

{

‘Content-Type’: ‘application/json ; charset=utf-8’,

‘Authorization’ : “Bearer ” + token

}

Body:

data = [“XXXXXXXXXXXXXXXXXXXXXX” ]

استعلام بر اساس شماره رهگیری صورتحساب TrackingId

[server-url] /taxpayer/ api/InvoiceExternalService_v6/ InquiryByTrackId

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

Header:

{

‘Content-Type’: ‘application/json ; charset=utf-8’,

‘Authorization’ : “Bearer ” + token }

Body:

data = [“8b8a3877-xxxx-xxxx-xxxx-ec5d599dfab9” ]

استعلام بر اساس شماره منحصربه‌فرد ایجاد شده توسط کاربر UniqueId

کاربران می‌توانند جهت استعلام صورتحساب‌های ثبت‌شده در سامانه کیسان، طریق URL زیر اقدام نموده و وضعیت صورتحساب خود را مشاهده نمایند:

[server-url] /taxpayer/ api/InvoiceExternalService_v6/ InquiryByUniqueId

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

Header:

{

‘Content-Type’: ‘application/json ; charset=utf-8’,

‘Authorization’ : “Bearer ” + token

}

Body:

data = [ “8b8a3877-xxxx-xxxx-xxxx-ec5d599dfab9” ]

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

{

“data”: [

{

“uniqueId”: “dd1353fe-xxxx-xxxx-xxxx-ac86ece83870”,

“trackingId”: “60a2b1be-xxxx-xxxx-xxxx-d5eb699ff619”,

“taxSerialNumber”: “A1112ExxxxB00000012900”,

“statusCode”: 18,

“statusTitle”: “صورتحساب های نیازمند بررسی”

{

“trackingId”: “b0283ecd–xxxx-xxxx-xxxx-0e369e7137eb”,

“taxSerialNumber”: “A1112xxxx2C00000012976”,

“statusCode”: 18,

“statusTitle “: “صورتحساب های نیازمند بررسی”

{

“uniqueId”: “ee847da1-xxxx-xxxx-xxxx-8e7403523108”,

“trackingId”: “b7b13c73-0483-459d-8240-e5d040008a78”,

“taxSerialNumber”: “A1112xxxx2C00000012994”,

“statusCode”: 14,

“statusTitle”: ” درج در کارپوشه “

}

“error”: false,

“succeeded”: true

}

حذف صورتحساب (با استفاده از UniqueId)

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

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

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

[server-url] /taxpayer/api/InvoiceExternalService_v6/DeleteByUniqueId

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

Header:

{

‘Content-Type’: ‘application/json ; charset=utf-8’,

‘Authorization’ : “Bearer ” + token }

Body:

data = [ “32bacb66-xxxx-xxxx-xxxx-8bb5e84e631e”]

نمونه نتیجه دریافت شده پس از حذف موفقیت‌آمیز صورتحساب

Result:

{

“data”: [

{

“status”: 3,

“uniqueId”: “32bacb66-xxxx-xxxx-xxxx-8bb5e84e631e”,

“description”: “صورتحساب حذف شد.”,

“title”: “”

}

“error”: false,

“succeeded”: true

}

ابطال

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

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

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

[server-url] /taxpayer/ api/InvoiceExternalService_v6/InvoiceRevok

نمونه قالب ورودی اطلاعات جهت ابطال صورتحساب به صورت زیر است:

Header:

{

‘Content-Type’: ‘application/json ; charset=utf-8’,

‘Authorization’ : “Bearer ” + token

}

Body:

[

{

“uniqueId”: “3fa85f64-5717-4562-b3fc-2c963f66afa6”,

“invoiceNumber”: “string”,

“invoiceDate”: “2024-05-28T13:54:23.120Z”,

“invoiceTime”: “string”,

“referenceTaxSerialNumber”: “string”,

“description”: “string”

}

]

نمونه خروجی ابطال صورتحساب:

در این نمونه ابطال صورتحساب با موفقیت انجام پذیرفته است.

{

“data”:[

{

“status”: 3,

“uniqueId”: “a821dc5c-xxxx-xxxx-xxxx-0d9d88534c4d”,

“trakingId”: “f7c5d29b-xxxx-xxxx-xxxx-177cfea2144b”,

“taxSerialNumber”: “A1112xxxx2F00000096418”,

“description”:””,

“title”:””

}

“error”: false,

}

گزارش سرجمع صورتحساب‌‌های ارسالی

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

[server-url] /taxpayer/api/InvoiceExternalService_v6/InvoiceTotallyExport

اطلاعات گزارش موردنظر می‌بایست بر اساس مقادیر تکمیل و ارسال گردد.

Header:

{

‘Content-Type’: ‘application/json ; charset=utf-8’,

‘Authorization’ : “Bearer ” + token

}

Body:

{

“fromInvoiceDate”: “2024-05-28T13:57:13.882Z”,

“toInvoiceDate”: “2024-05-28T13:57:13.882Z”,

“taxSerialNumber”: “string”,

“invoiceNumber”: “string”,

“fromCreateDate”: “2024-05-28T13:57:13.882Z”,

“toCreateDate”: “2024-05-28T13:57:13.882Z”,

“PeymentType”: null,

“InvoiceType”: null,

“InvoicePattern”: null,

“InvoiceSubject”: null,

“buyerNationalCode”: “string”,

“statusCode”: null,

“customsDeclarationCottageDate”: “2024-05-28T13:57:13.882Z”,

“customsDeclarationCottageNumber”: “string”,

“saleType”: null,

“referenceTaxSerialNumber”: “string”

}

در جدول زیر توضیحاتی در رابطه با فیلدهای موجود در json دریافت گزارش صورتحساب‌ها ارائه شده است.

توضیحات	اجباری/اختیاری	فیلد
تاریخ شروع صدور صورتحساب (میلادی)	اجباری	FromInvoiceDate
تاریخ پایان صدور صورتحساب (میلادی)	اجباری	ToInvoiceDate
شماره 22 کاراکتری منحصربه‌فرد مالیاتی	اختیاری	TaxSerialNumber
شماره صورتحساب داخلی	اختیاری	InvoiceNumber
تاریخ شروع ثبت صورتحساب در پایانه فروشگاهی کیسان (میلادی)	اختیاری	FromCreateDate
تاریخ پایان ثبت صورتحساب در پایانه فروشگاهی کیسان (میلادی)	اختیاری	ToCreateDate
روش تسویه(لیست شماره 3)	اختیاری	PeymentType
نوع صورتحساب: (لیست شماره4)	اختیاری	InvoiceType
الگوی صورتحساب(لیست شماره5)	اختیاری	InvoicePattern
موضوع صورتحساب(لیست شماره6)	اختیاری	InvoiceSubject
وضعیت صورتحساب در پایانه فروشگاهی کیسان(لیست شماره 7)	اختیاری	statusCode
تاریخ کوتاژ اظهارنامه گمرکی (میلادی)	اختیاری	CustomsDeclarationCottageDate
شماره کوتاژ اظهارنامه گمرکی (میلادی)	اختیاری	CustomsDeclarationCottageNumber
نوع انجام معامله: 1. غیر بورسی 2. بورس کالا 3. بورس انرژی 4. گواهی سپرده کالا	اختیاری	saleType
شماره 22 کاراکتری منحصربه‌فرد مالیاتی صورتحساب مرجع	اختیاری	referenceTaxSerialNumber

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

قالب خروجی نتیجه دریافت اطلاعات به صورت جیسون شامل موارد زیر است:

{

“data”: [

{

“discount”: 0.0,

“tax17”: 0.0,

“otherDutyAmount”: 0.0,

“otherLegalFundsPrice”: 0.0,

“countInvoiceItem”: 0,

“countInvoice”: 0,

“finalPrice”: 0.0,

“unitPrice”: 0.0,

“amount”: 0.0,

“taxPrice”: 0.0,

“dutyPrice”: 0.0,

“constructionWages”: 0.0,

“saleProfit”: 0.0,

“brokerCommission”: 0.0,

“totalPrice”: 0.0,

“totalPriceWithDiscount”: 0.0

}

“error”: false

}

گزارش صورتحساب‌های خرید

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

[server-url] /taxpayer/api/InvoiceExternalService_v6/InvoiceBuyerExport

.اطلاعات گزارش موردنظر می‌بایست بر اساس مقادیر تکمیل و ارسال گردد

Header:

{

‘Content-Type’: ‘application/json ; charset=utf-8’,

‘Authorization’ : “Bearer ” + token

}

Body:

[

{

“FromInvoiceDate”: “0000-00-00”,

“ToInvoiceDate”: “0000-00-00”,

“TaxSerialNumber”: null,

“InvoiceNumber”: null,

“FromCreateDate”: null,

“ToCreateDate”: null,

“PeymentType”: null,

“InvoiceType”: null,

“InvoicePattern”: null,

“InvoiceSubject”: null,

“selleNationalCode”: “string”,

“statusCode”: null,

“CustomsDeclarationCottageDate”: null,

“CustomsDeclarationCottageNumber”: null,

“saleType”: null,

“referenceTaxSerialNumber”: null

}

]

در جدول زیر توضیحاتی در رابطه با فیلدهای موجود در json دریافت گزارش صورتحساب‌های خرید ارائه شده است.

توضیحات	اجباری/اختیاری	فیلد
تاریخ شروع صدور صورتحساب (میلادی)	اجباری	FromInvoiceDate
تاریخ پایان صدور صورتحساب (میلادی)	اجباری	ToInvoiceDate
شماره 22 کاراکتری منحصربه‌فرد مالیاتی	اختیاری	TaxSerialNumber
شماره صورتحساب داخلی	اختیاری	InvoiceNumber
تاریخ شروع ثبت صورتحساب در پایانه فروشگاهی کیسان (میلادی)	اختیاری	FromCreateDate
تاریخ پایان ثبت صورتحساب در پایانه فروشگاهی کیسان (میلادی)	اختیاری	ToCreateDate
روش تسویه(لیست شماره3)	اختیاری	PeymentType
نوع صورتحساب: (لیست شماره4)	اختیاری	InvoiceType
الگوی صورتحساب(لیست شماره 5)	اختیاری	InvoicePattern
موضوع صورتحساب)لیست شماره 6)	اختیاری	InvoiceSubject
وضعیت صورتحساب در پایانه فروشگاهی کیسان(لیست شماره 7)	اختیاری	statusCode
تاریخ کوتاژ اظهارنامه گمرکی (میلادی)	اختیاری	CustomsDeclarationCottageDate
شماره کوتاژ اظهارنامه گمرکی (میلادی)	اختیاری	CustomsDeclarationCottageNumber
نوع انجام معامله(لیست شماره 8)	اختیاری	saleType
شماره 22 کاراکتری منحصربه‌فرد مالیاتی صورتحساب مرجع	اختیاری	referenceTaxSerialNumber

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

قالب خروجی نتیجه دریافت اطلاعات به صورت جیسون شامل موارد زیر است:

}

“taxSerialNumber”: “xxxxxxxxxxxxxxxxxxxxxx”,

“invoiceNumber”: “api-14020325-1”,

“invoiceDate”: “0000-00-00”,

“InvoiceTypeTitle”: “نوع۱”,

“InvoiceTypeCode”: 1,

“InvoicePatternTitle”: “فروش (همراه با اطلاعات خریدار)”,

“sellerUserFullName”: “test”,

“sellerUserCompanyName”: ” test2″,

“buyerUserNationalCode”: “022222222”,

“buyerUserFullName”: “test3”,

“buyerUserCompanyName”: “test4 “,

“BuyerTypeTitle”: “حقیقی”,

“BuyerTypeCode”: 1,

“StatusCode”: 14,

“StatusTitle”: “درج در کارپوشه”,

“createdDate”: “1402/03/30”,

“SaleTypeTitle”: “غیر بورس”,

“SaleTypeCode”: 1,

“invoiceItems”: “”,

“invoiceNumber”: “api-14020325-1”,

“invoiceDate”: “1402/03/25”,

“commodityCode”: “3”,

“stuffTitle”: “stufftest-21”,

“UnitTypeTitle”: “نامشخص”,

“UnitTypeCode”: -1,

“MoneyTypeTitle”: “دلار آمریکا”,

“MoneyTypeCode”: 840,

“SaleTypeTitle”: “عادی”,

“SaleTypeCode”: 1,

“amount”: 0,

“unitPrice”: 0,

“equivalentToRial”: 0,

“taxPercent”: 0,

“taxPrice”: 0,

“dutyPercent”: 0,

“dutyPrice”: 0,

“otherLegalFundsPercent”: 0,

“otherLegalFundsPrice”: 0,

“constructionWages”: 0,

“saleProfit”: 0,

“brokerCommission”: 0,

“discount”: 0,

“totalPrice”: 0,

“totalPriceWithDiscount”: 0,

“finalPrice”: 0,

“totlaTaxDutyPrice InvoicePatternCode”: 1,

“InvoiceSubjectTitle”: “اصلی”,

“InvoiceSubjectCode”: 1,

“sellerUserNationalCode”: “0”

}

استعلام خریدار

جهت استعلام خریداران، می‌توان از URL زیر جهت اتصال به وب‌سرویس استفاده نمود:

[server-url] /identity/api/Service/InquiryBuyerCollaboration

اطلاعات گزارش موردنظر می‌بایست بر اساس مقادیر تکمیل و ارسال گردد.

Header:

{

‘Content-Type’: ‘application/json ; charset=utf-8’,

‘Authorization’ : “Bearer ” + token

}

Body:

{

“type”: “1”,

“nationalcode”: “0081914385”,

“postalcode”: “1714864881”,

“economiccode”: “00819143850001”

}

قالب خروجی نتیجه استعلام خریدار

قالب خروجی نتیجه دریافت اطلاعات به صورت جیسون شامل موارد زیر است:

{

“data”: {

“user”: {

“type”: “2”,

“nationalCode”: “XXXXXXXXXX”,

“economicCode”: ” XXXXXXXXXX “,

“postalCode”: “YYYYYYYYYY”,

“firstName”: “test1”,

“lastName”: “test2”,

“companyName”: “Test3”

“userContainerId”: “c40c004d-ZZZZ-XXXX-a3c2-2101a5bfcaf2”,

“isActive”: true

“error”: false,

}

استعلام وضعیت شناسه کالا/خدمت

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

[server-url] /identity/api/Service/InquiryByCommodityCode

Header:

{

‘Content-Type’: ‘application/json ; charset=utf-8’,

‘Authorization’ : “Bearer ” + token

}

Body:

Data=[“1”, “52102”, “100845215457”]

1. قالب خروجی نتیجه استعلام کالا/خدمت

قالب خروجی نتیجه دریافت اطلاعات به صورت جیسون شامل موارد زیر است:

{

“data”: [

{

“commodityCode”: “1”,

“stuffCod”: ” xxxxxxxxxxxxx “,

“stuffTitle”: “اy”,

“defaultTaxPercent”: 0,

“title”: “y”,

“isExistsStuff”: true,

“isActive”: true,

“description”: “string”

{

“commodityCode”: “52102”,

“stuffCod”: “xxxxxxxxxxxxx”,

“stuffTitle”: ” string “,

“defaultTaxPercent”: 9,

“title”: ” string “,

“isExistsStuff”: true,

“isActive”: true,

“description”: ” string “

{

“commodityCode”: “100845215457”,

“description”: “این شناسه کالا /خدمات در لیست کالا خدمات کاربر وجود ندارد”

}

“error”: false,

“succeeded”: true

}

ویرایش صورتحساب

صورتحساب‌هایی قابل ویرایش هستند که هنوز به مالیات ارسال نشده‌اند و در واقع وضعیت آن‌ها 1، 2، 3، 4 و 18 است. جهت ویرایش صورتحساب از آدرس زیر استفاده شود. لازم به ذکر است، قالب ورودی اطلاعات تفاوتی با قالب ارسال صورتحساب نداشته و فقط فیلد «IsUpdate» در Header اضافه شده که مقدار آن، «True» و «False» بوده و نمایانگر ویرایش و یا عدم ویرایش صورتحساب است.

URL سرویس ویرایش صورتحساب:

[server-url] /taxpayer/api/InvoiceExternalService_v6

قالب ورودی اطلاعات به صورت جیسون بر اساس نمونه تکمیل‌شده شامل موارد زیر است:

Header:

{

‘Content-Type’: ‘application/json ; charset=utf-8’,

‘Authorization’ : “Bearer ” + token

}

Body:

[ {

“invoiceNumber”: “string”,

“invoiceDate”: “2024-05-28T14:04:26.141Z”,

“invoiceTime”: “string”,

“saleType”: 0,

“referenceTaxSerialNumber”: “string”,

“invoicePattern”: 0,

“invoiceType”: 0,

“invoiceSubject”: 0,

“paymentType”: 0,

“uniqueId”: “3fa85f64-5717-4562-b3fc-2c963f66afa6”,

“sellerBranch”: “string”,

“buyerType”: 0,

“buyerCompanyName”: “string”,

“buyerFirstName”: “string”,

“buyerLastName”: “string”,

“buyerNationalCode”: “string”,

“buyerEconomicCode”: “string”,

“buyerPassportNumber”: “string”,

“buyerPostalCode”: “string”,

“buyerBranch”: “string”,

“buyerPhoneNumber”: “string”,

“sellerCustomsDeclarationNumber”: “string”,

“sellerCustomsLicenseNumber”: “string”,

“sellerContractRegistrationNumber”: “string”,

“flightType”: 0,

“creditPaymentAmount”: 0,

“passengerNationalCode”: “string”,

“passengerPassportNumber”: “string”,

“billId”: “string”,

“tax17”: 0,

“customsDeclarationCottageNumber”: “string”,

“customsDeclarationCottageDate”: “2024-05-28T14:04:26.141Z”,

“cooperationCode”: “string”,

“description”: “string”,

“isUpdate”: true,

“invoiceItems ” : [ {

“commodityCode”: “string”,

“extendStuffTitle”: “string”,

“amount”: 0,

“unitType”: 0,

“moneyType”: 0,

“equivalentToRial”: 0,

“unitPrice”: 0,

“discount”: 0,

“taxPercent”: 0,

“taxPrice”: 0,

“dutyPercent”: 0,

“dutyPrice”: 0,

“dutyTitle”: “string”,

“exchangeContractNumber”: “string”,

“exchangeContractDate”: “2024-05-28T14:04:26.141Z”,

“currencyAmount”: 0,

“otherLegalFundsTitle”: “string”,

“otherLegalFundsPercent”: 0,

“otherLegalFundsPrice”: 0,

“constructionWages”: 0,

“saleProfit”: 0,

“brokerCommission”: 0,

“brokerContractNumber”: “string”,

“netWeight”: 0,

“stuffIRRValue”: 0,

“stuffCurrencyValue”: 0,

“purchaseSalePriceDifference”: 0,

“cutie”: 0,

“agencyEconomicCode”: “string”

} ],

“invoicePayments”: [ {

“paymentMethod”: 0,

“paymentAmount”: 0,

“paymentDate”: “2024-05-28T14:04:26.141Z”,

“switchNumber”: “string”,

“acceptanceNumber”: “string”,

“terminalNumber”: “string”,

“traceNumber”: “string”,

“payerCardNumber”: “string”,

“payerNationalCode”: “string”

} ]

گزارش استعلام جزئیات صورتحساب

جهت دریافت جزئیات صورتحساب‌های ارسالی به پایانه فروشگاهی کیسان می‌توان از URL زیر جهت اتصال به وب‌سرویس استفاده نمود:

[server-url] /taxpayer/api/InvoiceExternalService_v6/ReportInvoice

اطلاعات گزارش موردنظر می‌بایست بر اساس مقادیر تکمیل و ارسال گردد.

Header:

{

‘Content-Type’: ‘application/json ; charset=utf-8’,

‘Authorization’ : “Bearer ” + token

}

Body:

[

{

“TaxSerialNumber”: “string”,

“uniqueId”: “string”,

” trakingid”: “string”

}

]

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

قالب خروجی نتیجه دریافت اطلاعات به صورت جیسون شامل موارد زیر است:

{

“data”: [

{

“taxSerialNumber”: “xxxxxxxxxxxxxxxxxxxx”,

“UniqueId”: “*******-****-****-****-b3470db6135e”,

“trackingId”: “*******-****-****-****-eb9e203cca8f”,

“invoiceNumber”: “string”,

“invoiceDate”: “string”,

“InvoiceTypeTitle”: “نوع۲”,

“InvoiceTypeCode”: 2,

“InvoicePatternTitle”: “فروش (بدون اطلاعات خریدار)”,

“InvoicePatternCode”: 1,

“InvoiceSubjectTitle”: “اصلی”,

“InvoiceSubjectCode”: 1,

“sellerUserNationalCode”: “xxxxxxxxx”,

“sellerUserFullName”: “string “,

“sellerUserCompanyName”: “string”,

“buyerUserNationalCode”: “xxxxxxxxx”,

“buyerUserFullName”: “string”,

“BuyerTypeTitle”: “حقیقی”,

“BuyerTypeCode”: 1,

“StatusCode”: 9,

“StatusTitle”: “در صف استعلام از مالیات”,

“createdDate”: “string”,

“SaleTypeTitle”: “عادی”,

“SaleTypeCode”: 1,

“PaymentType”: “نقدی”,

“invoiceItems”: [

{

“invoiceNumber”: “string”,

“invoiceDate”: “1403/03/22”,

“commodityCode”: “xxxxxxxxxxxx”,

“stuffTitle”: ” string”,

“UnitTypeTitle”: “string”,

“UnitTypeCode”: 1638,

“MoneyTypeTitle”: “ریال”,

“MoneyTypeCode”: 364,

“SaleTypeTitle”: “-“,

“SaleTypeCode”: 1,

“amount”: 0.0,

“unitPrice”: 0.0,

“equivalentToRial”: 0.0,

“taxPercent”: 0.0,

“taxPrice”: 0.0,

“dutyPercent”: 0.0,

“dutyPrice”: 0.0,

“otherLegalFundsPercent”: 0.0,

“otherLegalFundsPrice”: 0.0,

“constructionWages”: 0.0,

“saleProfit”: 0.0,

“brokerCommission”: 0.0,

“discount”: 0.0,

“totalPrice”: 0.0,

“totalPriceWithDiscount”: 0.0,

“finalPrice”: 0.0,

“totlaTaxDutyPrice”: 0.0

}

“invoicePayments”: []

}

“error”: false

}

استعلام صورتحساب از طریق شماره داخلی صورتحساب

بیشترین تعداد درخواست برای هر ارسال 100 می باشد.

[server-url]Taxpayer/ api/InvoiceExternalService_v6/InquiryByInfo

Header:

{

‘Content-Type’: ‘application/json ; charset=utf-8’,

‘Authorization’ : “Bearer ” + token

}

Body:

[

{

“invoiceNumber”: “string”,

“invoiceDate”: “2024-00-00T00:00:00.499Z”,

“subject”: 0 }]

قالب نتیجه استعلام گزارش به صورت زیر می باشد:

{

“data”: [

{

“trackingId”: “ab856df3-4953-4f55-9f07-eecb81112d7f”,

“taxSerialNumber”: “xxxxxxxxxxxxxxxxxxxxx”,

“status”: 3,

“statusTitle”: “تایید صورتحساب توسط فروشنده”,

“invoiceNumber”: “00011”,

“invoiceDate”: “2024-00-00T00:00:00”,

“Subject”: 1

}

“error”: false

}

لیست شماره 1:

BasePaymentCreditTypeCode
روش پرداخت
Code	Title
1	چک
2	تهاتر
3	وجه نقد
4	POS
5	درگاه پرداخت اینترنتی
6	کارت به کارت
7	انتقال به حساب
8	سایر

لیست شماره 2 :

Status
وضعیت استعلام
Code	Title
1	خطا در عدم ثبت شناسه کالا توسط کاربر
2	خطا در ثبت صورتحساب تکراری
3	ثبت موفق صورتحساب

لیست شماره 3:

PeymentType
روش تسویه
Code	Title
1	نقدی
2	نسیه
3	نقدی/نسیه

لیست شماره 4:

InvoiceType
نوع صورتحساب
Code	Title
1	نوع1 (همراه با اطلاعات خریدار)
2	نوع 2 (بدون اطلاعات خریدار)

لیست شماره 5:

InvoicePattern
الگوی صورتحساب
Code	Title
1	فروش (همراه با اطلاعات خریدار)
2	فروش ارز
3	طلا، جواهر و پلاتین (همراه با اطلاعات خریدار)
4	قرارداد پیمانکاری
5	قبوض خدماتی
6	بلیت هواپیما
7	صادرات
21	فروش (بدون اطلاعات خریدار)
23	طلا،جواهر،پلاتین (بدون اطلاعات خریدار)

لیست شماره 6:

InvoiceSubject
موضوع صورتحساب
Code	Title
1	اصلی
2	اصلاحی
3	ابطالی
4	برگشت از فروش

لیست شماره 7:

StatusCode
وضعیت صورتحساب در پایانه فروشگاهی کیسان
Code	Title
1	ثبت اولیه
3	تایید صورتحساب توسط فروشنده
8	درحال ارسال به مالیات
9	در صف استعلام از مالیات
10	در حال بررسی توسط شرکت معتمد
12	درصف انتظار ارسال مجدد به مالیات
14	درج در کارپوشه
15	مرجع صورتحساب – اصلاحی
16	مرجع صورتحساب – برگشت از فروش
17	مرجع صورتحساب – ابطال
18	نیازمند بررسی توسط مودی
19	آرشیو

لیست شماره‌8:

saleType
نوع انجام معامله
Code	Title
1	عادی (مقدار پیش فرض)
2	بورس کالا
3	بورس انرژی
4	گواهی سپرده کالا

لیست شماره 9:

buyerType
نوع خریدار
code	Title
1	حقیقی
2	حقوقی
3	مشارکت مدنی
4	اتباع غیرایرانی

لیست شماره10:

flightType
نوع پرواز
Code	Title
1	داخلی
2	خارجی

لیست شماره 11:

نوع خریدار	شناسه ملی/کد ملی/مشارکت مدنی/اتباع خریدار	کد اقتصادی	کد پستی	شماره گذرنامه	نام	نام خانوادگی	نام شرکت
1	10رقمی باشد (اجباری)	14رقمی باشد (یا این فیلد پر شود یا فیلد کدپستی،اگر هر دو پر بود ترجیح بر کد اقتصادی است)درصورت تکمیل این فیلد،10رقم اول برابر با کد ملی باشد	10رقمی باشد(یا این فیلد را پر کند یا فیلد کد اقتصادی، اگر هر دو پر بود ترجیح بر کد اقتصادی است)	اختیاری	اجباری	اجباری	اختیاری
2	11 رقمی باشد (اجباری)	11رقمی باشد(اجباری)با 1 یا 3شروع شود کد اقتصادی برابر با شناسه ملی است	10رقمی باشد (اختیاری)	اختیاری	اختیاری	اختیاری	اختیاری
3	10 یا 12 رقمی باشد (اجباری)	11رقمی باشد و با 6 شروع شود(اجباری)	10رقمی باشد (اختیاری)	اختیاری	اختیاری	اختیاری	اختیاری
4	12رقمی باشد (اجباری)	14رقمی باشد (یا این فیلد پر شود یا فیلد کد پستی اگر هر دو پر بود ترجیح بر کد اقتصادی است )در صورت تکمیل این فیلد،12رقم اول برابر با کد فراگیر اتباع باشد	10رقمی باشد (یا این فیلد را پر کند یا فیلد کد اقتصادی، اگر هر دو پر بود ترجیح بر کد اقتصادی است)	اختیاری	اجباری	اجباری	اختیاری

نویسنده: بهاره رئیس دانا - کارشناس مدیریت دانش در کیسان

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

نحوه اتصال به نرم‌افزار کیسان از طریق API

نحوه اتصال سرویس خارجی به API

فرآیند دریافت و دسترسی به سرویس‌ها

جزئیات دریافت دسترسی (توکن)

سرویس دریافت توکن دسترسی

سرویس دریافت توکن دسترسی برای کاربرانی که با یک نام کاربری در کیسان چند پرونده مالیاتی دارند

ارسال اطلاعات به سامانه جمع ‌آوری کیسان

تشریح فیلدها

قالب ورودی اطلاعات

قالب خروجی ثبت صورتحساب:

نتیجه دریافت اطلاعات توسط سامانه جمع‌آوری اطلاعات کیسان

قالب خروجی نتیجه دریافت اطلاعات

تشریح نتیجه

ثبت کالا/خدمات

قالب خروجی نتیجه دریافت اطلاعات کالا/خدمت

استعلام صورتحساب‌های ثبت‌شده

حذف صورتحساب (با استفاده از UniqueId)

ابطال

گزارش سرجمع صورتحساب‌‌های ارسالی

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

گزارش صورتحساب‌های خرید

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

استعلام خریدار

قالب خروجی نتیجه استعلام خریدار

استعلام وضعیت شناسه کالا/خدمت

گزارش استعلام جزئیات صورتحساب

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

استعلام صورتحساب از طریق شماره داخلی صورتحساب

دیدگاهتان را بنویسید لغو پاسخ