ارسال صورتحساب با برقراری ارتباط از طریق api به همراه نمونه‌های پر شده

 

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

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

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

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

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

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

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

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

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

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

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

• دريافت توكن

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

• نمونه یک توکن

BearereyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJqdGkiOiIyYzEyZDNjMy1jNTYxLTQ2YTgtOWVjNy1kNGNhZGVhYzQ2OTkiLCJ1aWQiOiIwMWVhNmU1ZS04YzExLTRlZWItYjMwNy1kM2JjYjUxNmRkOTYiLCJ1Y2lkIjoiZWIwYzlhYjktMzk4Zi00NDI4LThhNjgtYWY2Y2EwMWUyOTVkIiwicHVpZCI6IjAxZWE2ZTVlLThjMTEtNGVlYi1iMzA3LWQzYmNiNTE2ZGQ5NiIsInB1Y2lkIjoiZWIwYzlhYjktMzk4Zi00NDI4LThhNjgtYWY2Y2EwMWUyOTVkIiwibmF0aW9uYWxjb2RlIjoiMTExMTExIiwibmFtZSI6ImFkbWluIiwiaXNhZG1pbiI6IlRydWUiLCJicmFuY2hpZCI6IiIsImNvbXBhbnlpZCI6IiIsImV4cCI6MTY0MzQ1NzkxNywiaXNzIjoiV2luZG93TGluay5TZWN1cml0eS5CZWFyZXIiLCJhdWQiOiJXaW5kb3dMaW5rLlNlY3VyaXR5LkJlYXJlci5Vc2VyIn0.rK3tg1p2oxKMsbr9CgV5F_gua3rs5JL59GgEr_8CHyA

تصویر ارسال درخواست و دریافت توکن

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

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

[server-url]/identity/api/servicetoken

• مقادیر ورودی

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

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

• مقادیر خروجی

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

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

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

• توضیحات:

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

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

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

تشریح فیلدها

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

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

اقلام صورتحساب
توضیح	نوع فیلد	نام فیلد
برای کالاها و خدمات این فیلد مقدار 1 می‌گیرد	int	commodityType
قبل از ثبت صورتحساب باید لیست شناسه‌های کالاها یا خدمات خود را در کیسان و در بخش (سرویس‌ها -> کالا/خدمات) ثبت کنید. این فیلد شامل شناسه های داخلی است. توجه مهم: هر کالا یک شناسه 13 رقمی و یک شناسه داخلی دارد که می‌تواند با شناسه 13 رقمی یکسان یا متفاوت باشد. در این ستون مقدار شناسه داخلی قرار می‌گیرد.	string	commodityCode
تعداد یا مقدار کالا یا خدمت مورد معامله است. این فیلد مقادیر اعشاری نیز می‌پذیرد.	decimal	amount
“این فیلد فقط مقدار عددی می‌پذیرد. از فایل کد واحد های اندازه گیری، کد واحد مورد نظر را یافته و در این ستون وارد کنید. نمونه صحیح برای واحد کیلوگرم: 164	int	unitType
این ستون فقط مقدار عددی می‌پذیرد. نوع ارز مورد معامله را نشان می‌دهد. این ستون با کدهای مربوط به iso 4217 تکمیل می‌شود. نمونه صحیح برای ریال ایران: 364 در صورت خالی ماندن این ستون مقدار آن 364 که به معنای ریال ایران است در نظر گرفته می‌شود.	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

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

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

