=== Ferma OFD.ru ===
Contributors: ofdru
Tags: woocommerce, ofd, fiscalization, receipts, ferma
Requires at least: 6.0
Tested up to: 7.0
Requires PHP: 7.4
Stable tag: 2.0.0
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Этот модуль обеспечивает онлайн-регистрацию чеков через сервис Ferma от OFD.ru в соответствии с 54-ФЗ.

== Description ==

Ferma OFD.ru помогает формировать и передавать фискальные чеки через сервис Ferma от OFD.ru.

Плагин поддерживает основные сценарии работы интернет-магазина: чек предоплаты 100%, закрывающий чек полного расчета, возвраты, частичные возвраты, чеки коррекции, агентские реквизиты, коды маркировки, реестр чеков, журнал событий и проверку статусов через callback или API.

Для работы требуется подключение к сервису Ferma от OFD.ru и корректно заполненные настройки плагина. Фискализация выполняется на стороне сервиса Ferma; плагин передает данные из WooCommerce и ручных форм, а также сохраняет историю операций в административной панели WordPress.

Плагин протестирован на WordPress 7.0 и PHP 8.5.6. Минимальная поддерживаемая версия PHP указана в заголовке `Requires PHP`.

= Системные требования =

* WordPress 6.0 или выше.
* WooCommerce.
* PHP 7.4 или выше.
* Обязательное PHP-расширение mbstring.
* Доступ к сервису Ferma от OFD.ru.

Без расширения mbstring плагин не может быть активирован и не выполняет формирование или отправку чеков.

= Основные возможности =

* Формирование чеков по заказам WooCommerce.
* Поддержка цепочки «предоплата 100% → полный расчет».
* Ручные и автоматические сценарии формирования чеков по статусам заказа.
* Полные и частичные возвраты по фискальному остатку заказа.
* Произвольные чеки без привязки к заказам WooCommerce.
* Чеки коррекции с возможностью указать основание и реквизиты коррекции.
* Агентские реквизиты на уровне товарных позиций.
* Ручная работа с кодами маркировки и типом кода маркировки.
* Реестр чеков, журнал событий и диагностические инструменты.
* Callback и резервная проверка статусов через API.

= Внешний сервис и передаваемые данные =

Плагин взаимодействует с внешним сервисом Ferma от OFD.ru. Для формирования чеков в сервис могут передаваться данные, необходимые для фискализации: состав заказа, суммы, ставки НДС, электронная почта или телефон покупателя, данные кассира, агентские реквизиты, данные поставщика, коды маркировки и технические идентификаторы чеков.

Статусы чеков могут возвращаться в WordPress через callback или запрашиваться плагином через API. Администратор сайта отвечает за корректность настроек, реквизитов и правомерность применения выбранных налоговых и фискальных признаков.

== Installation ==

1. Загрузите папку плагина `wp-ferma-ofd` в каталог `/wp-content/plugins/` или установите архив через раздел «Плагины» в WordPress.
2. Убедитесь, что на сервере установлено и включено PHP-расширение mbstring.
3. Активируйте плагин в административной панели WordPress.
4. Убедитесь, что WooCommerce установлен и активен.
5. Откройте раздел Ferma OFD в административной панели.
6. Заполните параметры подключения к сервису OFD.ru Ferma, реквизиты кассира и настройки чеков.
7. При необходимости настройте автоматические сценарии, callback, агентские реквизиты, НДС и работу с кодами маркировки.
8. Выполните тест подключения и тестовую фискализацию.

= Чистая установка версии 2.0.0 =

Версия 2.0.0 является новой архитектурной линией плагина и устанавливается начисто. Автоматическая миграция настроек, истории чеков, журналов, автоматизаций, callback-токенов и других данных старой архитектуры не выполняется.

Перед установкой версии 2.0.0:

1. Сохраните необходимые данные и настройки старого плагина.
2. Деактивируйте старую версию.
3. Удалите каталог старого плагина.
4. Установите архив версии 2.0.0.
5. Активируйте плагин.
6. Заполните настройки подключения заново.
7. Выполните тест подключения и тестовую фискализацию.

== Frequently Asked Questions ==

= Нужен ли договор или доступ к OFD.ru Ferma? =

Да. Для работы плагина требуется доступ к сервису Ferma от OFD.ru и учетные данные для API.

= Плагин сам выполняет фискализацию? =

Нет. Плагин формирует данные чека и передает их в сервис Ferma от OFD.ru. Фискализация выполняется на стороне сервиса.

= Плагин ведет складской учет кодов маркировки? =

Нет. Плагин поддерживает ручное указание кодов маркировки для чеков, где это необходимо, но не ведет складской учет и не подбирает коды автоматически.

= Можно ли формировать частичные возвраты? =

Да. Частичный возврат выполняется вручную через расширенную форму чека по заказу. Перевод заказа в статус возврата запускает автоматический полный возврат доступного фискального остатка и не использует выбранные вручную позиции.

= Можно ли создавать произвольные чеки без заказа WooCommerce? =

Да. Произвольные чеки доступны в отдельном разделе и не связаны с заказами WooCommerce. В текущей версии для произвольного чека поддерживается один тип оплаты на весь чек; сумма оплаты рассчитывается автоматически по позициям.

= Что происходит при ошибке ККТ? =

Информация об ошибке сохраняется в реестре и журнале. Повторная отправка и анализ ошибки выполняются из административного интерфейса плагина.

== Screenshots ==

== Changelog ==

= 2.0.0 =
* Выпущена новая архитектурная версия интеграции с WooCommerce.
* Добавлена поддержка чеков предоплаты 100%, полного расчета, возвратов и коррекций.
* Добавлены частичные возвраты по заказам WooCommerce.
* Добавлена работа с агентскими реквизитами и кодами маркировки.
* Добавлены произвольные чеки без заказа WooCommerce.
* Добавлены реестр чеков, журнал событий, callback, проверка статусов и диагностика.
* Обновлена работа со ставками НДС 22% и устаревшими ставками 20% для специальных сценариев.
* Добавлена обязательная проверка PHP-расширения mbstring.

== Upgrade Notice ==

= 2.0.0 =
Версия 2.0.0 является новой архитектурной версией плагина. Автоматическая миграция настроек и данных из предыдущей публичной версии не выполняется. Перед установкой сохраните необходимые данные старой версии, деактивируйте и удалите старый плагин, после чего установите версию 2.0.0 как новый плагин.
