=== معتمد آسا — صورتحساب سامانه مودیان ===
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: 1.0.0
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);
* 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.

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 ==

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