یکپارچه‌سازی کامل برای تیم‌های فنی و سامانه‌های فروش
اتصال نرم‌افزار به آسا با وب‌سرویس (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 جدید بگیرید؛ Secret قبلی همان لحظه نامعتبر می‌شود.
توکن کوتاه‌مدت
درخواست‌ها با توکنی انجام می‌شوند که به‌صورت پیش‌فرض ۶۰ دقیقه اعتبار دارد.
دسترسی محدود با scope
برای هر توکن فقط دسترسی لازم را بخواهید: ثبت و ارسال، ابطال، یا فقط استعلام.
فقط HTTPS
همه درخواست‌های وب‌سرویس روی ارتباط رمزنگاری‌شده انجام می‌شوند.
محیط آزمایشی جدا
صورتحساب‌های آزمایشی با نشان Sandbox و شناسه جداگانه فرستاده می‌شوند و به محیط عملیاتی نمی‌روند.
آسا شرکت معتمد مالیاتی نوع اول با مجوز سازمان امور مالیاتی کشور است و از داده‌های شما طبق ضوابط محرمانگی و حریم خصوصی محافظت می‌کند.
پیش‌نیازها
- برنامه‌نویس یا تیم فنی آشنا با فراخوانی سرویس‌های HTTP و JSON
- Client ID و Client Secret صادرشده از زبانه «اتصال API v2» در تنظیمات کسب‌وکار
- شناسه یکتای حافظه مالیاتی فعال؛ برای آزمایش، شناسه جداگانه محیط Sandbox سازمان
- شناسه ۱۳ رقمی کالا/خدمت اقلام و کد واحدهای اندازه‌گیری (از سرویس داده‌های مرجع)
پیش‌نیاز مشترک همه روش‌ها ثبت‌نام رایگان در پنل آسا و دریافت شناسه یکتای حافظه مالیاتی با کلید معتمد آسا است. مراحل را در راهنمای ثبت‌نام و دریافت شناسه یکتا ببینید.
مستندات و منابع این روش
- مستندات کامل 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 استاندارد، مدل ساده و محیط آزمایشی را دارد. اتصال‌های موجود نسخه ۱ بدون تغییر کار می‌کنند، اما مستندات نسخه ۱ دیگر منتشر نمی‌شود و نشانی آن به مستندات نسخه ۲ هدایت می‌شود. اتصال تازه و هر به‌روزرسانی را با نسخه ۲ انجام دهید.
روش‌های دیگر اتصال به آسا
- پنل تحت وبساده‌ترین راه شروع؛ بدون نصب و بدون دانش فنی
- فایل اکسلتا ۵۰۰٬۰۰۰ ردیف در هر فایل، با خطایابی پیش از ثبت
- اتصال نرم‌افزار حسابداریصورتحساب‌های سپیدار، هلو، تدبیر و سیبا، مستقیم در پنل آسا
- پایگاه داده اختصاصیبا هر پایگاه داده‌ای؛ بدون تغییر در نرم‌افزار شما
- کارت‌خوانتراکنش‌های کارت‌خوان را بدون ورود دستی به صورتحساب تبدیل کنید
برای شروع با این روش آماده‌اید؟
ثبت‌نام در آسا رایگان است. اگر مطمئن نیستید این روش برای کسب‌وکار شما مناسب است، کارشناسان آسا راهنمایی‌تان می‌کنند.
بدون هزینه ثبت‌نام، بدون گواهی امضا، بدون تعطیلی.