=== افزونه حمل و نقل |ماشین حساب ارسال پست و تیپاکس و چاپار و دیجی اکسپرس و پارسی پست | پس کرایه |تنظیمات ارسال رایگان ===

Contributors: amadast, alih70442
Tags: shipping, delivery, online-shipping-calculation, online store, ecommerce
Requires at least: 5.8
Tested up to: 7.0
Stable tag: 3.2.7
Requires PHP: 7.4
License: GPLv3 or later
License URI: https://www.gnu.org/licenses/gpl-3.0.html
A plugin that calculates shipping prices online with various sending methods.

== Description ==
افزونه Amadast Shipping WP یک افزونه حمل‌ونقل پیشرفته برای ووکامرس است که هزینه ارسال مرسوله را به‌صورت آنلاین و دقیق بر اساس شهر مبدا، شهر مقصد، وزن، ابعاد، نوع بسته‌بندی و سرویس حمل محاسبه می‌کند و به مشتریان امکان می‌دهد در صفحه تسویه‌حساب، روش ارسال دلخواه خود را انتخاب کنند. این افزونه به‌طور کامل با سیستم مناطق حمل‌ونقل ووکامرس یکپارچه بوده و قابلیت استفاده از چندین سرویس‌دهنده ارسال را فراهم می‌کند.

Amadast Shipping WP is a powerful WooCommerce shipping plugin that calculates accurate and real‑time shipping costs based on the actual order details and allows customers to choose their preferred shipping method during checkout. The plugin is fully integrated with WooCommerce Shipping Zones and uses Amadast's external API to retrieve up‑to‑date shipping prices from supported courier services.

= امکانات اصلی افزونه / Key Features =

- محاسبه آنلاین هزینه ارسال بر اساس اطلاعات واقعی سفارش / Real‑time shipping cost calculation
- یکپارچه با ووکامرس و مناطق حمل‌ونقل (Shipping Zones) / Full integration with WooCommerce Shipping Zones
- امکان انتخاب چند سرویس حمل‌ونقل (مانند پست پیشتاز، تیپاکس و سرویس‌های فوروارد) / Support for multiple courier services (e.g. Post Pishtaz, Tipax, Forward services)
- تشخیص خودکار واحد وزن محصولات و تبدیل آن به گرم / Automatic detection and conversion of product weight units
- تعیین وزن پیش‌فرض برای محصولاتی که وزن ندارند / Default product weight for items without defined weight
- افزودن وزن بسته‌بندی به وزن کل سفارش / Additional packaging weight support
- استفاده از ابعاد پیش‌فرض برای تشخیص خودکار نوع بسته‌بندی / Default product dimensions for automatic package type detection
- امکان تعریف هزینه‌های اضافی به‌صورت مبلغ ثابت یا درصدی / Fixed or percentage‑based extra shipping costs
- پشتیبانی از ارسال رایگان برای شهرهای انتخاب‌شده / Free shipping support for selected cities
- قابلیت مخفی‌سازی سایر روش‌های ارسال در صورت فعال بودن ارسال رایگان / Option to hide other shipping methods when free shipping is available
- پشتیبانی از پس‌کرایه (پرداخت هزینه حمل در زمان تحویل) / Cash on Delivery (Postage Due) shipping option
- تعریف هزینه پایه و هزینه هر کیلوگرم به‌عنوان حالت جایگزین در زمان قطعی سرویس / Fallback shipping cost when the external API is unavailable
- سازگار با قالب‌ها و افزونه‌های رایج ووکامرس / Compatible with most WooCommerce themes and plugins

= مدیریت فیلدهای صفحه پرداخت ووکامرس / Checkout & WooCommerce Fields Management =

افزونه Amadast امکان کنترل بهتر فرم تسویه‌حساب ووکامرس را فراهم می‌کند، از جمله:

Amadast Shipping WP provides better control over the WooCommerce checkout experience:

- بارگذاری لیست شهرها در صفحه پرداخت / Optional city list loading on the checkout page
- استفاده از فیلد پیش‌فرض شهر ووکامرس یا لیست اختصاصی شهرها / Ability to use WooCommerce default city field or Amadast city list
- مخفی‌سازی فیلدهای غیرضروری مانند نام شرکت، آدرس دوم، ایمیل (در صورت استفاده از شماره موبایل) / Option to hide unnecessary checkout fields such as company name, address line 2, email address (when mobile number is used instead)

= تنظیمات ارسال / Shipping Settings =

