cheque

Описание

cheque — Windows-ориентированный Python-проект для работы с кассовым оборудованием и связанными платёжными сценариями.

README рассчитан на двух читателей:

• разработчика, который сопровождает проект;
• будущего Codex-агента, которому нужно быстро понять структуру, точки входа и ограничения окружения.

Основной поток проекта:

• чтение JSON с составом чека;
• подготовка и печать чека через ККТ Штрих;
• обработка оплат и возвратов по эквайрингу;
• обработка оплат и возвратов по СБП;
• проверка кодов маркировки;
• запись служебных данных и логов.

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

Основные сценарии

check.py

Главная точка входа для печати чека.

Что делает:

• читает входные данные чека;
• создаёт объект ККТ;
• при необходимости проверяет маркировку;
• запускает оплату через pinpad_tbank.py или pinpad_OOP.py;
• запускает оплату или возврат через СБП;
• печатает служебные блоки оплаты;
• закрывает чек;
• сохраняет данные для последующей выгрузки.

Ожидает аргументы командной строки:

python .\check.py <path_to_receipt_dir> <receipt_name_without_json>

Скрипт использует файл:

<path_to_receipt_dir>\<receipt_name_without_json>.json

operation_shtrih.py

Отдельный служебный сценарий для операций ККТ и печати сопутствующих отчётов.

Поддерживает, по коду, как минимум:

• x_otchet
• z_otchet
• z_otchet_only
• repeat
• about
• open_box

Также умеет печатать данные по СБП и пинпаду, если это указано во входном JSON.

Запуск:

python .\operation_shtrih.py <path_to_receipt_dir> <receipt_name_without_json>

pinpad_tbank.py

Интеграция с терминалом Т-Банка через DualConnector и вспомогательный PosGui.

Особенности текущей реализации:

• конфигурация терминалов хранится в tbank.ini;
• общие таймауты и параметры PosGui также читаются из tbank.ini;
• таймаут обмена с терминалом возвращается как код ошибки 2000;
• используется отдельная логика GUI-диалогов для ручного взаимодействия с кассиром.

pinpad_OOP.py

Интеграция со сбербанковским пинпадом через COM-объект SBRFSRV.Server.

Что делает:

• выполняет оплату sale;
• выполняет возврат return_sale;
• умеет запускать сверку итогов reconciliation;
• умеет запускать отчётные операции x_otchet, z_otchet, full_otchet;
• возвращает код результата терминала в error;
• возвращает текст слипа или чека в text.

Как используется в проекте:

• в check.py выбирается, если pinpad_type не равен "tbank";
• в operation_shtrih.py используется для служебных операций и печати отчётов по пинпаду.

То есть это не запасной файл, а рабочая интеграция для сценариев эквайринга Сбербанка.

Скрипты и модули второго плана

• shtrih_OOP.py — работа с ККТ Штрих;
• SBP_OOP.py — СБП Сбербанк;
• alfabank_SBP.py — СБП через Альфа-Банк;
• pinpad_OOP.py — сбербанк сценарий пинпада;
• receipt_db.py — локальная БД чеков;
• dbf_make.py — формирование DBF;
• preparation_km_to_honest_sign.py — подготовка данных маркировки;
• logger_config.py — конфигурация логирования;
• my_rec.py — пример структуры входного чека.

Требования к окружению

Проект рассчитан на Windows.

По коду видно жёсткую привязку к локальным путям и окружению, например:

• d:\kassa\script_py\shtrih\
• d:\kassa\db_receipt\
• D:\files\
• локальные .env-файлы и сертификаты

Также ожидается наличие:

• установленного Python;
• доступа к COM/драйверам оборудования;
• кассового ПО и драйверов Штрих;
• сетевой доступности внешних банковских и терминальных сервисов;
• файлов сертификатов и ключей, которые не должны попадать в репозиторий.

Установка зависимостей

Зависимости перечислены в requirements.txt.

Установка:

python -m venv .venv
.\.venv\Scripts\activate
pip install -r .\requirements.txt

Ключевые используемые библиотеки:

• python-decouple
• python-dotenv
• requests
• requests-pkcs12
• PySimpleGUI-4-foss
• pywin32
• pyserial
• qrcode
• PyAutoGUI

Конфигурация

.env

В проекте используется локальный .env, который читают разные модули, в том числе:

• check.py
• SBP_OOP.py
• alfabank_SBP.py

Точный состав переменных зависит от используемого сценария. По коду точно видно, что в конфигурации могут использоваться:

• параметры минидисплея, например lcd_com;
• банковские URL и идентификаторы;
• пути к локальным БД;
• сервисные учётные данные и сертификаты.

Секреты, ключи и реальные значения в README не дублируются.

Ключи .env, которые видны по коду

Общие

• lcd_com — COM-порт минидисплея, используется в check.py

СБП Сбер

Используются в SBP_OOP.py:

• clientSecret
• clientID
• tid
• memberid
• sert_pass
• sert_name

СБП Альфа-Банк

