{
  "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": "Неверный пароль"
          }
        }
      }
    }
  }
}