نام فیلد	Latin	جایگاه در صورتحساب	فروش 11	ارزی 12	طلا 13	قرارداد 14	قبض 15	بلیت 16	صادرات 17	فروش 21	طلا 23
تاریخ و زمان صدور صورتحساب (میلادی)	invoiceDate	header
تاریخ و زمان ایجاد صورتحساب (میلادی)	invoiceTime	header
نوع صورتحساب	baseInvoiceTypeId	header
شماره منحصر به فرد مالیاتی صورتحساب مرجع	referenceInvoiceTaxSerialNumber	header
الگوی صورتحساب	baseInvoicePatternId	header
موضوع صورتحساب	baseInvoiceSubjectId	header
نوع انجام معامله	SaleType	header
نوع شخص خریدار	baseBuyerTypeId	header
شناسه ملی/ شماره ملی/ شناسه مشارکت مدنی/ کد فراگیر اتباع غیر ایرانی خریدار	BuyerNationalCode	header
شماره اقتصادی خریدار	BuyerEconomicCode	header
شماره ملی/کد فراگیر اتباع غیر ایرانی مسافر	PassengerNationalCode	header
کد پستی خریدار	BuyerPostalCode	header
نام شرکت خریدار	buyerCompanyName	header
نام خریدار	buyerFirstName	header
نام خانوادگی خریدار	buyerLastName	header
شماره تماس خریدار	buyerPhoneOrMobileNumber	header
کد شعبه خریدار	BuyerBranch	header
نوع پرواز	baseFlightTypeId	header
شماره گذرنامه خریدار	passportNumber	header
شماره پروانه گمرکی فروشنده	sellerCustomsLicenseNumber	header
کد گمرک محل اظهار فروشنده	sellerCustomsDeclarationNumber	header
شماره کوتاژ اظهارنامه گمرکی	CustomsDeclarationCottageNum	header
تاریخ کوتاژ اظهارنامه گمرکی	CustomsDeclarationCottageDate	header
شناسه یکتای ثبت قرارداد فروشنده	sellerContractRegistrationNumber	header
شماره اشتراک /شناسه قبض بهره بردار	BillId	header
روش تسویه	basePaymentTypeId	header
مبلغ نسیه	creditPaymentAmount	header
مالیات موضوع ماده 17	tax17	header
توضیحات	description	header
نوع کالا/خدمت	CommodityType	body
شناسه کالا/خدمت	commodityCode	body
شرح اضافی کالا/ خدمت	ExtendStuffTitle	body
تعداد/مقدار	amount	body
واحد اندازه گیری	baseUnitTypeCode	body
وزن خالص	NetWeight	body
مبلغ واحد	UnitPrice	body
میزان ارز	CurrencyAmount	body
نوع ارز	BaseMoneyTypeISOCode	body
نرخ برابری ارز با ریال	EquivalentToRial	body
ارزش ریالی کالا/ خدمت	StuffIRRValue	body
ارزش ارزی کالا/ خدمت	StuffCurrencyValue	body
مبلغ تخفیف	Discount	body
نرخ مالیات بر ارزش افزوده	taxPercent	body
مبلغ مالیات بر ارزش افزوده	taxPrice	body
موضوع سایر مالیات و عوارض	dutyTitle	body
نرخ سایر مالیات و عوارض	dutyPercent	body
مبلغ سایر مالیات و عوارض	dutyPrice	body
موضوع سایر وجوه قانونی	otherLegalFundsTitle	body
نرخ سایر وجوه قانونی	otherLegalFundsPercent	body
مبلغ سایر وجوه قانونی	otherLegalFundsPrice	body
اجرت ساخت	constructionWages	body
سود فروشنده	saleProfit	body
حق العمل	brokerCommission	body
شماره قرارداد بورسی	exchangeContractNumber	body
تاریخ قرارداد بورسی	exchangeContractDate	body
شناسه یکتای ثبت قرارداد حق العمل کاری	BrokerContractNumber	body
تفاوت نرخ خرید و فروش ارز/کارمزد فروش	PurchaseSalePriceDifference	body
شماره سوئیچ پرداخت	switchNumber	payment
شماره پذیرنده فروشگاهی	acceptanceNumber	payment
شماره پایانه	terminalNumber	payment
روش پرداخت	BasePaymentCreditTypeCode	payment
شماره پیگیری	TraceNumber	payment
شماره کارت پرداخت کننده صورتحساب	payerCardNumber	payment
شماره/شناسه ملی/کد فراگیر پرداخت کننده صورتحساب	PayerNationalCode	payment
تاریخ و زمان پرداخت صورتحساب	PaymentDate	payment
مبلغ پرداختی	PaymentAmount	payment
				اجباری		اختیاری		خاص		ignore

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

• URL سرویس ثبت صورتحساب:

[server-url] /taxpayer/api/InvoiceExternalService_v6

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

Header:

