Создание модулей онлайн-касс

Модули онлайн-касс интегрируют платформу BILLmanager с фискальными регистраторами и облачными кассами для автоматической отправки чеков в ОФД. Каждый модуль состоит из XML-описания конфигурации и исполняемого скрипта, который обрабатывает команды платформы. Модуль отвечает за проверку подключения, формирование данных чека, отправку запроса во внешнюю систему и обновление статуса фискализации в базе данных BILLmanager.

Общие сведения

Модуль онлайн-касс обеспечивает автоматическую фискализацию расчетов и передачу данных о чеках оператору фискальных данных (ОФД)

Каталог установки: /usr/local/mgr5/cashregister/

Поддерживаемые возможности (из SDK billmgr.modules.cashregister):

check_connection — проверка подключения;
send_receipt — отправка чека;
check_receipt — проверка статуса чека;
expense_receipt — поддержка расходных чеков;
refund_receipt — поддержка чеков возврата;
manual_monthly_send — ручная ежемесячная отправка.

Команды --command:

check_connection;
send_receipt;
check_receipt;
другие команды (например, refund_receipt) — по необходимости.

Пример вызова модуля онлайн-кассы

/usr/local/mgr5/cashregister/crmodulkassa --command send_receipt --cash_register 1

Команда (`--command`)	Параметры	Вход (stdin)	Выход (stdout)	Обязательность / Примечание
`features`	—	—	XML с `<features>`	Обязательная
`check_connection`	—	XML-файл с параметрами кассы.	`<doc/>` или ошибка	Если объявлен `Feature.CHECK_CONNECTION`
`send_receipt`	`--cash_register <id>`, `--payment_receipt <id_чека>`	—	—	Если объявлен `Feature.send_receipt`. Отправляет чек со статусом `ReceiptStatus.New`
`check_receipt`	`--cash_register <id>`, `--payment_receipt <id_чека>`	—	—	Если объявлен `Feature.CHECK_RECEIPT`. Проверяет статус чека во внешней системе
`send_prepared_receipt`	`--cash_register <id>`, `--payment_receipt <id_чека>`	—	—	Если объявлен `Feature.PREPARED_RECEIPT`. Отправляет чек со статусом `ReceiptStatus.Prepare`
`form_tune`	—	XML-файл текущей формы.	Изменённый XML-файл формы.	Если объявлен `Feature.FORM_TUNE`

Возможности-флаги (не добавляют новых команд, только влияют на интерфейс BILLmanager):

Feature.EXPENSE_RECEIPT — поддержка чеков расхода (признак, что модуль умеет их регистрировать);
Feature.REFUND_RECEIPT — поддержка чеков возврата для платежей без чека прихода;
Feature.MANUAL_MONTHLY_SEND — поддержка ручной отправки чеков по услугам (чеки создаются в статусе Prepare).

Пояснения к XML-файлу модулей онлайн-касс

Команда `features` — выход (stdout)

Модуль возвращает XML-документ со списком поддерживаемых возможностей. Формируется автоматически через метод features() класса CashregisterModule, который собирает все возможности из self._features и self._commands.

<doc>
	<features>
		<feature name="check_connection"/>
		<feature name="send_receipt"/>
		<feature name="check_receipt"/>
		<feature name="send_prepared_receipt"/>
		<feature name="expense_receipt"/>
		<feature name="refund_receipt"/>
		<feature name="manual_monthly_send"/>
		<feature name="form_tune"/>
	</features>
</doc>

Команда check_connection — вход (stdin)

При создании или редактировании онлайн-кассы BILLmanager вызывает модуль с этой командой, передавая на стандартный ввод XML-форму с текущими параметрами кассы (те, что описаны в metadata name="cashregister.edit.XXX"):

Пример входного XML

<doc>
	<url>https://api.modulkassa.ru</url>
	<username>test_user</username>
	<password>secret</password>
	<retailpointid>123</retailpointid>
</doc>

Выход:

при успешном подключении — пустой XML <doc/>;
при ошибке:
- XML с описанием ошибки (стандартный формат):

<doc>
	<error type="msg_error_*" value="*" object="*"/>
</doc>

- XML для конкретного поля:

<doc>
	<error type="value" object="url" value="" desc="desc_*"/>
</doc>

Команда form_tune — вход и выход