- تعریف عنوان اختصاصی برای روش «ارسال رایگان» / Custom title for the Free Shipping method
- انتخاب شهرهای دارای ارسال رایگان (با امکان جستجو و انتخاب چندگانه) / Select cities eligible for Free Shipping (with multi‑select and search)
- فعال‌سازی روش ارسال پس‌کرایه برای مشتریان / Enable Cash on Delivery (Postage Due) shipping method

= سازگاری / Compatibility =

- وردپرس / WordPress
- ووکامرس / WooCommerce
- مناطق حمل‌ونقل ووکامرس / WooCommerce Shipping Zones


== Screenshots ==

1- صفحه تنظیمات افزونه
2- نمایش قیمت به مشتریان در صفحه سبد خرید
3- نمایش قیمت به مشتریان در صفحه پرداخت

== External services ==

This plugin connects to third-party and Amadast-hosted services. Data is sent only when the related feature is used (for example, during checkout, admin settings tests, OTP login, or when the map feature is enabled).

این افزونه به سرویس‌های شخص ثالث و سرویس‌های میزبانی‌شده توسط آمادست متصل می‌شود. داده‌ها تنها زمانی ارسال می‌شوند که از ویژگی مربوطه استفاده شود (برای مثال، در طول تسویه‌حساب، تست‌های تنظیمات مدیریت، ورود با رمز یکبار مصرف (OTP) یا زمانی که نقشه فعال باشد).

= Amadast Shipping Calculator API =

This service is used to calculate live shipping prices for supported carriers during cart and checkout.

Data sent when rates are requested:
- Origin and destination city
- Package weight, value, and type
- Selected couriers
- Plugin version
- Site URL, site name, site description, and admin email (for account/support context)
- Relevant Amadast plugin settings

If the API does not respond, the plugin may use configured fallback pricing.

Service provider: Amadast
Terms of service: https://amadast.com/terms
Privacy policy: https://amadast.com/terms

سرویس محاسبه‌گر هزینه ارسال آمادست:
این سرویس برای محاسبه لحظه‌ای و آنلاین هزینه ارسالِ سرویس‌های حمل‌ونقل پشتیبانی‌شده، در سبد خرید و صفحه تسویه‌حساب استفاده می‌شود.
داده‌هایی که برای محاسبه هزینه به این سرویس ارسال می‌شوند:
- شهر مبدا و شهر مقصد
- وزن مرسوله (پس از اعمال وزن بسته‌بندی)، ارزش و نوع بسته
- سرویس‌های حمل‌ونقل انتخاب‌شده
- نسخه افزونه
- آدرس سایت، نام سایت، توضیحات سایت و ایمیل مدیر سایت (جهت ارتباط در صورت نیاز فنی و پشتیبانی)
- تنظیمات مربوط به افزونه آمادست
در صورتی که API در دسترس نباشد، افزونه به‌صورت خودکار از هزینه‌های پیش‌فرضِ تعریف‌شده در پنل مدیریت استفاده می‌کند.

= Amadast Account API (OTP authentication) =

This service is used when a store administrator signs in to their Amadast account inside the plugin settings.

Data sent when OTP login is used:
- Mobile phone number
- OTP verification code
- Site URL and login metadata

Service provider: Amadast
Terms of service: https://amadast.com/terms
Privacy policy: https://amadast.com/terms

سرویس حساب کاربری آمادست (احراز هویت پیامکی):
این سرویس زمانی استفاده می‌شود که مدیر فروشگاه بخواهد از داخل تنظیمات افزونه وارد حساب کاربری آمادست خود شود.
داده‌های ارسالی هنگام ورود با پیامک (OTP):
- شماره تلفن همراه
- کد تایید یکبار مصرف
- آدرس سایت و متادیتاهای مربوط به ورود

= Amadast Package Detection API =

This service is used to suggest package/box type for cart items when AI package detection is enabled.

Data sent when package detection runs:
- Cart item dimensions, weight, quantity, and product metadata needed for packing estimation

Service provider: Amadast (shop-integration.amadast.com)
Terms of service: https://amadast.com/terms
Privacy policy: https://amadast.com/terms

سرویس تشخیص بسته‌بندی آمادست:
این سرویس زمانی که ویژگی "تشخیص بسته‌بندی با هوش مصنوعی" فعال باشد، برای پیشنهاد نوع بسته/کارتن برای اقلام موجود در سبد خرید استفاده می‌شود.
داده‌های ارسالی هنگام اجرای تشخیص بسته‌بندی:
- ابعاد، وزن، تعداد و متادیتاهای محصول که برای تخمین نوع بسته‌بندی نیاز است.

= Amadast AI Shipping Price Prediction =