header = {

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

‘Authorization’ : “Bearer ” + token

}

Body:

[

{

“invoiceNumber”: “api-doller22”,

“invoiceDate”: “2023-05-22T10:00:00”,

“invoiceTime”: None,

“saleType”: 1,

“referenceTaxSerialNumber”: None,

“invoiceType”: 1,

“invoicePattern”: 2,

“invoiceSubject”: 1,

“paymentType”: 1,

“uniqueId”:“uniqeId”,

“SellerBranch”:None,

“BuyerBranch “:None,

“buyerType”: 1,

“buyerCompanyName”: None,

“buyerFirstName”: “نام”,

“buyerLastName”: “نام خانوادگی”,

“buyerNationalCode”: “000000000000”,

“buyerEconomicCode”: None,

“buyerPassportNumber”: None,

“buyerPostalCode”: “0000000000”,

“buyerPhoneNumber”: “00000000000” ,

“sellerCustomsDeclarationNumber”: None,

“sellerCustomsLicenseNumber”: None,

“sellerContractRegistrationNumber”: None,

“flightType”: 0,

“PassengerNationalCode”: “0000000000”,

“creditPaymentAmount”:0.0,

“billId”: None,

“tax17”: None,

“CustomsDeclarationCottageNumber”: None,

“CustomsDeclarationCottageDate”:None,

“CooperationCode”: “coptest1234”,

“description”: None,

“invoiceItems”: [

{

“commodityType”: 2,

“ExtendStuffTitle”: “12-1566/1”,

“commodityCode”: “99300”,

“amount”: 100.0,

“unitType”: 1627,

“moneyType”: 840,

“equivalentToRial”: 400000.0,

“unitPrice”:1000.0,

“discount”: 0,

“taxPercent”: 9.0,

“taxPrice”: 0,

“dutyPercent”: 0.0,

“dutyPrice”: 0.0,

“dutyTitle”: None,

“ExchangeContractNumber”: None,

“exchangeContractDate”: None,

“currencyAmount”: 0.0,

“otherLegalFundsTitle”: None,

“otherLegalFundsPercent”: 0.0,

“otherLegalFundsPrice”: 0.0,

“constructionWages”: 0.0,

“saleProfit”: 0.0,

“brokerCommission”: 0.0,

“brokerContractNumber”: None,

“NetWeight”:0.0,

“StuffCurrencyValue” : 0.0,

“PurchaseSalePriceDifference”:0.0

}],

“invoicePayments”: [

{

“paymentAmount”:49050000,

“paymentMethod”:4.0,

“paymentDate”: “2023-01-15T00:00:00”,

“switchNumber”: None,

“acceptanceNumber”: None,

“terminalNumber”: None,

“traceNumber”: None,

“payerCardNumber”: None,

“payerNationalCode”: None }], } ]

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

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

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

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

{

“status”: int,

“uniqueId”: string

“commodityCode”: string,

“TaxSerialNumber”: string,

“TrackingId”: string,

“description”: string,

“title”: string

}

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

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

تشریح نتیجه

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

1. خطا در عدم ثبت شناسه کالا توسط کاربر

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

{

“status”: 1,

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

“commodityCode”: “0831100692420001”,

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

“title”: “CommodityCode”

}

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

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

{

“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”: “string”,

“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

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

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

{

“error”: bool,

“message”: string,

“traceId”: string,

“data”:[{

“description”: string,

“CommodityCode”: string

}]

}

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

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

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

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

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

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

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

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

Header:

header = {

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

‘Authorization’ : “Bearer ” + token

}

Body:

data = [

“XXXXXXXXXXXXXXXXXXXXXX”

]

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

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

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

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

Header:

header = {

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

‘Authorization’ : “Bearer ” + token

}

Body:

data = [

“8b8a3877-xxxx-xxxx-xxxx-ec5d599dfab9”

]

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

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

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

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

Header:

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:

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”: uuid.uuid4,

“InvoiceNumber”: “ebtaliAPI705d”,

“InvoiceDate”: “2023-05-08”,

“invoiceType”: 2,

“invoicePattern”: 1,

“invoiceSubject”: 3,

“ReferenceTaxSerialNumber”: “A1112D0xxxx0000008C377”,

“Description”: “ebtal”

},

]

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

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

