Бот для бухгалтеров

Telegram-бот для автоматизации работы бухгалтеров: получение данных из МойСклад, валидация и генерация документов (УПД, ТН) в форматах XML (ВерсФорм 5.03, 1С EnterpriseData 1.20) и Excel.

🔐 Многопользовательская система

Каждый пользователь работает со своим личным кабинетом МойСклад!

• Авторизация при первом запуске через /start
• Учетные данные шифруются и хранятся безопасно
• Возможность смены credentials через /change_credentials
• Выход из аккаунта через /logout

📖 Подробнее: docs/MULTI_USER_AUTH.md

🚀 Возможности

• 📦 Интеграция с МойСклад - автоматическое получение данных о заказах через API
• ✅ Валидация данных - проверка обязательных и желательных полей (ИНН, КПП, адреса, товары)
• 📄 Генерация XML - создание документов в форматах ВерсФорм 5.03 (УПД/ТН) и 1С EnterpriseData 1.20 (Реализация)
• 📊 Генерация Excel - выгрузка в форматы УПД и ТОРГ-12
• 🤖 Telegram интерфейс - удобное управление через бота

📋 Требования

• Python 3.10+
• Аккаунт МойСклад с API доступом
• Telegram Bot Token

🛠️ Установка

Вариант 1: Docker (рекомендуется) 🐳

Development

Преимущества:

• Изолированное окружение
• Простое развертывание
• Автоматический перезапуск
• Управление ресурсами

Linux/Mac:

# Клонирование
git clone <repository_url>
cd BUH_bot

# Настройка
cp .env.example .env
nano .env  # Укажите TELEGRAM_BOT_TOKEN

# Запуск
chmod +x start.sh
./start.sh

Windows:

git clone <repository_url>
cd BUH_bot

copy .env.example .env
notepad .env

start.bat

📖 Подробная документация: docs/DOCKER_QUICKSTART.md
📚 Полное руководство: docs/DOCKER_GUIDE.md

Production 🚀

Для production используется docker-compose с готовыми образами, мониторингом и автообновлением:

Компоненты:

• ✅ BUH Bot из registry (ghcr.io)
• ✅ Nginx reverse proxy
• ✅ Prometheus + Grafana мониторинг
• ✅ Watchtower автообновление
• ✅ Автоматический backup

Быстрый деплой:

# 1. Сборка и публикация образа
./build-image.sh

# 2. Настройка production
cp .env.prod.example .env.prod
nano .env.prod  # TELEGRAM_BOT_TOKEN и др.

# 3. Деплой
./deploy-prod.sh

Или через Makefile:

make prod-build  # Собрать образ
make prod-up     # Запустить production
make prod-logs   # Логи

Мониторинг:

• 📊 Grafana: http://your-server:3000
• 📈 Prometheus: http://your-server:9090
• 🐳 cAdvisor: http://your-server:8080

📖 Production документация: docs/PRODUCTION_DEPLOYMENT.md

Вариант 2: Локальная установка

1. Клонируйте репозиторий

git clone <repository_url>
cd BUH_bot

2. Создайте виртуальное окружение

python -m venv venv
source venv/bin/activate  # Linux/Mac
# или
venv\Scripts\activate  # Windows

3. Установите зависимости

pip install -r requirements.txt

4. Настройте переменные окружения

cp .env.example .env

Отредактируйте .env и укажите:

• TELEGRAM_BOT_TOKEN - токен Telegram бота

⚠️ ВАЖНО: MOYSKLAD_LOGIN и MOYSKLAD_PASSWORD больше не нужны!
Каждый пользователь вводит свои учетные данные МойСклад при первом запуске бота через /start.

5. Создайте Telegram бота
   • Откройте @BotFather в Telegram
   • Отправьте команду /newbot
   • Следуйте инструкциям и получите токен
   • Вставьте токен в .env

🚀 Запуск

Docker (рекомендуется)

# Linux/Mac
./start.sh

# Windows
start.bat

# Или напрямую
docker-compose up -d

Управление:

# Логи
docker-compose logs -f

# Остановка
docker-compose down

# Перезапуск
docker-compose restart

Локальный запуск

python bot.py

Первое использование

1. Отправьте /start боту в Telegram
2. Введите ваш логин от МойСклад
3. Введите ваш пароль от МойСклад (сообщение будет удалено)
4. Бот проверит учетные данные и сохранит их в зашифрованном виде
5. Начните работу!

Управление учетными данными

• /change_credentials - сменить логин/пароль
• /logout - выйти из аккаунта и удалить данные

📖 Использование

Команды бота

• /start - Начало работы / авторизация в МойСклад
• /help - Справка по использованию
• /logout - Выход из аккаунта (удаление учетных данных)
• /change_credentials - Смена логина/пароля МойСклад
• 🔍 Поиск отгрузки - Найти отгрузку по номеру заказа
• 📋 Список отгрузок - Показать последние отгрузки

Пример работы

1. Первый запуск:

   • Отправьте /start
   • Введите логин МойСклад
   • Введите пароль МойСклад (сообщение удаляется автоматически)

2. Поиск отгрузки:

   • Нажмите 🔍 Поиск отгрузки
   • Введите номер заказа (например: 951)

