Фискальные чеки (NaloGO)

Автоматическая отправка чеков в ФНС для самозанятых через lknpd.nalog.ru

Обзор

NaloGO — интеграция с API Федеральной налоговой службы для самозанятых (режим НПД). При каждом успешном платеже через YooKassa бот автоматически создает фискальный чек в личном кабинете налогоплательщика lknpd.nalog.ru.

Интеграция работает только с YooKassa. Остальные платежные системы (CryptoBot, Telegram Stars, CloudPayments, Freekassa и др.) не генерируют фискальные чеки.

Как это работает

1. Пользователь оплачивает через YooKassa
2. Webhook подтверждает успешный платеж, баланс зачисляется
3. Бот формирует данные чека (название услуги, сумма, дата)
4. Чек отправляется в API lknpd.nalog.ru
5. ФНС возвращает UUID чека, который сохраняется в БД

Что содержит чек

Поле	Значение
Название услуги	Генерируется из шаблонов PAYMENT_SERVICE_NAME и PAYMENT_BALANCE_DESCRIPTION
Сумма	Сумма платежа в рублях
Тип дохода	От физического лица
Количество	1
Время	Московское время (UTC+3)

Настройка

Шаг 1: Регистрация как самозанятый

1. Зарегистрируйтесь как самозанятый через приложение Мой налог или на lknpd.nalog.ru
2. Запомните свой ИНН
3. Установите пароль для входа в личный кабинет на lknpd.nalog.ru

Отдельная регистрация API-ключа не требуется. Бот использует ваш ИНН и пароль для авторизации в ЛК налогоплательщика.

Шаг 2: Настройка .env

NALOGO_ENABLED=true
NALOGO_INN=123456789012
NALOGO_PASSWORD=your_lknpd_password

Шаг 3: Перезапуск бота

docker compose up -d --build

Переменные окружения

Переменная	По умолчанию	Описание
NALOGO_ENABLED	false	Включить интеграцию
NALOGO_INN	—	ИНН самозанятого (обязательно)
NALOGO_PASSWORD	—	Пароль от lknpd.nalog.ru (обязательно)
NALOGO_DEVICE_ID	автогенерация	ID устройства для API (обычно не нужно менять)
NALOGO_STORAGE_PATH	./nalogo_tokens.json	Путь к файлу хранения токенов авторизации
NALOGO_QUEUE_CHECK_INTERVAL	300	Интервал проверки очереди (секунды)
NALOGO_QUEUE_RECEIPT_DELAY	3	Задержка между отправкой чеков из очереди (секунды)
NALOGO_QUEUE_MAX_ATTEMPTS	10	Максимум попыток отправки одного чека
NALOGO_PROXY_URL	—	SOCKS прокси для nalog.ru (подробнее)
ADMIN_NOTIFICATIONS_NALOG_TOPIC_ID	—	ID топика для уведомлений в Telegram

Для работы интеграции необходимы все три параметра: NALOGO_ENABLED=true, NALOGO_INN и NALOGO_PASSWORD.

Очередь чеков

Если API ФНС временно недоступен (503, техработы, таймауты), чек автоматически добавляется в очередь Redis и повторяется позже.

Как работает очередь

• Фоновый процесс проверяет очередь каждые NALOGO_QUEUE_CHECK_INTERVAL секунд (по умолчанию 5 минут)
• Между отправкой чеков — пауза NALOGO_QUEUE_RECEIPT_DELAY секунд
• Чеки никогда не удаляются из очереди — повторяются бесконечно с увеличением счетчика попыток
• При успешной отправке всей очереди — уведомление администратору

Защита от дублирования

• Redis-ключ nalogo:created:{payment_id} (TTL 30 дней) предотвращает повторное создание чека
• Redis-ключ nalogo:queued:{payment_id} (TTL 7 дней) предотвращает дублирование в очереди
• Проверка поля receipt_uuid в БД перед созданием

Pending Verification

Если авторизация прошла успешно, но запрос на создание чека получил таймаут — чек мог быть создан на стороне ФНС. Такие чеки попадают в отдельную очередь Pending Verification и требуют ручной проверки в ЛК налогоплательщика.