This service is used as a fallback estimator when the main calculator API is unavailable or times out (if enabled in settings). It is also used from admin test tools.

Data sent when prediction runs:
- Sender and recipient city
- Package weight, value, and type
- Selected provider

Service provider: Amadast (predict.amadast.sabz.cloud)
Terms of service: https://amadast.com/terms
Privacy policy: https://amadast.com/terms

سرویس پیش‌بینی هزینه ارسال با هوش مصنوعی:
این سرویس به‌عنوان یک تخمین‌زننده جایگزین در زمانی که API اصلی محاسبه‌گر در دسترس نباشد یا با تایم‌اوت مواجه شود (در صورت فعال بودن در تنظیمات) استفاده می‌شود. همچنین در ابزارهای تستِ پنل مدیریت نیز کاربرد دارد.
داده‌های ارسالی هنگام اجرای پیش‌بینی:
- شهر فرستنده و گیرنده
- وزن، ارزش و نوع مرسوله
- شرکت حمل‌ونقل انتخاب‌شده

= Neshan Maps (optional) =

If the checkout map feature is enabled and a Neshan API key is configured, the plugin loads Neshan map assets and may call Neshan reverse-geocoding to convert map coordinates to an address.

Data sent when the map feature is used:
- Latitude and longitude selected on the map (reverse geocoding request)
- Neshan API key configured in plugin settings

Service provider: Neshan (neshan.org)
Terms of service: https://platform.neshan.org/terms
Privacy policy: https://platform.neshan.org/privacy

نقشه نشان (اختیاری):
در صورتی که ویژگی نقشه در صفحه تسویه‌حساب فعال باشد و کلید API نشان تنظیم شده باشد، افزونه فایل‌های نقشه نشان را بارگذاری کرده و ممکن است برای تبدیل مختصات نقشه به آدرس کتبی، از سرویس نشان استفاده کند.
داده‌های ارسالی هنگام استفاده از نقشه:
- طول و عرض جغرافیایی انتخاب‌شده روی نقشه
- کلید API نشان که در تنظیمات افزونه وارد شده است.

= Amadast media CDN (admin landing page only) =

The plugin admin landing page may load a promotional intro video hosted on Amadast media storage.

Data sent when the video is loaded:
- Standard HTTP request metadata (IP address, browser user agent, requested file URL)

Service provider: Amadast (amadast-file.storage.iran.liara.space)
Terms of service: https://amadast.com/terms
Privacy policy: https://amadast.com/terms

شبکه توزیع محتوای آمادست (فقط در صفحه فرود تنظیمات):
صفحه فرود (Landing page) افزونه در پنل مدیریت ممکن است یک ویدیوی معرفی را که در فضای ذخیره‌سازی رسانه آمادست میزبانی می‌شود، بارگذاری کند.
داده‌های ارسالی هنگام بارگذاری ویدیو:
- متادیتای استاندارد درخواست‌های HTTP (آدرس IP، نوع مرورگر یا User Agent، آدرس فایل درخواستی)

== Installation ==

= Using The WordPress Dashboard =

1. Navigate to the Add New in the plugins dashboard
2. Search for Amadast
3. Click Install Now
4. Activate the plugin on the Plugin dashboard

نصب از طریق داشبورد وردپرس:
1. به بخش افزونه‌ها > افزودن افزونه تازه در داشبورد وردپرس بروید
2. کلمه Amadast را جستجو کنید
3. روی دکمه "نصب" کلیک کنید
4. افزونه را فعال کنید

= Uploading in WordPress Dashboard =

1. Navigate to the Add New in the plugins dashboard
2. Navigate to the Upload area
3. Select amadast-shipping-wp.zip from your computer
4. Click Install Now
5. Activate the plugin in the Plugin dashboard

آپلود فایل در داشبورد وردپرس:
1. به بخش افزونه‌ها > افزودن افزونه تازه در داشبورد وردپرس بروید
2. روی دکمه "بارگذاری افزونه" کلیک کنید
3. فایل amadast-shipping-wp.zip را از سیستم خود انتخاب کنید
4. روی دکمه "هم‌اکنون نصب کن" کلیک کنید
5. پس از نصب، افزونه را فعال کنید

== Changelog ==

= 3.2.4 - 2026-06-11 =
- Compliance: Renamed plugin display name to remove "WP" per WordPress.org trademark guidelines.
- Compliance: Aligned Requires at least and Requires PHP between plugin header and readme.
- Compliance: Completed External services documentation for all remote endpoints used by the plugin.
- Compliance: Applied escaping and sanitization fixes across admin UI, wizard, auth, and settings screens.
- Compliance: Ensured nonce and server input sanitization follows WordPress security guidelines.

