🧾 FNS Receipt Service

Автоматизированный сервис для создания чеков самозанятого через ФНС (Мой налог) с отправкой детализированных чеков клиентам по email

---

📋 Содержание

• Описание
• Возможности
• Установка
• Настройка
• Использование
• API Reference
• Переменные окружения
• Ограничения и особенности
• FAQ
• Лицензия

---

🎯 Описание

FNS Receipt Service — Node.js сервис для автоматического создания чеков самозанятого через API ФНС («Мой налог») и отправки клиентам детализированных чеков по email.

Сервис учитывает ограничения официального API ФНС и использует практику, применяемую платёжными системами.

Ключевая особенность

⚠️ Ограничение API ФНС: официальный API самозанятых не поддерживает несколько позиций в одном чеке.

Используется гибридный подход:

• В ФНС → отправляется одна агрегированная позиция с общей суммой дохода
• Клиенту по email → отправляется детализированный HTML‑чек со всеми товарами/услугами

Это полностью соответствует требованиям ФНС: налоговый учёт ведётся по сумме дохода, а не по товарным позициям.

Если вы обнаружили баг или есть идея для улучшения сервиса, пожалуйста, создайте Issue в репозитории.

---

✨ Возможности

• ✅ Создание чеков самозанятого через официальный API ФНС
• ✅ Retry‑механизм при временных ошибках ФНС (до 3 попыток)
• ✅ Детализированные HTML‑чеки для клиентов
• ✅ Отправка официальной ссылки на чек ФНС
• ✅ Защита API паролем
• ✅ Простая HTTP‑интеграция с любыми сервисами

---

🚀 Установка

Требования

• Node.js 16.x+
• npm или yarn
• Активный статус самозанятого в «Мой налог»

Установка

git clone https://github.com/ga1maz/fns-receipt-service.git
cd fns-receipt-service
npm install

Основные зависимости

{
  "express": "^4.18.0",
  "lknpd-nalog-api": "^1.0.0",
  "nodemailer": "^6.9.0",
  "dotenv": "^16.0.0"
}

---

⚙️ Настройка

1. Создание .env

cp .env.example .env

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

# === ФНС (Мой налог) ===
INN=123456789012
PASSWORD=your_fns_password

# === Приложение ===
APPNAME=Моя компания

# === SMTP ===
SMTP_HOST=smtp.gmail.com
SMTP_PORT=587
SMTP_USER=noreply@example.com
SMTP_PASS=app_password
SMTP_MAIL_FROM=noreply@example.com

# === Безопасность ===
API_PASS=your_secure_password_here
PORT=4000

Поддерживаются любые SMTP‑провайдеры (Gmail, Яндекс, Mail.ru и др.). Для Gmail рекомендуется использовать пароль приложения.

---

🎮 Использование

Запуск сервера

node index.js

Сервер запускается на:

http://localhost:4000

Проверка состояния сервиса

GET /health

Сервис возвращает состояние подключения и возможные ошибки:

{
  "status": "ok",          // общий статус сервера (ok, degraded, error)
  "connect_to_fns": "ok", // соединение с API ФНС
  "smtp": "ok"             // статус SMTP
}

Примеры возможных ошибок health:

• connect_to_fns: error — проблемы с авторизацией или доступностью API ФНС
• smtp: error — проблемы с подключением к SMTP серверу (неверный логин/пароль, блокировка сервера)
• status: degraded — сервис работает, но есть неполадки с одним из сервисов

Если вы что-то не заметили или есть идеи для доработки, создайте Issue в репозитории.

---

📡 API Reference

POST /api/v1/create-receipt

Создаёт один чек дохода в ФНС на общую сумму всех позиций и отправляет клиенту детализированный HTML‑чек по email.

🔐 Авторизация

Пароль передаётся в теле запроса:

{
  "api_pass": "..."
}

Значение сравнивается с API_PASS из .env.

📥 Request Body

{
  "api_pass": "your_secure_password_here",
  "email": "client@example.com",
  "items": [
    {
      "id": "sku-001",
      "name": "Консультация по налогам",
      "price": 5000,
      "quantity": 1
    }
  ]
}

⚙️ Логика обработки

• Общая сумма:

Σ (price × quantity)

• В ФНС отправляется:

  • name → APPNAME
  • amount → общая сумма
  • quantity → 1

• При ошибке ФНС:

  • до 3 попыток
  • задержка 2 секунды между попытками

📤 Response (Success)

HTTP 200 OK

{
  "success": true,
  "receiptId": "200uhagtun",
  "printLink": "https://lknpd.nalog.ru/api/v1/receipt/INN/receiptId/print"
}

Поля totalAmount и email не возвращаются в ответе.

❌ Ошибки

400 — Неверные данные

{ "error": "Неверные данные" }

401 — Unauthorized

{ "error": "Unauthorized" }

500 — Internal Server Error

{ "error": "Не удалось создать чек" }

---

🧩 Переменные окружения (.env)

Переменная	Назначение
API_PASS	Пароль доступа к API
INN	ИНН самозанятого
PASSWORD	Пароль «Мой налог»
APPNAME	Название в чеке ФНС
SMTP_HOST	SMTP сервер
SMTP_PORT	SMTP порт
SMTP_USER	SMTP логин
SMTP_PASS	SMTP пароль
SMTP_MAIL_FROM	Email отправителя
PORT	Порт сервера

---

📝 Ограничения и особенности

• ❗ Один запрос = один чек дохода
• ❗ Детализация не передаётся в ФНС, только в email
• ✔️ Поддержка дробных количеств
• ✔️ HTML‑чек с таблицей позиций
• ✔️ Официальная ссылка ФНС

---

❓ FAQ

Это законно? Да. ФНС учитывает доход суммарно, детализация — дополнительный сервис.

Можно ли создать несколько чеков на один платёж? Нет. Один платёж = один чек.

Нужно ли хранить receiptId? Рекомендуется для поддержки клиентов и учёта.

Нужен ли IP РФ? Да, API ФНС работает только с IP РФ.

---

📄 Лицензия

MIT License © 2026

---

Сделано с ❤️ для самозанятых