Используются в alfabank_SBP.py:

• private_key_path
• alfa_alias
• alfa_tls_crt
• alfa_tls_key
• alfa_sbp_url
• alfa_sql_path

Также используются кассир-зависимые ключи:

• alfa_temno_kassir1
• alfa_qrcid_kassir1
• alfa_temno_kassir2
• alfa_qrcid_kassir2
• alfa_temno_kassir3
• alfa_qrcid_kassir3
• alfa_temno_kassir11
• alfa_qrcid_kassir11

По коду имя ключа строится динамически:

alfa_temno_<windows_username>
alfa_qrcid_<windows_username>

Если Windows-пользователь называется иначе, в .env должны существовать соответствующие пары ключей именно под его имя.

Что ещё стоит проверить вручную

Часть интеграций может ожидать дополнительные переменные в связанных внешних модулях или локальном окружении кассы. README фиксирует только то, что явно читается из текущего кода репозитория.

tbank.ini

Конфигурация T-Банка вынесена в отдельный INI-файл.

Структура:

[kassir1]
url=http://...
tid=...

[kassir11]
url=http://...
tid=...
posgui_addr=127.0.0.1:6000

[timeout]
operation_timeout_seconds=10
currency_code=643
posgui_addr=127.0.0.1:6000
posgui_codepage=windows-1251
posgui_connect_timeout_seconds=1.0
posgui_response_timeout_padding_seconds=5.0
posgui_enabled=1
posgui_required=0
posgui_manual_dialogs=1
posgui_result_dialog_timeout_seconds=3

Смысл секций:

• секции вида [kassirN] описывают конкретные терминалы или кассы;
• секция [timeout] хранит общие настройки времени ожидания и PosGui.

Формат входных данных

Входные данные подаются через JSON-файл чека.

Пример структуры можно посмотреть в my_rec.py.

По текущему коду важны, как минимум, такие поля:

• operationtype
• items
• sum-cash
• sum-cashless
• summ3
• PinPad
• pinpad_type
• SBP
• SBP-type
• number_receipt
• initial_sale_number
• initial_sale_date
• tag1021
• email
• perm_mode

Пример сокращённого JSON чека

Ниже не полный, а рабочий сокращённый пример структуры, собранный по my_rec.py и check.py:

{
  "id": "EL5532/02",
  "number_receipt": "5532/02",
  "date_create": "20260210",
  "operationtype": "sale",
  "tax-type": 1,
  "tag1021": "Кассир",
  "tag1203": "644917946302",
  "email": "",
  "perm_mode": 1,
  "PinPad": 0,
  "pinpad_type": "tbank",
  "SBP": 1,
  "SBP-type": "sber",
  "sum-cash": 0.0,
  "sum-cashless": 0.0,
  "summ3": 1267.0,
  "summ4": 0.0,
  "sum": 1267.0,
  "initial_sale_number": "",
  "initial_sale_date": "10.02.26",
  "cutter": "~S",
  "text-basement": [""],
  "items": [
    {
      "name": "Товар 1",
      "id": "1",
      "nn": "2310648306135",
      "seller": "П341|Кассир",
      "department": "",
      "comment": "",
      "artname": "Товар 1",
      "artnom": "310648",
      "katname": "Категория",
      "katnom": "61",
      "nds": "20",
      "gtd": "",
      "country": "*",
      "marktip": "5408",
      "barcode": "0104...",
      "quantity": 1,
      "price": 499.0,
      "fullprice": 499.0,
      "discount": 0.0,
      "taxtype": 1,
      "paymenttypesign": 4,
      "bonuswritedown": 0,
      "bonusaccrual": 25,
      "qr": "0104...",
      "qr_water": "",
      "paymentitemsign": 33
    }
  ],
  "km": [
    "0104..."
  ],
  "km_water": [],
  "bonusi": [
    "Бонусов будет начислено: 63"
  ],
  "bonus_items": [],
  "rn": "0009347016042401",
  "fn": "7384440900773851",
  "reqId": "8066e45b-1b88-4346-a664-55c379d3f3a5",
  "reqTimestamp": 1770729524199
}

Что важно:

• items должны содержать позиции чека в формате, который понимает shtrih_OOP.py;
• поля SBP, PinPad, summ3, sum-cashless управляют платёжными сценариями;
• для возврата используются operationtype = "return_sale", initial_sale_number и initial_sale_date;
• если включена проверка маркировки, должны быть корректно заполнены items[*].qr, items[*].marktip и список km.

Логи и данные

Проект пишет логи в файловую систему Windows.

По текущему коду используются, в частности:

• D:\files\ — основные логи;
• d:\kassa\db_receipt\ — локальные БД и служебные данные;
• текстовые и промежуточные файлы рядом со сценариями кассы.

Если каталогов нет или права доступа ограничены, часть сценариев не запустится.

Ограничения проекта

