> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bedolagam.ru/llms.txt
> Use this file to discover all available pages before exploring further.

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

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

## Обзор

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

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

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

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

### Доставка чека покупателю

Раньше чек существовал только в личном кабинете ФНС. Начиная с `v3.65.0` он доходит до покупателя, а `v3.65.1` и `v3.66.0` добавили запасные пути:

| Способ | Когда используется |
| - | - |
| Ссылка на чек | Основной вариант |
| Файл в Telegram | Ссылка `lknpd.nalog.ru` часто недоступна клиентам через VPN |
| Письмо на почту | Когда Telegram недоступен |

Параллельно чек дублируется в топик `ADMIN_NOTIFICATIONS_NALOG_TOPIC_ID` с подробным блоком получателя: ID, имя, username, почта. Имя и почта копируются по тапу.

> [!NOTE]
>
> Адресат чека — **покупатель**, а не одаряемый: при покупке подарочной подписки чек уходит тому, кто заплатил (`v3.66.0`).
>
> Если чек отправлен вручную из админки, покупателю он всё равно доставляется.

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

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

## Настройка

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

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

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

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

```env theme={null}
NALOGO_ENABLED=true
NALOGO_INN=123456789012
NALOGO_PASSWORD=your_lknpd_password
```

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

```bash theme={null}
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 ([подробнее](/getting-started/proxy-setup#прокси-для-nalogru)) |
| `ADMIN_NOTIFICATIONS_NALOG_TOPIC_ID` | — | ID топика для уведомлений в Telegram |

> [!WARNING]
>
> Для работы интеграции необходимы все три параметра: `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` убедитесь что директория с файлом примонтирована:

```yaml theme={null}
volumes:
  - ./data:/app/data
```

И в `.env`:

```env theme={null}
NALOGO_STORAGE_PATH=./data/nalogo_tokens.json
```

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

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

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

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

### Настройка

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

```env theme={null}
# Выделенный прокси для 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 автоматически пойдёт через него.

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

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

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

> [!WARNING]
>
> 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)
```

> [!NOTE]
>
> Подробнее о настройке SOCKS-прокси для бота — в разделе [SOCKS5 прокси](/getting-started/proxy-setup).

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

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

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 ФНС может быть временно недоступен — это нормально, чеки отправятся позже
* Проверьте логи на повторяющиеся ошибки
* Используйте кнопку принудительной обработки в мониторинге


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.