راهنمای مطالعه
ارسال صورتحساب با برقراری ارتباط از طریق 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
تصویر ارسال درخواست و دریافت توکن
سرویس دریافت توکن دسترسی
[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 |
قالب ورودی اطلاعات
[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
}
به ازای هر قلم کالا که خطا داشته باشد یک خروجی مشابه کد بالا دریافت میشود. که مقادیر آن در جدول زیر آمده است:
تشریح نتیجه
در حالت کلی 2 نوع خطا ممکن است دریافت شود که به شرح ذیل است:
- خطا در عدم ثبت شناسه کالا توسط کاربر
اگر هنگام ثبت صورتحساب، کالایی برای مؤدی تعریف نشده باشد، فیلد CommodityCode، شناسه اختصاصی کالا را مشخص میکند، در اینصورت مؤدی میبایست نسبت به ثبت کالا/خدمت خود قبل از ثبت و ارسال صورتحسابها اقدام نماید.
“status”: 1,
“uniqueId”: “8b8a3877-a7cf-4d8c-bdd9-ec5d599dfab9”,
“commodityCode”: “0831100692420001”,
“description”: “کد کالا نامعتبر است”,
“title”: “CommodityCode”
}
- خطا در ثبت صورتحساب تکراری
اگر کاربر صورتحساب تکراری ثبت نماید، 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، کدینگ داخلی و …) |
استعلام صورتحسابهای ثبتشده
جهت استعلام صورتحسابهای ثبت شده میتوان از روشهای زیر استفاده نمود:
- استعلام بر اساس شماره منحصربهفرد مالیاتی TaxSerialNumber
کاربران میتوانند جهت استعلام صورتحسابهای ثبتشده در سامانه کیسان، از طریق URL زیر اقدام نموده و وضعیت صورتحساب خود را مشاهده نمایند:
- [server-url] /taxpayer/ api/InvoiceExternalService_v6/InquiryByTaxSerialNumber
نمونه قالب ورودی اطلاعات جهت استعلام صورتحساب بر اساس شماره منحصربهفرد مالیاتی به صورت زیر است:
Header:
header = {
‘Content-Type’: ‘application/json ; charset=utf-8’,
‘Authorization’ : “Bearer ” + token
}
Body:
data = [
“XXXXXXXXXXXXXXXXXXXXXX”
]
- استعلام بر اساس شماره رهگیری صورتحساب 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”
]
- استعلام بر اساس شماره منحصربهفرد ایجاد شده توسط کاربر UniqueId
کاربران میتوانند جهت استعلام صورتحسابهای ثبتشده در سامانه کیسان، طریق URL زیر اقدام نموده و وضعیت صورتحساب خود را مشاهده نمایند:
نمونه قالب ورودی اطلاعات جهت استعلام صورتحساب بر اساس شماره منحصربهفرد ایجادشده توسط کاربر به صورت زیر است:
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”]
قالب خروجی نتیجه دریافت اطلاعات به صورت جیسون شامل موارد زیر است:
{
“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، 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
}