• Проект сильно зависит от конкретной инфраструктуры и путей.
• В коде есть прямые os.chdir(...) в рабочий каталог кассы.
• Логика рассчитана на запуск рядом с драйверами, JSON-файлами чеков и локальными БД.
• Часть модулей взаимодействует с внешним оборудованием и не может быть полноценно протестирована без стенда.

Быстрая проверка

Минимальная проверка синтаксиса:

python -m py_compile .\check.py .\operation_shtrih.py .\pinpad_tbank.py

Запуск основного сценария:

python .\check.py <path_to_receipt_dir> <receipt_name_without_json>

Запуск служебных операций ККТ:

python .\operation_shtrih.py <path_to_receipt_dir> <receipt_name_without_json>

Коды выхода

Ниже перечислены коды, которые явно видны в текущем коде проекта.

check.py

• 0 — сценарий завершился успешно
• 96 — ошибка инициализации или выполнения сценария СБП
• 98 — не пройдена проверка маркировки
• 99 — неизвестный тип операции
• 9888 — не удалось импортировать модуль проверки маркировки
• 9992 — не удалось импортировать pinpad_tbank.Tbank
• 9993 — не удалось импортировать receipt_db.Receiptinsql
• 9994 — не удалось импортировать alfabank_SBP.Alfa_SBP
• 9995 — не удалось импортировать SBP_OOP.SBP
• 9997 — не удалось импортировать pinpad_OOP.PinPad
• 9998 — не удалось импортировать модуль или класс Штрих

pinpad_tbank.py

• 0 — операция терминала завершилась успешно
• 2000 — пользовательская отмена или таймаут ожидания терминала
• 97 — ответ терминала не удалось интерпретировать однозначно

Для pinpad_tbank.py это именно внутренние коды клиента, которые потом поднимаются наружу в check.py.

operation_shtrih.py

• 0 — штатное завершение служебной операции

Остальные ошибки в этом сценарии, как правило, идут через исключение или драйвер ККТ, а не через отдельную таблицу кодов возврата.

Важная оговорка

В проекте есть и другие коды ошибок на уровне драйверов ККТ, банковских API и COM-интеграций. README фиксирует только те коды, которые явно управляются логикой самих Python-скриптов.

Типовые сценарии

1. Обычная продажа безналом через T-Банк

Минимальная идея входного JSON:

• operationtype = "sale"
• PinPad = 1
• pinpad_type = "tbank"
• sum-cashless > 0
• SBP = 0

Запуск:

python .\check.py d:\path\to\receipts EL5532_02

Что произойдёт:

• check.py прочитает EL5532_02.json;
• создаст объект ККТ;
• вызовет pinpad_tbank.py;
• дождётся результата терминала;
• напечатает служебный слип оплаты;
• закроет чек и завершится с кодом 0 либо с кодом ошибки пинпада.

2. Продажа через СБП

Минимальная идея входного JSON:

• operationtype = "sale"
• SBP = 1
• SBP-type = "sber" или SBP-type = "alfabank_bank"
• summ3 > 0
• PinPad = 0

Запуск:

python .\check.py d:\path\to\receipts EL5532_02

Что произойдёт:

• при SBP-type = "sber" будет использован SBP_OOP.py;
• при любом другом значении сейчас уходит ветка в alfabank_SBP.py;
• скрипт создаст заказ на оплату;
• дождётся подтверждения оплаты или отмены;
• напечатает информацию по СБП;
• затем закроет чек.

3. Возврат по СБП

Минимальная идея входного JSON:

• operationtype = "return_sale"
• SBP = 1
• summ3 > 0
• initial_sale_number заполнен
• initial_sale_date заполнен

Запуск:

python .\check.py d:\path\to\receipts EL5532_02

Что произойдёт:

• будет найдена исходная операция оплаты;
• по данным исходной продажи сформируется возврат;
• результат возврата будет распечатан в чеке.

4. X-отчёт или Z-отчёт ККТ

Во входном JSON достаточно указать:

• operationtype = "x_otchet" или operationtype = "z_otchet"

Запуск:

python .\operation_shtrih.py d:\path\to\receipts service_receipt

Что произойдёт:

• будет открыт сценарий служебной операции ККТ;
• напечатается X- или Z-отчёт;
• данные о кассе могут быть дополнительно сохранены в текстовый файл.

5. Ручной тест терминала T-Банк из CLI

pinpad_tbank.py можно запускать отдельно как ручной тестовый клиент.

Примеры:

python .\pinpad_tbank.py payment --amount 1.00 --section kassir1
python .\pinpad_tbank.py refund --amount 1.00 --section kassir1
python .\pinpad_tbank.py short_report --section kassir1
python .\pinpad_tbank.py posgui_info --section kassir1

Это полезно, когда нужно проверить терминал, PosGui или tbank.ini отдельно от полного кассового сценария.

Что стоит улучшить

• убрать жёстко зашитые пути в конфигурацию;
• формализовать схему входного JSON;
• отделить слой интеграций с оборудованием от сценарной логики;
• сократить количество побочных эффектов при импорте модулей;
• добавить отдельный документ с обязательными переменными .env для каждого платёжного сценария.