=== معتمد آسا — صورتحساب سامانه مودیان ===
Contributors: asatsp
Tags: woocommerce, easy digital downloads, invoice, tax, iran
Requires at least: 5.8
Tested up to: 7.1
Requires PHP: 7.2
Stable tag: 2.0.1
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Issues Iranian electronic tax invoices (Moadian system) for WooCommerce and Easy Digital Downloads orders through the ASA TSP API v2.

== Description ==

افزونه‌ی «معتمد آسا» (ASA TSP) برای هر سفارش فروشگاه، صورتحساب الکترونیکی سامانه مودیان صادر می‌کند؛ ارسال، استعلام وضعیت، برگشت از فروش و ابطال از همان صفحه‌ی سفارش انجام می‌شود. افزونه با ووکامرس و Easy Digital Downloads کار می‌کند و اگر هر دو فعال باشند، هر دو را پوشش می‌دهد.

**امکانات**

* صدور خودکار صورتحساب وقتی سفارش به وضعیت دلخواه (پیش‌فرض: «تکمیل‌شده») می‌رسد؛ ارسال در پس‌زمینه انجام می‌شود و صفحه‌ی خریدار را کند نمی‌کند.
* صورتحساب نوع ۲ برای مصرف‌کننده‌ی نهایی، و نوع ۱ وقتی خریدار در صفحه‌ی پرداخت کد ملی یا شناسه ملی شرکت را وارد کند (بخش اختیاری «صورتحساب رسمی» در پرداخت کلاسیک و بلوک پرداخت).
* سه روش ارزش افزوده: از تنظیمات مالیات فروشگاه، قیمت‌های شامل ارزش افزوده، یا کالای معاف.
* قیمت‌های ریال، تومان، هزار ریال و هزار تومان خودکار به ریال تبدیل می‌شوند؛ کوپن‌ها به تخفیف ردیف تبدیل می‌شوند.
* شناسه کالا/خدمت، واحد و نرخ ارزش افزوده برای هر محصول و هر متغیر (متغیر از محصول اصلی ارث می‌برد)، با لینک جست‌وجوی شناسه کالا.
* کادر «معتمد آسا — سامانه مودیان» در صفحه‌ی سفارش: وضعیت، شماره مالیاتی، شماره مرجع، خطاها و سوابق، با دکمه‌های ارسال، ارسال مجدد، استعلام وضعیت و ابطال.
* ستون «سامانه مودیان» در فهرست سفارش‌ها و اقدام گروهی ارسال و استعلام.
* استرداد سفارش به «برگشت از فروش» یا «ابطال» پیشنهاد می‌شود و فقط پس از تأیید مدیر در سامانه مودیان ثبت می‌شود.
* استعلام خودکار هر ۱۰ دقیقه و تلاش دوباره برای ارسال‌هایی که به معتمد آسا نرسیدند؛ هیچ صورتحسابی دو بار صادر نمی‌شود.
* سازگار با جدول‌های سفارش ووکامرس (HPOS) و بلوک‌های سبد خرید و پرداخت.
* محیط سندباکس برای آزمایش بدون اثر مالیاتی.

برای استفاده به حساب کسب‌وکار در پنل معتمد آسا و شناسه و رمز اتصال API نسخه ۲ نیاز دارید (پنل معتمد آسا: «کسب‌وکارها ← تنظیمات ← اتصال API v2»).

== Installation ==

1. افزونه را از «افزونه‌ها ← افزودن ← بارگذاری افزونه» با فایل zip نصب و فعال کنید.
2. در «ووکامرس ← معتمد آسا» (یا «دانلودها ← معتمد آسا» وقتی فقط EDD فعال است) شناسه و رمز اتصال را وارد کنید و «آزمایش اتصال» را بزنید.
3. روش ارزش افزوده و شناسه کالا/خدمت پیش‌فرض را انتخاب کنید و تنظیمات را ذخیره کنید. تا این دو مشخص نشوند، صورتحسابی صادر نمی‌شود.
4. برای آزمایش، «محیط» را «سندباکس» و شناسه حافظه مالیاتی سندباکس را وارد کنید.

== Frequently Asked Questions ==

= شناسه و رمز اتصال را از کجا بگیرم؟ =

در پنل معتمد آسا، «کسب‌وکارها ← تنظیمات ← اتصال API v2». رمز فقط یک بار نمایش داده می‌شود؛ اگر آن را ندارید، در همان صفحه رمز را بچرخانید.

= شناسه کالا/خدمت را از کجا پیدا کنم؟ =

در صفحه‌ی هر محصول، زبانه‌ی «معتمد آسا»، لینک «جست‌وجوی شناسه کالا» را بزنید. شناسه‌ی پیش‌فرض تنظیمات برای محصولاتی به کار می‌رود که شناسه‌ی جداگانه ندارند.