= 3.2.3 - 2026-06-06 =
- New: Per-provider display priority on checkout (lower number = shown first).
- New: Per-provider max cart weight limit in grams.
- New: Custom Amadast shipping methods with province/city/weight/price/product conditions, free or paid cost, and COD support.

= 3.2.2 - 2026-06-02 =
- Compliance: Set WordPress "Tested up to" to major version 7.0 (WordPress.org plugin guidelines).
- Compliance: Removed custom Plugin Update Checker; updates are delivered only via WordPress.org.

= 3.2.1 - 2026-05-28 =
- New: Configurable calculator API wait time on checkout (default 4 seconds) in calculator settings.
- Enhancement: On timeout, fallback to AI price estimation (1 second) when enabled, then fixed rate.
- Enhancement: Faster shipping price polling and deadline-aware HTTP timeouts on checkout.
- Enhancement: Fixed-rate shipping label on checkout shows as "هزینه ارسال:"; admin orders show "هزینه ثابت" as rate source.

= 3.2.0 - 2026-04-08 =
- Compatibility: Added broader compatibility improvements with newer WordPress/WooCommerce versions.
- Enhancement: Added automatic detection and auto-fix tools for city/state checkout fields, including an alternative loading method for improved reliability.
- Fix: Resolved an issue where Post and other courier services could intermittently not appear on the checkout page.
- Enhancement: Improved overall stability and compatibility with newer environments.
- New: AI-based shipping price estimation when Amadast/Post services are unavailable.
- New: Integrated a new AI-powered package type detection service (box_id + packing_id).
- New: Added Boxit shipping provider.
- New: Added in-person pickup option for local customers.
- New: Added advanced fallback customization when Amadast/Post APIs are unavailable (custom message or admin-defined fixed pricing).
- Enhancement: Improved plugin settings UX and added more customization options.
- Enhancement: Improved plugin logging (more structured, safer, and more actionable).
- Dev: In the WooCommerce wc-json order output, packing metadata can be identified via: box_id, packing_id, and source (ai / algo / manual).

= 2.1.2 - 2025-09-01 =
- Compatibility: Tested with WordPress 6.7.1 and WooCommerce 9.5.1. Requires PHP 8.0+ (compatible with 8.2+).
- Fix: Resolved PHP 8.2 deprecations by adding typed properties to AMDSP_Online_Method and removing dynamic property writes.
- Fix: Avoided deprecated intval() usage with null base; now properly handles defaults.
- Enhancement: Treat WooCommerce Cart/Checkout Blocks as compatible to remove false error notices.
- Enhancement: Fallback resolution from city name to city ID with Persian/Arabic character normalization for better Blocks support.
- Enhancement: Admin compatibility notices are now dismissible.
- Dev: Use AMDSP_VERSION for script versioning to improve cache-busting across releases.
- New: Completely redesigned settings panel UI with improved UX and Persian typography.
- New: OTP-based Amadast account authentication inside settings with account info view and logout.
- New: Logs tab with inline viewer (tail) and secure log download.
- New: Export/Import all plugin settings as JSON from the settings page.
- New: Advanced city picker for selecting free-shipping cities with search and multi-select.
- New: Auto-detect WooCommerce weight unit and normalize to grams; manual override option available.
- New: Default product dimensions (cm) setting to improve package-size detection when product dimensions are missing.
- New: Post-payment (pay-on-delivery) toggle with per-carrier options (Post, Tipax).
- New: Admin tool to ensure the Amadast shipping method exists in WooCommerce zones (with AJAX button).
- Change: Added extra-cost (fixed and percent) settings and "hide other methods when free shipping is available" toggle.
- Change: Added fallback shipping price when API is down (base + per-kilo extras) settings.
- Dev: Version upgrades include data migrations (2.1.2 to ensure shipping method; 2.1.3 to convert default dimensions from mm to cm when needed).

== Upgrade Notice ==



= 3.2.3 =
New: shipping display priority, max weight limits per provider, and custom conditional shipping methods.
Required for WordPress.org repository compliance: security escaping, readme metadata, and external services documentation.

= 3.2.2 =
Required for WordPress.org repository compliance: correct tested-up-to header and removal of external update checker.

= 2.1.2 =
Major update: redesigned settings, OTP login, logs and settings import/export, advanced city picker, weight unit auto-detect, post-payment, and admin shipping method tool. Also includes PHP 8.2 fixes and Blocks compatibility improvements. Update recommended.
