671 lines
16 KiB
JSON
671 lines
16 KiB
JSON
{
|
||
"openapi": "3.1.0",
|
||
"info": {
|
||
"title": "FNS Receipt Service API",
|
||
"version": "1.0.0",
|
||
"description": "API сервиса создания чеков ФНС, админ-панели, настроек и диагностики."
|
||
},
|
||
"servers": [
|
||
{
|
||
"url": "/",
|
||
"description": "Current host"
|
||
}
|
||
],
|
||
"tags": [
|
||
{
|
||
"name": "Service",
|
||
"description": "Состояние сервиса"
|
||
},
|
||
{
|
||
"name": "Receipts",
|
||
"description": "Создание чеков"
|
||
},
|
||
{
|
||
"name": "Admin",
|
||
"description": "Админские методы UI"
|
||
}
|
||
],
|
||
"components": {
|
||
"securitySchemes": {
|
||
"AdminBearer": {
|
||
"type": "http",
|
||
"scheme": "bearer",
|
||
"bearerFormat": "JWT",
|
||
"description": "JWT из POST /admin/api/login"
|
||
},
|
||
"AdminPassword": {
|
||
"type": "apiKey",
|
||
"in": "header",
|
||
"name": "x-admin-password",
|
||
"description": "Legacy: значение API_PASS"
|
||
}
|
||
},
|
||
"schemas": {
|
||
"Health": {
|
||
"type": "object",
|
||
"properties": {
|
||
"status": {
|
||
"type": "string",
|
||
"examples": [
|
||
"ok"
|
||
]
|
||
}
|
||
}
|
||
},
|
||
"Item": {
|
||
"type": "object",
|
||
"required": [
|
||
"name",
|
||
"price"
|
||
],
|
||
"properties": {
|
||
"id": {
|
||
"type": "string",
|
||
"examples": [
|
||
"order-1"
|
||
]
|
||
},
|
||
"name": {
|
||
"type": "string",
|
||
"examples": [
|
||
"Услуга"
|
||
]
|
||
},
|
||
"price": {
|
||
"type": "number",
|
||
"examples": [
|
||
1000
|
||
]
|
||
},
|
||
"quantity": {
|
||
"type": "number",
|
||
"default": 1,
|
||
"examples": [
|
||
1
|
||
]
|
||
}
|
||
}
|
||
},
|
||
"CreateReceiptRequest": {
|
||
"type": "object",
|
||
"required": [
|
||
"email",
|
||
"items"
|
||
],
|
||
"properties": {
|
||
"api_pass": {
|
||
"type": "string",
|
||
"description": "Legacy-доступ для внешних интеграций. В UI вместо него используется Bearer JWT."
|
||
},
|
||
"email": {
|
||
"type": "string",
|
||
"format": "email",
|
||
"examples": [
|
||
"client@example.com"
|
||
]
|
||
},
|
||
"items": {
|
||
"type": "array",
|
||
"minItems": 1,
|
||
"items": {
|
||
"$ref": "#/components/schemas/Item"
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"CreateReceiptResponse": {
|
||
"type": "object",
|
||
"properties": {
|
||
"success": {
|
||
"type": "boolean"
|
||
},
|
||
"receiptCreated": {
|
||
"type": "boolean"
|
||
},
|
||
"emailSent": {
|
||
"type": "boolean"
|
||
},
|
||
"receiptId": {
|
||
"type": "string"
|
||
},
|
||
"printLink": {
|
||
"type": "string",
|
||
"format": "uri"
|
||
},
|
||
"warning": {
|
||
"type": "string"
|
||
},
|
||
"technicalError": {
|
||
"type": "object",
|
||
"additionalProperties": true
|
||
}
|
||
}
|
||
},
|
||
"Receipt": {
|
||
"type": "object",
|
||
"properties": {
|
||
"receiptId": {
|
||
"type": "string"
|
||
},
|
||
"email": {
|
||
"type": "string"
|
||
},
|
||
"amount": {
|
||
"type": "number"
|
||
},
|
||
"printLink": {
|
||
"type": "string"
|
||
},
|
||
"status": {
|
||
"type": "string"
|
||
},
|
||
"emailSent": {
|
||
"type": [
|
||
"boolean",
|
||
"null"
|
||
]
|
||
},
|
||
"createdAt": {
|
||
"type": "string",
|
||
"format": "date-time"
|
||
},
|
||
"items": {
|
||
"type": "array",
|
||
"items": {
|
||
"$ref": "#/components/schemas/Item"
|
||
}
|
||
}
|
||
},
|
||
"additionalProperties": true
|
||
},
|
||
"ConfigItem": {
|
||
"type": "object",
|
||
"properties": {
|
||
"key": {
|
||
"type": "string"
|
||
},
|
||
"value": {
|
||
"type": "string"
|
||
},
|
||
"configured": {
|
||
"type": "boolean"
|
||
},
|
||
"secret": {
|
||
"type": "boolean"
|
||
},
|
||
"source": {
|
||
"type": "string",
|
||
"enum": [
|
||
"env",
|
||
"ui"
|
||
]
|
||
}
|
||
}
|
||
},
|
||
"ErrorResponse": {
|
||
"type": "object",
|
||
"properties": {
|
||
"error": {
|
||
"type": "string"
|
||
},
|
||
"technicalError": {
|
||
"type": "object",
|
||
"additionalProperties": true
|
||
}
|
||
}
|
||
},
|
||
"LoginRequest": {
|
||
"type": "object",
|
||
"required": [
|
||
"password"
|
||
],
|
||
"properties": {
|
||
"password": {
|
||
"type": "string",
|
||
"description": "Значение API_PASS"
|
||
}
|
||
}
|
||
},
|
||
"LoginResponse": {
|
||
"type": "object",
|
||
"properties": {
|
||
"success": {
|
||
"type": "boolean"
|
||
},
|
||
"token": {
|
||
"type": "string"
|
||
},
|
||
"expiresAt": {
|
||
"type": "number"
|
||
},
|
||
"expiresIn": {
|
||
"type": "number"
|
||
}
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"paths": {
|
||
"/": {
|
||
"get": {
|
||
"tags": [
|
||
"Service"
|
||
],
|
||
"summary": "Информация о сервисе",
|
||
"responses": {
|
||
"200": {
|
||
"description": "Сервис доступен",
|
||
"content": {
|
||
"application/json": {
|
||
"schema": {
|
||
"type": "object",
|
||
"properties": {
|
||
"service": {
|
||
"type": "string"
|
||
},
|
||
"status": {
|
||
"type": "string"
|
||
}
|
||
}
|
||
}
|
||
}
|
||
}
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"/health": {
|
||
"get": {
|
||
"tags": [
|
||
"Service"
|
||
],
|
||
"summary": "Быстрая проверка состояния",
|
||
"responses": {
|
||
"200": {
|
||
"description": "OK",
|
||
"content": {
|
||
"application/json": {
|
||
"schema": {
|
||
"$ref": "#/components/schemas/Health"
|
||
}
|
||
}
|
||
}
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"/health/deep": {
|
||
"get": {
|
||
"tags": [
|
||
"Service"
|
||
],
|
||
"summary": "Проверка SMTP и ФНС",
|
||
"responses": {
|
||
"200": {
|
||
"description": "Результат диагностики",
|
||
"content": {
|
||
"application/json": {
|
||
"schema": {
|
||
"type": "object",
|
||
"properties": {
|
||
"status": {
|
||
"type": "string"
|
||
},
|
||
"connect_to_fns": {
|
||
"type": "string"
|
||
},
|
||
"smtp": {
|
||
"type": "string"
|
||
}
|
||
}
|
||
}
|
||
}
|
||
}
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"/health/smtp": {
|
||
"get": {
|
||
"tags": [
|
||
"Service"
|
||
],
|
||
"summary": "Проверка SMTP",
|
||
"responses": {
|
||
"200": {
|
||
"description": "SMTP доступен"
|
||
},
|
||
"500": {
|
||
"description": "Ошибка SMTP",
|
||
"content": {
|
||
"application/json": {
|
||
"schema": {
|
||
"$ref": "#/components/schemas/ErrorResponse"
|
||
}
|
||
}
|
||
}
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"/api/v1/create-receipt": {
|
||
"post": {
|
||
"tags": [
|
||
"Receipts"
|
||
],
|
||
"summary": "Создать чек в ФНС и отправить email",
|
||
"requestBody": {
|
||
"required": true,
|
||
"content": {
|
||
"application/json": {
|
||
"schema": {
|
||
"$ref": "#/components/schemas/CreateReceiptRequest"
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"responses": {
|
||
"200": {
|
||
"description": "Чек создан",
|
||
"content": {
|
||
"application/json": {
|
||
"schema": {
|
||
"$ref": "#/components/schemas/CreateReceiptResponse"
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"400": {
|
||
"description": "Неверные данные"
|
||
},
|
||
"401": {
|
||
"description": "Неверный api_pass"
|
||
},
|
||
"500": {
|
||
"description": "Ошибка создания чека",
|
||
"content": {
|
||
"application/json": {
|
||
"schema": {
|
||
"$ref": "#/components/schemas/ErrorResponse"
|
||
}
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"security": [
|
||
{
|
||
"AdminBearer": []
|
||
},
|
||
{}
|
||
]
|
||
}
|
||
},
|
||
"/admin/api/session": {
|
||
"post": {
|
||
"tags": [
|
||
"Admin"
|
||
],
|
||
"summary": "Проверить пароль админ-панели",
|
||
"security": [
|
||
{
|
||
"AdminBearer": []
|
||
}
|
||
],
|
||
"responses": {
|
||
"200": {
|
||
"description": "Пароль принят"
|
||
},
|
||
"401": {
|
||
"description": "Неверный пароль"
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"/admin/api/config": {
|
||
"get": {
|
||
"tags": [
|
||
"Admin"
|
||
],
|
||
"summary": "Получить настройки сервиса",
|
||
"security": [
|
||
{
|
||
"AdminBearer": []
|
||
}
|
||
],
|
||
"responses": {
|
||
"200": {
|
||
"description": "Настройки",
|
||
"content": {
|
||
"application/json": {
|
||
"schema": {
|
||
"type": "object",
|
||
"properties": {
|
||
"config": {
|
||
"type": "array",
|
||
"items": {
|
||
"$ref": "#/components/schemas/ConfigItem"
|
||
}
|
||
},
|
||
"files": {
|
||
"type": "object",
|
||
"additionalProperties": {
|
||
"type": "string"
|
||
}
|
||
}
|
||
}
|
||
}
|
||
}
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"put": {
|
||
"tags": [
|
||
"Admin"
|
||
],
|
||
"summary": "Обновить настройки сервиса",
|
||
"security": [
|
||
{
|
||
"AdminBearer": []
|
||
}
|
||
],
|
||
"requestBody": {
|
||
"required": true,
|
||
"content": {
|
||
"application/json": {
|
||
"schema": {
|
||
"type": "object",
|
||
"properties": {
|
||
"values": {
|
||
"type": "object",
|
||
"additionalProperties": {
|
||
"type": "string"
|
||
}
|
||
}
|
||
}
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"responses": {
|
||
"200": {
|
||
"description": "Настройки сохранены"
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"/admin/api/receipts": {
|
||
"get": {
|
||
"tags": [
|
||
"Admin"
|
||
],
|
||
"summary": "Получить локальный журнал чеков и ошибок",
|
||
"security": [
|
||
{
|
||
"AdminBearer": []
|
||
}
|
||
],
|
||
"responses": {
|
||
"200": {
|
||
"description": "Чеки и ошибки",
|
||
"content": {
|
||
"application/json": {
|
||
"schema": {
|
||
"type": "object",
|
||
"properties": {
|
||
"receipts": {
|
||
"type": "array",
|
||
"items": {
|
||
"$ref": "#/components/schemas/Receipt"
|
||
}
|
||
},
|
||
"errors": {
|
||
"type": "array",
|
||
"items": {
|
||
"type": "object",
|
||
"additionalProperties": true
|
||
}
|
||
}
|
||
}
|
||
}
|
||
}
|
||
}
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"/admin/api/receipts/sync": {
|
||
"post": {
|
||
"tags": [
|
||
"Admin"
|
||
],
|
||
"summary": "Синхронизировать последние чеки из ФНС",
|
||
"security": [
|
||
{
|
||
"AdminBearer": []
|
||
}
|
||
],
|
||
"responses": {
|
||
"200": {
|
||
"description": "Синхронизация выполнена",
|
||
"content": {
|
||
"application/json": {
|
||
"schema": {
|
||
"type": "object",
|
||
"properties": {
|
||
"success": {
|
||
"type": "boolean"
|
||
},
|
||
"synced": {
|
||
"type": "number"
|
||
},
|
||
"total": {
|
||
"type": "number"
|
||
}
|
||
}
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"500": {
|
||
"description": "Ошибка синхронизации"
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"/admin/api/fns-user": {
|
||
"get": {
|
||
"tags": [
|
||
"Admin"
|
||
],
|
||
"summary": "Получить профиль ФНС",
|
||
"security": [
|
||
{
|
||
"AdminBearer": []
|
||
}
|
||
],
|
||
"responses": {
|
||
"200": {
|
||
"description": "Профиль ФНС",
|
||
"content": {
|
||
"application/json": {
|
||
"schema": {
|
||
"type": "object",
|
||
"properties": {
|
||
"user": {
|
||
"type": "object",
|
||
"additionalProperties": true
|
||
}
|
||
}
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"500": {
|
||
"description": "Ошибка ФНС"
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"/openapi.json": {
|
||
"get": {
|
||
"tags": [
|
||
"Service"
|
||
],
|
||
"summary": "OpenAPI JSON",
|
||
"responses": {
|
||
"200": {
|
||
"description": "Спецификация OpenAPI"
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"/swagger": {
|
||
"get": {
|
||
"tags": [
|
||
"Service"
|
||
],
|
||
"summary": "Swagger UI",
|
||
"responses": {
|
||
"200": {
|
||
"description": "Swagger UI HTML"
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"/admin/api/login": {
|
||
"post": {
|
||
"tags": [
|
||
"Admin"
|
||
],
|
||
"summary": "Войти в админ-панель и получить JWT",
|
||
"requestBody": {
|
||
"required": true,
|
||
"content": {
|
||
"application/json": {
|
||
"schema": {
|
||
"$ref": "#/components/schemas/LoginRequest"
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"responses": {
|
||
"200": {
|
||
"description": "JWT создан",
|
||
"content": {
|
||
"application/json": {
|
||
"schema": {
|
||
"$ref": "#/components/schemas/LoginResponse"
|
||
}
|
||
}
|
||
}
|
||
},
|
||
"401": {
|
||
"description": "Неверный пароль"
|
||
}
|
||
}
|
||
}
|
||
}
|
||
}
|
||
}
|