= اگر سفارش مسترد شود چه می‌شود؟ =

افزونه استرداد را بررسی می‌کند و «برگشت از فروش» (برگشت بخشی از اقلام) یا «ابطال» (برگشت همه‌ی سفارش) را در کادر سفارش پیشنهاد می‌دهد. با «تأیید و ثبت در سامانه مودیان» ثبت می‌شود و با «نادیده گرفتن» کنار می‌رود. استرداد فقط مبلغی (بدون برگشت کالا) با صورتحساب اصلاحی در پنل معتمد آسا انجام می‌شود.

= اگر اتصال در میانه‌ی ارسال قطع شود، صورتحساب تکراری صادر می‌شود؟ =

خیر. نتیجه‌ی نامعلوم پیش از هر ارسال دوباره استعلام می‌شود و معتمد آسا هم صورتحساب دوم با همان کد داخلی را نمی‌پذیرد.

= با حذف افزونه سوابق صورتحساب‌ها پاک می‌شود؟ =

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

== External services ==

This plugin connects to the ASA TSP («معتمد آسا») API v2 at https://api-v2.asatsp.ir, operated by ASA TSP, a licensed trusted service provider of the Iranian Tax Administration's Moadian system. It is the service that registers the store's invoices in the Moadian system; the plugin cannot work without it. Only the store manager's own credentials (Client ID and Client Secret from the ASA TSP panel) are used.

When it connects:

* when the manager clicks «آزمایش اتصال» on the settings page (an access token is requested and the list of measurement units is read);
* when an order reaches the status chosen for automatic issuing, or the manager sends, resends, cancels or confirms a return for an order (from a background job or the manager's own admin request, never from a buyer's page view); before the first invoice of each run the list of measurement units and their official codes is read;
* every 10 minutes, to inquire the state of documents still waiting for the tax system's answer.

What is sent:

* the Client ID and Client Secret, to obtain a short-lived access token;
* the invoice: order number and date, each order line's product name, product code (SKU), goods/service id, unit, quantity, unit price, discount and VAT rate, shipping and fee rows, the store name and the business's fiscal memory id;
* for type-2 invoices, when «نام و همراه خریدار در صورتحساب نوع ۲» is on: the buyer's name, mobile/phone and billing address;
* for type-1 invoices, only when the buyer entered them at checkout: the buyer's national code or company national id, economic code and postal code, plus name, mobile and address;
* for inquiries: only the plugin's internal document ids;
* when the manager clicks «استعلام» next to a goods/service id: only that 13-digit id;
* when the manager opens or turns on «محدودیت IP»: nothing but the access token (ASA reads the address the request comes from).

No data is sent for tracking or statistics. The «جست‌وجوی شناسه کالا» link opens https://stuffid.asatsp.ir in the manager's browser with the product name as the search term; nothing is sent until the manager clicks it.

ASA TSP terms of use: https://asatsp.ir/rules — privacy policy: https://asatsp.ir/privacy

== Changelog ==

= 2.0.1 =
* زبانه «گزارش‌ها»: فروش فروشگاه در کنار مبلغ صورتحساب‌ها در ۱۲ ماه شمسی، صورتحساب‌ها به تفکیک روز و وضعیت، ارزش افزوده چهار فصل اخیر، درخواست‌ها به معتمد آسا و پرتکرارترین دلیل‌های رد، با بازه دلخواه و دریافت CSV.
* ابزارک «معتمد آسا» در پیشخوان فروشگاه: صورتحساب‌های ماه جاری، موارد نیازمند اقدام، سفارش‌های بدون صورتحساب و نمودار ۱۴ روز اخیر.
* نسخه جدید افزونه در خود فروشگاه اعلام می‌شود و در وردپرس، اپن‌کارت و پرستاشاپ با یک کلیک نصب می‌شود؛ بسته پیش از نصب با SHA-256 منتشرشده مطابقت داده می‌شود.
* صفحه «معتمد آسا» کل عرض پیشخوان را می‌گیرد.
* «بررسی و رفع مشکل» برای کارهای پس‌زمینه: علت اجرا نشدن WP-Cron را پیدا می‌کند (خاموش بودن در wp-config.php، بسته بودن درخواست سایت به خودش، کش کامل صفحه، شلوغی صف)، آنچه از دست افزونه برمی‌آید همان‌جا درست می‌کند و دستور آماده Cron میزبان را با دکمه کپی می‌دهد.
* اجرای پشتیبان: تا رفع مشکل، وقتی مدیری صفحه‌های مدیریت وردپرس را باز کند، کارهای عقب‌افتاده افزونه در پس‌زمینه اجرا می‌شوند.
* فهرست صورتحساب‌ها پس از به‌روزرسانی یک بار دوباره ساخته می‌شود تا مبلغ ارزش افزوده هر صورتحساب در گزارش‌ها بیاید.
* «سفارش‌های ارسال‌نشده»، انتخاب روش ارسال سفارش‌های دیرهنگام و ارسال گروهی فوری، در اپن‌کارت، پرستاشاپ و مجنتو هم آمده است.