3. Работа с отгрузкой:

   • Выберите отгрузку из списка
   • Просмотрите результаты валидации
   • Выберите формат документа: 📄 XML или 📊 Excel
   • Для Excel бот автоматически рекомендует УПД или ТН в зависимости от типа контрагента
   • Получите готовый файл

📁 Структура проекта

BUH_bot/
├── .env                          # Переменные окружения (только TELEGRAM_BOT_TOKEN)
├── .env.example                  # Пример настроек
├── .gitignore                    # Игнорируемые файлы
├── requirements.txt              # Зависимости Python
├── config.py                     # Конфигурация приложения
├── bot.py                        # Основной файл бота (точка входа)
├── users.json                    # Зашифрованные данные пользователей (не в Git!)
├── .encryption_key               # Ключ шифрования (не в Git!)
│
├── docs/                         # Документация
│   ├── MULTI_USER_AUTH.md        # Описание системы авторизации
│   ├── PROJECT_STRUCTURE.md      # Структура проекта
│   └── CHANGES_2025-11-03.md     # История изменений
│
├── modules/                      # Модули приложения
│   ├── __init__.py
│   ├── moysklad_client.py        # API клиент МойСклад
│   ├── validator.py              # Валидация данных заказов
│   ├── xml_generator.py          # Генерация XML (ВерсФорм 5.03)
│   └── user_manager.py           # ⭐ NEW: Управление пользователями и credentials
│
├── scripts/                      # Вспомогательные скрипты
│   └── __init__.py
│
└── temp_documents/               # Временные файлы (не в Git!)

🔍 Валидация данных

Бот проверяет следующие данные:

Обязательные поля (❌ CRITICAL)

• Продавец: ИНН, КПП, наименование, юридический адрес
• Покупатель: ИНН, КПП, наименование, юридический адрес
• Товары: наименование, количество, цена, ставка НДС
• Заказ: номер, дата, сумма

Желательные поля (⚠️ WARNING)

• ОГРН/ОГРНИП
• Расчетный счет и банк
• Контактные данные
• Единицы измерения товаров

Валидация форматов

• ИНН: 10 цифр (юр. лица) или 12 цифр (ИП) + контрольная сумма
• КПП: 9 цифр
• ОГРН: 13 цифр (юр. лица) или 15 цифр (ИП)
• НДС: корректные ставки (0%, 10%, 20%, без НДС)
• Суммы: положительные числа, соответствие итогов

📄 Форматы документов

XML (ВерсФорм 5.03) - для ФНС

• УПД - Универсальный передаточный документ (Счет-фактура + ТОРГ-12)
• ТН - Товарная накладная (ТОРГ-12)

Соответствие приказу ФНС России для электронного документооборота.

XML (1С EnterpriseData 1.20) - для загрузки в 1С

• Документ реализации товаров и услуг - прямая загрузка в конфигурации 1С

📖 Подробная документация: docs/XML_1C_FORMAT.md

Excel

• УПД - Печатная форма с полными реквизитами
• ТОРГ-12 - Товарная накладная

🔐 Безопасность

⚠️ Важно:

• Никогда не коммитьте .env в репозиторий
• Храните учетные данные в безопасности
• Используйте HTTPS для всех API запросов
• Регулярно обновляйте зависимости

🐛 Устранение неполадок

Ошибка авторизации в МойСклад

• Проверьте правильность логина и пароля
• Убедитесь, что у аккаунта есть API доступ
• Проверьте подключение к интернету
• Попробуйте /change_credentials для смены данных

Ошибка: "Invalid token" (Telegram)

• Проверьте корректность токена в .env
• Убедитесь, что бот активен в BotFather

Потеря доступа к данным

⚠️ Если файл .encryption_key был удален или поврежден:

• Все сохраненные учетные данные станут недоступны
• Пользователям нужно заново пройти авторизацию через /start

Проблемы с многопользовательским доступом

• Убедитесь, что файл users.json доступен для записи
• Проверьте, что .encryption_key существует
• Смотрите логи бота для детальной информации

📚 Документация

• API МойСклад
• Форматы ФНС
• Telegram Bot API

🤝 Поддержка

При возникновении вопросов или проблем:

1. Проверьте раздел "Устранение неполадок"
2. Изучите PROJECT_PLAN.md для детального описания
3. Проверьте логи в консоли

📝 Лицензия

MIT License

🎯 Roadmap

• ✅ Многопользовательская система авторизации
• ✅ Шифрование учетных данных пользователей
• ✅ Интеграция с МойСклад API
• ✅ Валидация данных отгрузок
• ✅ Генерация XML (УПД 5.03)
• ✅ Генерация Excel через API МойСклад
• ✅ Умная рекомендация шаблонов (ТН для физ.лиц, УПД для юр.лиц/ИП)
• База данных для истории генерации
• Автоматические уведомления о новых заказах
• Генерация PDF печатных форм
• Электронная подпись XML документов
• Интеграция с 1С:Бухгалтерия
• OAuth авторизация МойСклад
• Webhook режим для бота

---

Сделано с ❤️ для бухгалтеров