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

Обзор

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

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

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

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

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

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

Настройка

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

Зарегистрируйтесь как самозанятый через приложение Мой налог или на lknpd.nalog.ru
Запомните свой ИНН
Установите пароль для входа в личный кабинет на 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 прокси.

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

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

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

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

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

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

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

​Обзор

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

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

​Настройка

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

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

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

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

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

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

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

​Pending Verification

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

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

​Ограничения

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

​Настройка

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

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

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

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

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

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

Обзор

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

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

Настройка

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

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

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

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

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

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

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

Pending Verification

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

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

Ограничения

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

Настройка

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

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

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

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

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

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