125 lines
4.6 KiB
Markdown
125 lines
4.6 KiB
Markdown
# FNS Receipt Service
|
||
|
||
Express-сервис на Node.js 22 для создания чеков через ФНС и отправки ссылки на чек по email.
|
||
|
||
## Локальный запуск
|
||
|
||
```bash
|
||
npm install
|
||
cp .env.example .env
|
||
npm start
|
||
```
|
||
|
||
Сервис запустится на порту из `PORT` или на `4000` по умолчанию.
|
||
|
||
Админ-интерфейс доступен по адресу:
|
||
|
||
```http
|
||
GET /admin
|
||
```
|
||
|
||
Для входа используется значение `API_PASS`. Через интерфейс можно смотреть локальный журнал чеков, синхронизировать последние чеки из кабинета ФНС, создавать чек вручную, проверять ФНС/SMTP и менять параметры сервиса без отдельного фронтенд-фреймворка.
|
||
|
||
Swagger UI доступен по адресу:
|
||
|
||
```http
|
||
GET /swagger
|
||
```
|
||
|
||
OpenAPI JSON доступен по адресу:
|
||
|
||
```http
|
||
GET /openapi.json
|
||
```
|
||
|
||
## Docker
|
||
|
||
Сборка образа:
|
||
|
||
```bash
|
||
docker build -t fns-receipt-service .
|
||
```
|
||
|
||
Запуск контейнера:
|
||
|
||
```bash
|
||
docker run --env-file .env -p 3000:3000 fns-receipt-service
|
||
```
|
||
|
||
## Переменные окружения
|
||
|
||
Заполните эти переменные в Timeweb Cloud в разделе переменных окружения:
|
||
|
||
```env
|
||
INN=123456789012
|
||
PASSWORD=your_fns_password
|
||
APPNAME=Название проекта
|
||
ADMIN_EMAIL=admin@example.com
|
||
SMTP_HOST=smtp.example.com
|
||
SMTP_PORT=587
|
||
SMTP_SECURE=false
|
||
SMTP_USER=noreply@example.com
|
||
SMTP_PASS=email_app_password
|
||
SMTP_MAIL_FROM=noreply@example.com
|
||
API_PASS=strong_api_password
|
||
JWT_SECRET=long_random_jwt_secret
|
||
ADMIN_SESSION_HOURS=12
|
||
PORT=3000
|
||
HOST=0.0.0.0
|
||
FNS_TIMEOUT_MS=30000
|
||
SMTP_TIMEOUT_MS=15000
|
||
```
|
||
|
||
`API_PASS` используется как пароль входа в админ-панель и должен совпадать с `api_pass` в старых запросах к `POST /api/v1/create-receipt`. После входа UI получает JWT и дальше отправляет запросы с `Authorization: Bearer <token>`.
|
||
|
||
`JWT_SECRET` лучше задавать отдельно от `API_PASS`. Если `JWT_SECRET` не задан, сервис подпишет JWT через `API_PASS`, но для продакшена это менее удобно при ротации пароля.
|
||
|
||
Настройки, измененные через UI, сохраняются в `data/config.json` и перекрывают значения из `.env`. Сетевые параметры `PORT` и `HOST` применятся после перезапуска процесса.
|
||
|
||
## Timeweb Cloud
|
||
|
||
Что заполнить при Docker-деплое:
|
||
|
||
| Поле | Значение |
|
||
| --- | --- |
|
||
| Dockerfile | `Dockerfile` |
|
||
| Порт | `3000` |
|
||
| Путь до директории проекта | `/fns-receipt-service` |
|
||
| Путь проверки состояния | `/health` |
|
||
|
||
Команду запуска для Docker-деплоя отдельно указывать не нужно: она уже задана в `Dockerfile` как `CMD ["node", "/app/server.js"]`.
|
||
|
||
## API
|
||
|
||
Проверка состояния:
|
||
|
||
```http
|
||
GET /health
|
||
```
|
||
|
||
Создание чека:
|
||
|
||
```http
|
||
POST /api/v1/create-receipt
|
||
Content-Type: application/json
|
||
|
||
{
|
||
"api_pass": "strong_api_password",
|
||
"email": "client@example.com",
|
||
"items": [
|
||
{
|
||
"id": "order-1",
|
||
"name": "Услуга",
|
||
"price": 1000,
|
||
"quantity": 1
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
Поле `email` обязательно: на этот адрес сервис отправит письмо со ссылкой на чек после успешного создания чека в ФНС.
|
||
|
||
Если чек создан в ФНС, но письмо клиенту не отправилось, API вернет `success: true`, `receiptCreated: true`, `emailSent: false`, `receiptId`, `printLink` и `technicalError`. Ошибка отправки сохранится в `error.json`.
|
||
|
||
Все успешно созданные чеки сохраняются в локальный журнал `data/receipts.json`, чтобы в UI была связь между чеком, email пользователя и позициями заказа. Синхронизация с ФНС подтягивает последние чеки из кабинета, но для старых чеков, созданных не этим сервисом, email пользователя может быть неизвестен.
|