= 1.1.3 =
* زبانه تازه «سفارش‌های ارسال‌نشده» در صفحه «معتمد آسا»: سفارش‌های وضعیت صدور خودکار که هنوز صورتحساب ندارند، با فیلتر تاریخ، ارسال تکی، انتخابی و «ارسال همه» با نمایش پیشرفت و امکان توقف.
* سفارش قدیمی‌تر از ۱۴ روز با روشی که هنگام ارسال انتخاب می‌کنید فرستاده می‌شود: «ماده ۹» (تاریخ واقعی فروش) یا انتقال تاریخ به ۱۲ روز پیش. ارسال خودکار و دکمه‌های دیگر چنین سفارشی را تا روشش انتخاب نشده نمی‌فرستند، چون سامانه مودیان تاریخ قدیمی‌تر از ۱۵ روز را نمی‌پذیرد.

= 1.1.2 =
* اقدام گروهی «ارسال به سامانه مودیان» در فهرست سفارش‌ها، سفارش‌های انتخاب‌شده را همان لحظه ارسال می‌کند و نتیجه را بالای فهرست نشان می‌دهد. پیش‌تر سفارش‌ها فقط به صف کارهای پس‌زمینه می‌رفتند و در سایتی که این کارها اجرا نمی‌شد، ارسال نمی‌شدند.
* پس از اقدام گروهی، بازگشت همیشه به فهرست سفارش‌ها است؛ حتی اگر افزونه دیگری نشانی بازگشت وردپرس را خالی کند. پیش‌تر در این حالت صفحه «نوشته‌ها» باز می‌شد.
* هشدار پیشخوان «معتمد آسا» وقتی کارهای پس‌زمینه (ارسال خودکار و استعلام وضعیت) عقب بیفتند، با دکمه «اجرای کارهای عقب‌افتاده».

= 1.1.1 =
* صفحه‌ی تازه‌ی «معتمد آسا» با راه‌اندازی مرحله‌به‌مرحله و زبانه‌های پیشخوان، صورتحساب‌ها (ارسال و استعلام تکی و گروهی)، کالاها و خدمات (استعلام شناسه کالا)، گزارش عملیات (هر درخواست با JSON ارسالی و دریافتی، ۹۰ روز) و تنظیمات.
* «معتمد آسا» در نوار بالای پیشخوان، با شمار سندهای نیازمند اقدام.
* گزینه‌ی «فروشنده پرونده ارزش افزوده ندارد (مشمول فراخوان نیست)» با نرخ صفر.
* «کد داخلی در معتمد آسا» و «شرح کالا در صورتحساب» برای هر محصول.
* «محدودیت IP»: محدود کردن شناسه و رمز اتصال به نشانی این سرور.
* واحد اندازه‌گیری هر ردیف با کد رسمی سامانه مودیان فرستاده می‌شود. برای نمونه، «عدد» با کد 1627 فرستاده می‌شود. نسخه‌های قبلی شناسه‌ی داخلی واحد را می‌فرستادند. API v2 برای این شناسه هشدار می‌داد و هشت واحد، از جمله «گرم»، «نخ»، «میلی‌متر» و «میلی‌گرم»، به نام واحد دیگری ثبت می‌شدند. لازم نیست تنظیمات یا محصولات را دوباره ذخیره کنید.

= 1.0.1 =
* ابطالی که کمتر از چهار دقیقه پس از آخرین صورتحساب سفارش (مثلاً درست پس از برگشت از فروش) خواسته شود، با وضعیت «در انتظار زمان ارسال» نگه داشته می‌شود و زمان‌بند آن را به‌طور خودکار می‌فرستد. سامانه مودیان ابطالِ زودتر از سند مرجع را با خطای 0200201 رد می‌کرد.
* تاریخ صدور برگشت از فروش هرگز پیش از تاریخ صورتحساب مرجع نیست.

= 1.0.0 =
* نخستین نسخه: صدور خودکار و دستی صورتحساب برای ووکامرس و Easy Digital Downloads، صورتحساب نوع ۱ و ۲، برگشت از فروش و ابطال با تأیید مدیر، استعلام خودکار، سازگاری با HPOS و بلوک پرداخت.