{

“data”: [

{

“status”: 3,

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

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

“taxSerialNumber”: “A1112xxxx2F00000096418”,

“description”: “”,

“title”: “”

}

],

“error”: false,

“succeeded”: true

}

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

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

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

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

Header:

header = {

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

‘Authorization’ : “Bearer ” + token

}

Body:

{

“FromInvoiceDate” : “2023-06-15”,

“ToInvoiceDate” : “2023-06-30”,

“TaxSerialNumber”: null,

“InvoiceNumber”: null,

“FromCreateDate”: null,

“ToCreateDate”: null,

“PeymentType”: null,

“InvoiceType”: null,

“InvoicePattern”: null,

“InvoiceSubject”: null,

“statusCode”: null,

“CustomsDeclarationCottageDate”: null,

“CustomsDeclarationCottageNumber”: null,

“saleType”: null,

“referenceTaxSerialNumber”:null

}

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

توضیحات	اجباری/اختیاری	فیلد
تاریخ شروع صدور صورتحساب (میلادی)	اجباری	FromInvoiceDate
تاریخ پایان صدور صورتحساب (میلادی)	اجباری	ToInvoiceDate
شماره 22 کاراکتری منحصربه‌فرد مالیاتی	اختیاری	TaxSerialNumber
شماره صورتحساب داخلی	اختیاری	InvoiceNumber
تاریخ شروع ثبت صورتحساب در پایانه فروشگاهی کیسان (میلادی)	اختیاری	FromCreateDate
تاریخ پایان ثبت صورتحساب در پایانه فروشگاهی کیسان (میلادی)	اختیاری	ToCreateDate
روش تسویه: 1. نقدی 2. نسیه 3. نقدی/نسیه	اختیاری	PeymentType
نوع صورتحساب: 1. همراه با اطلاعات خریدار 2. بدون اطلاعات خریدار	اختیاری	InvoiceType
الگوی صورتحساب: 1. فروش (همراه با اطلاعات خریدار) 2. فروش ارز 3. طلا، جواهر و پلاتین (همراه با اطلاعات خریدار) 4. قرارداد پیمانکاری5. قبوض خدماتی 6. بلیت هواپیما 7. صادرات 1. فروش (بدون اطلاعات خریدار) 3. طلا، جواهر و پلاتین (بدون اطلاعات خریدار)	اختیاری	InvoicePattern
موضوع صورتحساب: 1. اصلی 2. اصلاحی 3. ابطالی 4. برگشت از فروش	اختیاری	InvoiceSubject
وضعیت صورتحساب در پایانه فروشگاهی کیسان: 1. ثبت اولیه 2. ویرایش بدون تایید 3. تایید صورتحساب توسط فروشنده 4. لغو تایید صورتحساب توسط فروشنده 8. درحال ارسال به مالیات 9. در صف استعلام از مالیات 10. در حال بررسی توسط شرکت معتمد 11. در انتظار رفع خطا 12. درصف انتظار ارسال مجدد به مالیات 13. این شرکت معتمد مجاز به ارسال برای این حافظه نمی باشد 14. دریافت کد رهگیری 15. مرجع صورتحساب – اصلاحی 16. مرجع صورتحساب – برگشت از فروش 17. مرجع صورتحساب – ابطال 18. نیازمند بررسی توسط مودی 19. در انتظار رفع خطای مجدد 100. حذف	اختیاری	statusCode
تاریخ کوتاژ اظهارنامه گمرکی (میلادی)	اختیاری	CustomsDeclarationCottageDate
شماره کوتاژ اظهارنامه گمرکی (میلادی)	اختیاری	CustomsDeclarationCottageNumber
نوع انجام معامله: 1. غیر بورسی 2. بورس کالا 3. بورس انرژی 4. گواهی سپرده کالا	اختیاری	saleType
شماره 22 کاراکتری منحصربه‌فرد مالیاتی صورتحساب مرجع	اختیاری	referenceTaxSerialNumber

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

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