Мониторинг (админ-панель)

В разделе мониторинга бота доступна информация о NaloGO:

• Очередь: количество чеков, общая сумма, статус фонового процесса
• Pending Verification: чеки, требующие ручной проверки
• Действия:
  • Принудительная обработка очереди
  • Просмотр pending-чеков
  • Пометка как проверенные / повторная отправка
  • Очистка всех pending

Хранение токенов

Токены авторизации в API ФНС хранятся в файле nalogo_tokens.json. При контейнеризации этот файл должен быть на персистентном томе, иначе авторизация будет выполняться заново при каждом перезапуске.

В docker-compose.yml убедитесь что директория с файлом примонтирована:

volumes:
  - ./data:/app/data

И в .env:

NALOGO_STORAGE_PATH=./data/nalogo_tokens.json

Ограничения

Ограничение	Описание
Только YooKassa	Чеки создаются только при оплате через YooKassa
Только самозанятые	Работает только с режимом НПД (не ИП, не ООО)
Один аккаунт	Один ИНН/пароль — предполагается один оператор
Нет автоотмены	При возврате платежа чек не отменяется автоматически (нужно вручную в ЛК)
Без данных покупателя	Чеки создаются как доход от анонимного физлица
Файловое хранение токенов	Требуется персистентный том в Docker
Зависимость от Redis	При потере данных Redis очередь и ключи дедупликации теряются

Прокси для nalog.ru

Если сервер бота находится за пределами России или lknpd.nalog.ru недоступен напрямую, трафик к API налоговой можно маршрутизировать через SOCKS-прокси.

Настройка

Добавьте в .env:

# Выделенный прокси для nalog.ru
NALOGO_PROXY_URL=socks5://proxy-host:1080

# С авторизацией
NALOGO_PROXY_URL=socks5://username:password@proxy-host:1080

# Удалённое разрешение DNS через прокси (рекомендуется)
NALOGO_PROXY_URL=socks5h://proxy-host:1080

Если NALOGO_PROXY_URL не указан, но настроен общий PROXY_URL (для Telegram API) — трафик к nalog.ru автоматически пойдёт через него.

Схема socks5h:// выполняет DNS-резолвинг на стороне прокси-сервера. Это полезно, когда DNS lknpd.nalog.ru не резолвится локально.

Поддерживаемые схемы

Схема	Описание
socks5://	SOCKS5 с локальным DNS
socks5h://	SOCKS5 с удалённым DNS (рекомендуется)
socks4://	SOCKS4

HTTP/HTTPS прокси не поддерживаются. Используйте только SOCKS-протоколы.

Проверка работоспособности

В логах бота при старте появится:

[info] Nalogo proxy configured proxy_url=socks5://***@proxy-host:1080 source=NALOGO_PROXY_URL

Если используется общий PROXY_URL:

[info] Nalogo proxy configured proxy_url=socks5://***@proxy-host:1080 source=PROXY_URL (fallback)

Подробнее о настройке SOCKS-прокси для бота — в разделе SOCKS5 прокси.

Устранение проблем

Чеки не создаются

1. Проверьте NALOGO_ENABLED=true в .env
2. Убедитесь что NALOGO_INN и NALOGO_PASSWORD заполнены
3. Проверьте логи бота на ошибки авторизации NaloGO
4. Убедитесь что оплата идет через YooKassa (другие провайдеры не поддерживаются)

Ошибка авторизации

• Проверьте пароль от lknpd.nalog.ru (войдите вручную)
• Удалите nalogo_tokens.json для принудительной реавторизации
• Проверьте доступность lknpd.nalog.ru с сервера
• Если сервер за рубежом — настройте NALOGO_PROXY_URL через SOCKS-прокси в РФ

Очередь растет

• API ФНС может быть временно недоступен — это нормально, чеки отправятся позже
• Проверьте логи на повторяющиеся ошибки
• Используйте кнопку принудительной обработки в мониторинге