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

API کیسان

ارسال صورتحساب با برقراری ارتباط از طریق 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

}

Picture of نویسنده: تیم تحریریه کیسان
نویسنده: تیم تحریریه کیسان

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

دیدگاهتان را بنویسید

نشانی ایمیل شما منتشر نخواهد شد. بخش‌های موردنیاز علامت‌گذاری شده‌اند *