{

“data”: [

{

“discount”: 0.000000000000,

“tax17”: 0.000000000000,

“otherDutyAmount”: 0.000000000000,

“otherLegalFundsPrice”: 0.000000000000,

“countInvoiceItem”: 72,

“countInvoice”: 49,

“finalPrice”: 1640720405587.212000000000,

“unitPrice”: 1604508062330.500000000000,

“amount”: 69053.905677000000,

“taxPrice”: 346446054.050000000000,

“dutyPrice”: 0.000000000000,

“constructionWages”: 0.000000000000,

“saleProfit”: 0.000000000000,

“brokerCommission”: 0.000000000000,

“totalPrice”: 1640473346321.162000000000,

“totalPriceWithDiscount”: 1640373959533.162000000000

}

],

“error”: false,

“succeeded”: true

}

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

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

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

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

Header:

header = {

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

‘Authorization’ : “Bearer ” + token

}

Body:

[

}

“FromInvoiceDate” : “2023-06-15”,

“ToInvoiceDate” : “2023-06-30”,

“TaxSerialNumber”: null,

“InvoiceNumber”: null,

“FromCreateDate”: null,

“ToCreateDate”: null,

“PeymentType”: null,

“InvoiceType”: null,

“InvoicePattern”: null,

“InvoiceSubject”: null,

“statusCode”: null,

“CustomsDeclarationCottageDate”: null,

“CustomsDeclarationCottageNumber”: null,

“saleType”: null,

“referenceTaxSerialNumber”:null

}

]

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

توضیحات	اجباری/اختیاری	فیلد
تاریخ شروع صدور صورتحساب (میلادی)	اجباری	FromInvoiceDate
تاریخ پایان صدور صورتحساب (میلادی)	اجباری	ToInvoiceDate
شماره 22 کاراکتری منحصربه‌فرد مالیاتی	اختیاری	TaxSerialNumber
شماره صورتحساب داخلی	اختیاری	InvoiceNumber
تاریخ شروع ثبت صورتحساب در پایانه فروشگاهی کیسان (میلادی)	اختیاری	FromCreateDate
تاریخ پایان ثبت صورتحساب در پایانه فروشگاهی کیسان (میلادی)	اختیاری	ToCreateDate
روش تسویه: 1. نقدی 2. نسیه 3. نقدی/نسیه	اختیاری	PeymentType
نوع صورتحساب: 1. همراه با اطلاعات خریدار 2. بدون اطلاعات خریدار	اختیاری	InvoiceType
الگوی صورتحساب: 1. فروش (همراه با اطلاعات خریدار) 2. فروش ارز 3. طلا، جواهر و پلاتین (همراه با اطلاعات خریدار) 4. قرارداد پیمانکاری5. قبوض خدماتی 6. بلیت هواپیما 7. صادرات 1. فروش (بدون اطلاعات خریدار) 3. طلا، جواهر و پلاتین (بدون اطلاعات خریدار)	اختیاری	InvoicePattern
موضوع صورتحساب: 1. اصلی 2. اصلاحی 3. ابطالی 4. برگشت از فروش	اختیاری	InvoiceSubject
وضعیت صورتحساب در پایانه فروشگاهی کیسان: 1. ثبت اولیه 2. ویرایش بدون تایید 3. تایید صورتحساب توسط فروشنده 4. لغو تایید صورتحساب توسط فروشنده 8. درحال ارسال به مالیات 9. در صف استعلام از مالیات 10. در حال بررسی توسط شرکت معتمد 11. در انتظار رفع خطا 12. درصف انتظار ارسال مجدد به مالیات 13. این شرکت معتمد مجاز به ارسال برای این حافظه نمی باشد 14. دریافت کد رهگیری 15. مرجع صورتحساب – اصلاحی 16. مرجع صورتحساب – برگشت از فروش 17. مرجع صورتحساب – ابطال 18. نیازمند بررسی توسط مودی 19. در انتظار رفع خطای مجدد 100. حذف	اختیاری	statusCode
تاریخ کوتاژ اظهارنامه گمرکی (میلادی)	اختیاری	CustomsDeclarationCottageDate
شماره کوتاژ اظهارنامه گمرکی (میلادی)	اختیاری	CustomsDeclarationCottageNumber
نوع انجام معامله: 1. غیر بورسی 2. بورس کالا 3. بورس انرژی 4. گواهی سپرده کالا	اختیاری	saleType
شماره 22 کاراکتری منحصربه‌فرد مالیاتی صورتحساب مرجع	اختیاری	referenceTaxSerialNumber

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

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

}

