Skip to main content

​
Обзор

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_ENABLEDfalseВключить интеграцию
NALOGO_INN—ИНН самозанятого (обязательно)
NALOGO_PASSWORD—Пароль от lknpd.nalog.ru (обязательно)
NALOGO_DEVICE_IDавтогенерацияID устройства для API (обычно не нужно менять)
NALOGO_STORAGE_PATH./nalogo_tokens.jsonПуть к файлу хранения токенов авторизации
NALOGO_QUEUE_CHECK_INTERVAL300Интервал проверки очереди (секунды)
NALOGO_QUEUE_RECEIPT_DELAY3Задержка между отправкой чеков из очереди (секунды)
NALOGO_QUEUE_MAX_ATTEMPTS10Максимум попыток отправки одного чека
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 очередь и ключи дедупликации теряются

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

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

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

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

  • Проверьте пароль от lknpd.nalog.ru (войдите вручную)
  • Удалите nalogo_tokens.json для принудительной реавторизации
  • Проверьте доступность lknpd.nalog.ru с сервера

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

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