> ## 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 и др.) не генерируют фискальные чеки.
</Warning>

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

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](https://lknpd.nalog.ru/)
2. Запомните свой **ИНН**
3. Установите **пароль** для входа в личный кабинет на `lknpd.nalog.ru`

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

### Шаг 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`.
</Warning>

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

Если 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 автоматически пойдёт через него.

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

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

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

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

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

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

```
[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).
</Note>

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

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

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