“taxSerialNumber”: “AXXXXE000000012B98”,

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

“invoiceDate”: “1402/03/25”

“InvoiceTypeTitle”:”نوع۱”,

“InvoiceTypeCode”: 1,

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

“InvoicePatternCode”: 1,

“InvoiceSubjectTitle “اصلی”:”,

“InvoiceSubjectCode”: 1,

“sellerUserNationalCode”: “1111111111”,

“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”: 100.000000000000,

“unitPrice”: 1000.000000000000,

“equivalentToRial”: 400000.000000000000,

“taxPercent”: 9.000000000000,

“taxPrice”: 9000.000000000000,

“dutyPercent”: 0.000000000000,

“dutyPrice”: 0.000000000000,

“otherLegalFundsPercent”: 0.000000000000,

“otherLegalFundsPrice”: 0.000000000000,

“constructionWages”: 0.000000000000,

“saleProfit”: 0.000000000000,

“brokerCommission”: 0.000000000000,

“discount”: 0.000000000000,

“totalPrice”: 100000.000000,

“totalPriceWithDiscount”: 100000.000000,

“finalPrice”: 109000.000000,

“totlaTaxDutyPrice”: 9000.000000000000

}

]

}

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

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

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

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

Header:

header = {

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

‘Authorization’ : “Bearer ” + token

}

Body:

{

“type”: “2”,

“nationalCode”: “XXXXXXXXXXX”,

“postalCode”: “YYYYYYYYYY”,

“economicCode”: “XXXXXXXXXXX”

}

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

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

{

“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,

“succeeded”: true

}

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

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

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

Header:

header = {

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

‘Authorization’ : “Bearer ” + token

}

Body:

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

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

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

{

“data”:[

{

“commodityCode”: “1”,

“stuffCod”: “2710000003908”,

“stuffTitle”:”اهرم خم کن ابزارآلات خمکاری فلزات”,

“defaultTaxPercent”: 9.000000000000,

“title”:”اهرم خم کن ابزارآلات خمکاری فلزات”,

“isExistsStuff”: true,

“isActive”: true,

“description”:”موجود است”

},

{

“commodityCode”: “52102”,

“stuffCod”: “2720000003945”,

“stuffTitle”:”شمش چدنی”,

“defaultTaxPercent”: 9.000000000000,

“title”:”شمش چدنی”,

“isExistsStuff”: true,

“isActive”: true,

“description”:”موجود است”

},

{

“commodityCode”: “100845215457”,

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

}

],

“error”: false,

“succeeded”: true

}

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

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

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

[server-url] /taxpayer/api/InvoiceExternalService_v6

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

Header:

header = {

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

‘Authorization’ : “Bearer ” + token

}

Body:

[

{

“invoiceNumber”: null,

“invoiceDate”: “0001-01-01T00:00:00”,

“invoiceTime”: null,

“saleType”: 0,

“referenceTaxSerialNumber”: null,

“invoicePattern”: 0,

“invoiceType”: 0,

“invoiceSubject”: 0,

“paymentType”: 0,

“uniqueId”: “00000000-0000-0000-0000-000000000000”,

“buyerType”: 0,

“buyerCompanyName”: null,

“buyerFirstName”: null,

“buyerLastName”: null,

“buyerNationalCode”: null,

“buyerEconomicCode”: null,

“buyerPassportNumber”: null,

“buyerPostalCode”: null,

“buyerPhoneNumber”: null,

“sellerCustomsDeclarationNumber”: null,

“sellerCustomsLicenseNumber”: null,

“sellerContractRegistrationNumber”: null,

“flightType”: null,

“sellerBranch”: “2541”,

“buyerBranch”: “12500”,

“creditPaymentAmount”: 0.0,

“billId”: null,

“tax17”: null,

“customsDeclarationCottageNumber”: null,

“customsDeclarationCottageDate”: null,

“description”: null,

“IsUpdate”: True

“invoiceItems”: }

“commodityType”: 0,

“commodityCode”: null,

“amount”: 0.0,

“unitType”: 0,

“equivalentUnitType”: null,

“equivalentAmount”: 0.0,

“moneyType”: 0,

“equivalentToRial”: 0.0,

“unitPrice”: 0.0,

“discount”: 0.0,

“taxPercent”: 0.0,

“taxPrice”: 0.0,

“dutyPercent”: 0.0,

“dutyPrice”: 0.0,

“dutyTitle”: null,

“exchangeContractNumber”: null,

“exchangeContractDate”: null,

“currencyAmount”: 0.0,

“otherLegalFundsTitle”: null,

“otherLegalFundsPercent”: 0.0,

“otherLegalFundsPrice”: 0.0,

“constructionWages”: 0.0,

“saleProfit”: 0.0,

“brokerCommission”: 0.0,

“brokerContractNumber”: null,

“netWeight”: 0.0,

“ExtendStuffTitle”:”test”

}