Вызывается при открытии формы редактирования онлайн-кассы. Модуль получает на stdin текущий XML-файл формы и может изменить его (добавить поля, подсказки, атрибуты).

Пример входного XML (стандартная форма)

<doc>
	<form>
		<field name="url">
			<input type="text" name="url" required="yes"/>
		</field>
		<field name="username">
			<input type="text" name="username" required="yes"/>
		</field>
		<field name="password">
			<input type="password" name="password" required="yes" private="yes"/>
		</field>
	</form>
</doc>

Пример изменённого XML (добавлено поле retailpointid)

<doc>
	<form>
		<field name="url">
			<input type="text" name="url" required="yes" placeholder="https://..."/>
		</field>
		<field name="username">
			<input type="text" name="username" required="yes"/>
		</field>
		<field name="password">
			<input type="password" name="password" required="yes" private="yes"/>
		</field>
		<field name="retailpointid">
			<input type="text" name="retailpointid" required="yes"/>
		</field>
	</form>
</doc>

Команды send_receipt, check_receipt, send_prepared_receipt

Команды не используют stdin или stdout для передачи данных чека. Вместо этого BILLmanager передаёт в командной строке параметры:

--cash_register <id> — идентификатор онлайн-кассы;
--payment_receipt <id> — идентификатор чека (из таблицы payment_receipt).

Модуль должен самостоятельно (через БД или через misc.Mgrctl("payment_receipt.info", elid=id)) получить все данные чека: позиции, суммы, налоги, контактные данные покупателя и т. д. После взаимодействия с внешним API модуль обновляет статус чека в BILLmanager с помощью вызовов:

payment_receipt.wait — чек поставлен в очередь на фискализацию;
payment_receipt.success — чек успешно фискализирован (передаёт fn_number, fiscal_document_number, fiscal_document_attribute, receiptdate, receiptdate_tz);
payment_receipt.error — произошла ошибка (передаёт error_message).

Пример вызова через mgrctl или напрямую

/usr/local/mgr5/cashregister/crmodulkassa --command send_receipt --cash_register 1 --payment_receipt 123

Важно:

send_receipt используется для чеков со статусом ReceiptStatus.New (обычные чеки прихода);
send_prepared_receipt — для чеков со статусом ReceiptStatus.Prepare (чеки, созданные вручную или отложенные);
check_receipt — для чеков со статусом ReceiptStatus.Wait (проверка состояния ранее отправленного чека).

Возможности без отдельных команд

expense_receipt — BILLmanager разрешает создание расходных чеков (чеки с типом Buy, BuyRefund, BuyCorrection). Модуль обрабатывает их через send_receipt, send_prepared_receipt, но в данных чека будет соответствующий ReceiptType;
refund_receipt — разрешает создание чеков возврата для платежей, у которых ещё нет чека прихода. Обрабатывается аналогично expense_receipt;
manual_monthly_send — добавляет в интерфейсе возможность ручной отправки отложенных чеков (статус Prepare). Команда используется send_prepared_receipt.

Примечания по разработке

все callable-команды (кроме features) должны быть добавлены через _add_callable_feature() или декоратор @callable_feature;
обязательные команды (по умолчанию в __init__): check_connection, send_receipt, check_receipt. Остальные — опционально;
типы чеков и статусы определены в перечислениях ReceiptType и ReceiptStatus . При сохранении статуса через payment_receipt.success обязательно передавать фискальные атрибуты;
параметры кассы, помеченные в XML как private="yes", хранятся зашифрованными, но в check_connection передаются открыто;
параметры подключения, содержащие чувствительные данные (например, API-ключи или пароли), должны быть помечены в XML-форме атрибутом crypted="yes" ;
BILLmanager хранит параметры в базе данных в зашифрованном виде, но передаёт их в модуль в открытом виде на stdin исключительно при выполнении команды check_connection для возможности тестового подключения;
для логирования работы модуля рекомендуется использовать директорию /usr/local/mgr5/var/, а при разработке на Python — стандартный модуль billmgr.logger .

Механизм работы модуля

Этапы работы с модулем онлайн-кассы в BILLmanager:

Первоначальная настройка:
1. Установка модуля.
2. Добавление подключения к кассе.
Процесс работы с чеками:
1. Создание чека при оплате или вручную.
2. Отправка чека во внешнюю систему.
3. Обновление статуса чека в платформе.

Установите модуль:

вручную, если он представлен набором файлов;
из стандартного репозитория при помощи пакетного менеджера.

После установки модуль становится доступен для выбора при создании онлайн-кассы в BILLmanager.

Платформа опрашивает каждый модуль при запуске, чтобы узнать о поддерживаемых возможностях. Это исключает неподдерживаемые вызовы и определяет поведение форм при настройке кассы.

Структура модуля

Стандартный набор файлов модуля выглядит следующим образом:

Имя файла	Описание	Обязательный	Произвольное имя
/usr/local/mgr5/cashregister/crXXX	Основной скрипт модуля	Да	Нет
/usr/local/mgr5/etc/xml/billmgr_mod_crXXX.xml	XML-описание модуля	Да	Нет

Где XXX — название модуля, указанное латиницей. Если основной скрипт имеет расширение файла, оно также включается в имя модуля. Например, если скрипт называется crmodulkassa.py, имя модуля — modulkassa.py.

Описание XML

Наименование файла должно иметь вид billmgr_mod_crXXX.xml, где XXX — имя модуля. Файл копируется в каталог /usr/local/mgr5/etc/xml/. Файл содержит описание самого модуля (описывается как плагин), а также описание дополнительных форм и сообщений:

Пример XML-файла

<mgrdata>
  <plugin name="crcustom">
    <group>payment_cash_register</group>
    <author>Ваша компания</author>
    <params>
      <priority lang="ru">100</priority>
      <priority lang="en">100</priority>
    </params>
    <msg name="desc_short" lang="ru">Модуль КастомКасса</msg>
    <msg name="desc_full" lang="ru">Интеграция с облачной кассой КастомКасса</msg>
  </plugin>

  <metadata name="payment_cash_register.edit.crcustom" type="form">
    <form>
      <page name="methodprops">
        <field name="api_url">
          <input name="api_url" type="text" check="url" required="yes"/>
        </field>
        <field name="api_key">
          <input name="api_key" type="text" required="yes" private="yes" crypted="yes"/>
        </field>
        <field name="retail_point_id">
          <input name="retail_point_id" type="text" required="yes"/>
        </field>
      </page>
    </form>
  </metadata>

  <lang name="ru">
    <messages name="payment_cash_register.include">
      <msg name="module_crcustom">КастомКасса</msg>
      <msg name="crcustom">КастомКасса</msg>
    </messages>
    <messages name="payment_cash_register.edit.crcustom">
      <msg name="api_url">Адрес API</msg>
      <msg name="hint_api_url">URL для подключения к шлюзу кассы</msg>
      <msg name="api_key">Секретный ключ</msg>
      <msg name="hint_api_key">Ключ авторизации из личного кабинета</msg>
      <msg name="retail_point_id">Идентификатор торговой точки</msg>
      <msg name="hint_retail_point_id">Уникальный код точки продаж в системе кассы</msg>
    </messages>
    <messages name="msgerror">
      <msg name="msg_error_invalid_key">Неверный секретный ключ</msg>
      <msg name="msg_error_connection_failed">Ошибка подключения к серверу кассы</msg>
    </messages>
  </lang>
</mgrdata>

В примере элемент plugin отвечает за описание самого модуля. Свойство name совпадает с именем модуля. Элемент group со значением cash_register указывает, что модуль используется для онлайн-касс.

Элемент metadata с именем cashregister.edit.XXX отвечает за дополнительные поля модуля при добавлении и настройке кассы. Разместите поля в элементе <page name="methodprops"> для корректного отображения на формах в BILLmanager. Атрибут private="yes" запрещает вывод значения в открытом виде при экспорте настроек и используется для секретных данных, таких как ключи API или пароли.

Блок <messages name="payment_cash_register.include"> задаёт отображаемое имя модуля в интерфейсе выбора касс.

Блок <messages name="payment_cash_register.edit.crcustom"> содержит подписи и подсказки для полей формы настроек.

Блок <messages name="msgerror"> определяет тексты ошибок, которые модуль может вернуть в ответе команды.

После создания или изменения XML-файла перезагрузите платформу для применения изменений:

/usr/local/mgr5/sbin/mgrctl -m billmgr exit

Пример модуля (Python)

Пример модуля онлайн-кассы BILLmanager для фискализации чеков через "Модулькасса" с использованием Python SDK доступен в открытом репозитории github.

Может быть полезно

Связанные статьи: