یکپارچهسازی کامل برای تیمهای فنی و سامانههای فروش
اتصال نرمافزار به آسا با وبسرویس (API) و ارسال خودکار صورتحساب
نرمافزار فروش، فروشگاه اینترنتی یا ERP شما صورتحساب را مستقیم و خودکار برای آسا میفرستد و نتیجه را از همان مسیر میگیرد. کنترل، امضا و ارسال به سامانه مؤدیان با آساست.
- دانش فنی لازم
- برنامهنویس
- حجم مناسب صورتحساب
- زیاد تا بسیار زیاد
- راهاندازی
- نیازمند توسعه در سمت شما
- میزان خودکاربودن
- کاملاً خودکار
روش «وبسرویس (API)» چیست و برای چه کسی مناسب است؟
وبسرویس نسخه ۲ آسا یک API مبتنی بر JSON در نشانی api-v2.asatsp.ir است. با آن میتوانید در هر درخواست از ۱ تا ۲۵۰ صورتحساب را ثبت کنید، تعیین کنید بلافاصله به سامانه مؤدیان ارسال شوند یا فقط ثبت بمانند، و بعداً وضعیت هر صورتحساب را با شناسه داخلی خودتان، شماره صورتحساب یا شماره مالیاتی بپرسید.
دو مدل ورودی وجود دارد: «JSON استاندارد سازمان امور مالیاتی» برای تیمهایی که ساختار رسمی سامانه مؤدیان را خودشان تولید میکنند، و «مدل ساده» که در آن خریدار، اقلام و پرداختها را میفرستید و آسا ساختار رسمی را میسازد. هر دو مدل صورتحساب نوع ۱ و ۲، الگوهای مختلف و موضوعهای اصلی، اصلاحی، ابطالی و برگشت از فروش را پشتیبانی میکنند.
احراز هویت با Client ID و Client Secret انجام میشود که از پنل آسا صادر میکنید. برای آزمایش، صورتحساب را با نشان Sandbox و شناسه حافظه مالیاتی محیط آزمایشی سازمان میفرستید تا چیزی به محیط عملیاتی ارسال نشود.
مناسب است اگر…
- نرمافزار فروش، فروشگاه اینترنتی، اپلیکیشن یا ERP اختصاصی دارید و تیم فنی در اختیارتان است.
- میخواهید صورتحساب بهمحض صدور و بدون دخالت کاربر ثبت و ارسال شود.
- شرکت نرمافزاری هستید و میخواهید ارسال به سامانه مؤدیان را به محصول خود اضافه کنید.
- نرمافزار شما ابری است یا نمیخواهید برنامهای کنار پایگاه داده نصب شود.
روش دیگری انتخاب کنید اگر…
- برنامهنویس در اختیار ندارید و از سپیدار، هلو، تدبیر یا سیبا استفاده میکنید: اتصال نرمافزار حسابداری
- فقط میخواهید تعدادی صورتحساب را یکجا و بدون توسعه ثبت کنید: فایل اکسل
صورتحساب در این روش چه مسیری را طی میکند؟
- نرمافزار شماساخت صورتحساب و فراخوانی API
- وبسرویس آسااحراز هویت، اعتبارسنجی و ثبت
- امضا و ارسالبا کلید معتمد آسا به سامانه مؤدیان
- پیگیری وضعیتاستعلام نتیجه از همان API
مراحل راهاندازی و استفاده
ثبتنام و تعریف کسبوکار
در پنل آسا کسبوکار را با شناسه یکتای حافظه مالیاتی تعریف کنید. برای آزمایش، شناسه حافظه مالیاتی محیط Sandbox را هم ثبت کنید.
صدور اعتبارنامه API
در پنل، از «کسبوکارها» وارد تنظیمات کسبوکار شوید و در تب «اتصال API v2» اعتبارنامه صادر کنید. Client Secret فقط همان لحظه نمایش داده میشود؛ آن را در جای امن نگه دارید.
دریافت توکن دسترسی
با Client ID و Client Secret سرویس دریافت توکن را فراخوانی کنید و توکن را در سرآیند Authorization درخواستهای بعدی بگذارید. اعتبار پیشفرض توکن ۶۰ دقیقه است.
ثبت صورتحساب در محیط آزمایشی
صورتحساب را با مدل ساده یا JSON استاندارد و با نشان Sandbox بفرستید و پاسخ هر صورتحساب را بررسی کنید. خطاها به تفکیک فیلد برمیگردند.
پیگیری وضعیت
وضعیت صورتحساب را با سرویسهای استعلام بپرسید: در صف ارسال، ارسالشده و در انتظار پاسخ سامانه، موفق یا دارای خطا.
انتقال به محیط عملیاتی
پس از اطمینان، نشان Sandbox را بردارید و با شناسه حافظه مالیاتی عملیاتی ارسال کنید. نتیجه ثبت هر صورتحساب در صفحه «لاگها»ی پنل هم دیده میشود.
مزایا و معایب روش «وبسرویس (API)»
مزایا
- خودکارسازی کاملصورتحساب مستقیم از نرمافزار شما ثبت و ارسال میشود و نتیجه به همان نرمافزار برمیگردد.
- مستقل از سیستمعامل و پایگاه دادههر زبان و سکویی که درخواست HTTP بفرستد کافی است؛ روی سرور شما چیزی نصب نمیشود.
- ارسال گروهیدر هر درخواست تا ۲۵۰ صورتحساب ثبت میشود و پاسخ هر صورتحساب جداگانه برمیگردد.
- مدل ساده در کنار JSON رسمیاگر نمیخواهید ساختار رسمی سامانه مؤدیان را خودتان بسازید، مدل ساده کار را کوتاه میکند.
- محیط آزمایشیبا نشان Sandbox میتوانید پیش از ارسال واقعی، اتصال و دادهها را امتحان کنید.
- مستندات کامل با نمونهکدمستندات فارسی همراه نمونه درخواست به cURL، JavaScript، C#، Python و PHP در دسترس است.
- جلوگیری از ثبت تکراریهر درخواست شناسه یکتا دارد و درخواست تکراری دوباره ثبت نمیشود.
معایب و محدودیتها
- نیاز به برنامهنویسپیادهسازی، آزمون و نگهداری اتصال بر عهده تیم فنی شماست و زمان توسعه میخواهد.
- پیگیری وضعیت با استعلامنتیجه ارسال بهصورت خودکار به نرمافزار شما اعلام نمیشود؛ باید وضعیت را دورهای بپرسید.
- مسئولیت نگهداری اعتبارنامهنگهداری امن Client Secret و تعویض دورهای آن با شماست.
- کیفیت داده با نرمافزار شماستشناسه کالا/خدمت، اطلاعات خریدار و محاسبات باید در سامانه شما درست تولید شود؛ خطای داده یعنی رد صورتحساب.
امنیت روش «وبسرویس (API)»
اعتبارنامه اختصاصی هر کسبوکار
هر کسبوکار Client ID و Client Secret خودش را دارد. Secret فقط یکبار نمایش داده میشود و قابل بازیابی نیست.
تعویض فوری Secret
اگر احتمال افشای Secret میدهید، با یک کلیک Secret جدید بگیرید؛ قبلی همان لحظه نامعتبر میشود.
توکن کوتاهمدت
درخواستها با توکنی انجام میشود که بهصورت پیشفرض ۶۰ دقیقه اعتبار دارد.
دسترسی محدود با Scope
برای هر توکن میتوانید فقط دسترسی لازم را بخواهید: ثبت و ارسال، ابطال، یا فقط استعلام.
فقط HTTPS
همه درخواستهای وبسرویس روی ارتباط رمزنگاریشده انجام میشود.
محیط آزمایشی جدا
صورتحسابهای آزمایشی با نشان Sandbox و شناسه جداگانه فرستاده میشوند و به محیط عملیاتی نمیروند.
آسا شرکت معتمد مالیاتی نوع اول با مجوز سازمان امور مالیاتی است و با دادههای شما طبق ضوابط محرمانگی و حریم خصوصی رفتار میکند.
پیشنیازها
- برنامهنویس یا تیم فنی آشنا با فراخوانی سرویسهای HTTP و JSON
- Client ID و Client Secret صادرشده از تب «اتصال API v2» در تنظیمات کسبوکار
- شناسه یکتای حافظه مالیاتی فعال؛ برای آزمایش، شناسه جداگانه محیط Sandbox سازمان
- شناسه ۱۳ رقمی کالا/خدمت اقلام و کد واحدهای اندازهگیری (از سرویس دادههای مرجع)
پیشنیاز مشترک همه روشها، ثبتنام در پنل آسا و دریافت شناسه یکتای حافظه مالیاتی با کلید معتمد آسا است. راهنمای ثبتنام و دریافت شناسه یکتا را ببینید.
مستندات و لینکهای این روش
- مستندات کامل API نسخه ۲راهنمای فنی احراز هویت، ثبت صورتحساب با هر دو مدل، پیگیری وضعیت، خطاها و نمونهکد.
- مستندات API نسخه ۲ (نمایش مستقل)همان مستندات روی دامنه وبسرویس؛ برای باز کردن در صفحه کامل یا ارسال به تیم فنی.
- مستندات API نسخه ۱ویژه مشتریانی که پیشتر با نسخه ۱ متصل شدهاند. اتصالهای جدید را با نسخه ۲ پیاده کنید.
- راهنمای ثبتنام و دریافت شناسه یکتاآموزش تصویری انتخاب معتمد آسا در کارپوشه، دریافت شناسه یکتای حافظه مالیاتی و تعریف کسبوکار در پنل.
مشخصات فنی در یک نگاه
| مشخصه | مقدار |
|---|---|
| نشانی پایه | https://api-v2.asatsp.ir |
| قالب داده | JSON با کدگذاری UTF-8 |
| احراز هویت | Client ID و Client Secret ← توکن دسترسی (Bearer) |
| اعتبار توکن | ۶۰ دقیقه (پیشفرض) |
| تعداد صورتحساب در هر درخواست | ۱ تا ۲۵۰ |
| محیط آزمایشی | نشان sandBox روی هر صورتحساب، با شناسه حافظه مالیاتی Sandbox |
| انواع صورتحساب | نوع ۱ و نوع ۲؛ موضوع اصلی، اصلاحی، ابطالی و برگشت از فروش |
| نمونهکد | cURL، JavaScript، C#، Python، PHP |
نمونه درخواست دریافت توکن
اولین گام هر اتصال، دریافت توکن دسترسی است. مقدار scope اختیاری است؛ اگر ارسال نشود همه دسترسیهای مجاز همان اعتبارنامه اعمال میشود.
curl -X POST "https://api-v2.asatsp.ir/api/auth/v2/token" \
-H "Content-Type: application/json; charset=utf-8" \
-d '{
"grant_type": "client_credentials",
"client_id": "<client_id>",
"client_secret": "<client_secret>",
"scope": "v2.invoice.send v2.invoice.read"
}'سرویسهای اصلی
| کاربرد | سرویس |
|---|---|
| دریافت توکن دسترسی | POST /api/auth/v2/token |
| ثبت صورتحساب با JSON استاندارد سازمان | POST /api/invoice/send |
| ثبت صورتحساب فروش نوع ۱ با مدل ساده | POST /api/invoice/salesWithBuyerData |
| ثبت صورتحساب فروش نوع ۲ با مدل ساده | POST /api/invoice/salesEndUser |
| ارسال صورتحسابهای ثبتشده به سازمان | POST /api/invoice/sendInvoice |
| ثبت صورتحساب ابطالی | POST /api/invoice/cancelInvoice |
| پیگیری وضعیت با شناسه داخلی | POST /api/invoice/inquiryInternalId |
| پیگیری وضعیت با شماره مالیاتی | POST /api/invoice/inquiryTaxId |
| ثبت پرداخت صورتحساب ارسالشده | POST /api/invoice/registerPayment |
| فهرست واحدهای اندازهگیری | GET /api/InvoiceItemUnit |
این جدول خلاصه است. فهرست کامل سرویسها، مدل ساده سایر الگوها، ساختار درخواست و پاسخ و کدهای خطا در مستندات کامل آمده است.
پرسشهای متداول درباره روش «وبسرویس (API)»
Client ID و Client Secret را از کجا بگیرم؟
در پنل آسا از «کسبوکارها» وارد تنظیمات کسبوکار شوید و در تب «اتصال API v2» اعتبارنامه صادر کنید. Client Secret فقط هنگام صدور یا تعویض نمایش داده میشود.
آیا محیط آزمایشی (Sandbox) وجود دارد؟
بله. هر صورتحساب را میتوانید با نشان sandBox بفرستید. برای این کار باید شناسه حافظه مالیاتی محیط آزمایشی سازمان را جداگانه دریافت و در پنل ثبت کرده باشید؛ شناسه عملیاتی در محیط آزمایشی استفاده نمیشود.
در هر درخواست چند صورتحساب میتوان فرستاد؟
از ۱ تا ۲۵۰ صورتحساب. پاسخ هر صورتحساب جداگانه و به ترتیب ورودی برمیگردد؛ خطای یک صورتحساب مانع ثبت بقیه نمیشود.
آیا باید JSON رسمی سامانه مؤدیان را خودمان بسازیم؟
الزامی نیست. در «مدل ساده» اطلاعات خریدار، اقلام و پرداخت را میفرستید و آسا ساختار رسمی را میسازد. اگر ترجیح میدهید، میتوانید JSON استاندارد سازمان را هم مستقیم بفرستید.
نتیجه ارسال به سامانه مؤدیان را چطور بفهمیم؟
با سرویسهای استعلام، وضعیت صورتحساب را با شناسه داخلی، شماره صورتحساب یا شماره مالیاتی بپرسید. وضعیتها عبارتاند از: در صف ارسال، ارسالشده و در انتظار پاسخ سامانه، موفق و دارای خطا.
تفاوت نسخه ۱ و ۲ وبسرویس چیست؟
نسخه ۲ نسخه فعلی و پیشنهادی است و ثبت گروهی، JSON استاندارد، مدل ساده و محیط آزمایشی را دارد. نسخه ۱ برای مشتریانی که قبلاً متصل شدهاند همچنان در دسترس است.
روشهای دیگر اتصال به آسا
- پنل تحت وبسادهترین راه شروع؛ بدون نصب و بدون دانش فنی
- فایل اکسلدهها یا صدها صورتحساب با یک بار بارگذاری
- اتصال نرمافزار حسابداریصورتحسابهای سپیدار، هلو، تدبیر و سیبا، مستقیم در پنل آسا
- پایگاه داده اختصاصیبا هر پایگاه دادهای؛ بدون تغییر در نرمافزار شما
- کارتخوانتراکنشهای پوز را به صورتحساب تبدیل کنید
برای شروع با این روش آمادهاید؟
ثبتنام در آسا رایگان است. اگر مطمئن نیستید این روش برای کسبوکار شما مناسب است، کارشناسان آسا راهنماییتان میکنند.