“invoicePayments”: {

“paymentMethod”: null,

“paymentAmount”: 0.0,

“paymentDate”: null,

“switchNumber”: null,

“acceptanceNumber”: null,

“terminalNumber”: null,

“traceNumber”: null,

“payerCardNumber”: null,

“payerNationalCode”: null

}

}

]

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

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

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

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

Header:

header = {

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

‘Authorization’ : “Bearer ” + token

}

Body:

[

{

“TaxSerialNumber”: “string”,

“uniqueId”: “string”,

“TrackingCode”: “string”

}

]

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

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

{

“data”:[

{

“taxSerialNumber”: “AXXXXD04CCD00000170DC0”,

“UniqueId”: “a6c93458-c3d2-4ee0-xxx-e28a1d238fbd”,

“trackingId”: “49098674-xxx-4a50-9e42-15415f767548”,

“invoiceNumber”: “11”,

“invoiceDate”: “1402/08/09”,

“InvoiceTypeTitle: “نوع۱”,

“InvoiceTypeCode”: 1,

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

“InvoicePatternCode”: 1,

“InvoiceSubjectTitle”:”اصلی”

“InvoiceSubjectCode”: 1,

“sellerUserNationalCode”: “078063xxx”,

“sellerUserFullName”:”xxxx”

“sellerUserCompanyName”: “xxxx”,

“buyerUserNationalCode”: “10980123xxx”,

“buyerUserFullName”: “yyyy”,

“buyerUserCompanyName”: “zzzzz”,

“BuyerTypeTitle:”حقوقی”,

“BuyerTypeCode”: 2,

“StatusCode”: 3,

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

“createdDate”: “1402/08/09”,

“SaleTypeTitle” “عادی”,

“SaleTypeCode”: 1,

“PaymentType”:”نقدی”,

“invoiceItems”:[

{

“invoiceNumber”: “11”,

“invoiceDate”: “1402/08/09”,

“commodityCode”: “300”,

“stuffTitle”: “uuuuuuu”,

“UnitTypeTitle”: “عدد”,

“UnitTypeCode”: 1627,

“MoneyTypeTitle”:”ریال”,

“MoneyTypeCode”: 364,

“SaleTypeTitle”: “عادی”,

“SaleTypeCode”: 1,

“amount”: 15.00000000,

“unitPrice”: 3490000.00000000,

“equivalentToRial”: 1.0,

“taxPercent”: 9.00,

“taxPrice”: 4711500.0,

“dutyPercent”: 0.00,

“dutyPrice”: 0.0,

“otherLegalFundsPercent”: 0.00,

“otherLegalFundsPrice”: 0.0,

“constructionWages”: 0.0,

“saleProfit”: 0.0,

“brokerCommission”: 0.0,

“discount”: 0.0,

“totalPrice”: 52350000.0,

“totalPriceWithDiscount”: 52350000.0,

“finalPrice”: 57061500.000000,

“totlaTaxDutyPrice”: 4711500.000000000000

}

],

“invoicePayments”:[]

}

],

“error”: false,

“succeeded”: true

}