{
  "openapi": "3.1.0",
  "info": {
    "title": "PravoPro.com.ua AI Tools API",
    "description": "Публічне API юридичних та фінансових калькуляторів України (2026) та пошуку адвокатів і бухгалтерів.",
    "version": "1.0.0"
  },
  "servers": [
    {
      "url": "https://pravopro.com.ua",
      "description": "Production Server"
    }
  ],
  "paths": {
    "/api/ai/calculate": {
      "get": {
        "operationId": "getAvailableCalculators",
        "summary": "Отримати список підтримуваних калькуляторів та їх параметрів",
        "responses": {
          "200": {
            "description": "Список підтримуваних калькуляторів",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      },
      "post": {
        "operationId": "calculateLegalFinancial",
        "summary": "Виконати точний правовий чи фінансовий розрахунок за нормами 2026 року",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["calculator"],
                "properties": {
                  "calculator": {
                    "type": "string",
                    "enum": [
                      "court-fee",
                      "salary",
                      "inflation-3-percent",
                      "child-alimony",
                      "tck-fines",
                      "fop",
                      "military-pay"
                    ],
                    "description": "Ідентифікатор калькулятора"
                  },
                  "params": {
                    "type": "object",
                    "description": "Вхідні параметри для обраного калькулятора",
                    "properties": {
                      "claimAmount": { "type": "number", "description": "Ціна позову (для court-fee)" },
                      "claimType": { "type": "string", "enum": ["property", "non_property", "divorce", "appeal", "cassation"], "description": "Тип позову (для court-fee)" },
                      "payerType": { "type": "string", "enum": ["individual", "legal_entity"], "description": "Платник судового збору (для court-fee)" },
                      "isElectronicCourt": { "type": "boolean", "description": "Знижка 20% при поданні через Електронний суд (для court-fee)" },
                      "amount": { "type": "number", "description": "Сума заробітної плати (для salary)" },
                      "mode": { "type": "string", "description": "Режим: 'gross_to_net' або 'net_to_gross' для salary; 'percentage' або 'fixed' для child-alimony" },
                      "hasDisabledDiscount": { "type": "boolean", "description": "Пільга 8.41% ЄСВ для осіб з інвалідністю (для salary)" },
                      "debtAmount": { "type": "number", "description": "Сума простроченого боргу (для inflation-3-percent)" },
                      "startDate": { "type": "string", "format": "date", "description": "Початкова дата YYYY-MM-DD (для inflation-3-percent)" },
                      "endDate": { "type": "string", "format": "date", "description": "Кінцева дата YYYY-MM-DD (для inflation-3-percent)" },
                      "income": { "type": "number", "description": "Дохід платника аліментів у грн (для child-alimony)" },
                      "childrenCount": { "type": "integer", "description": "Кількість дітей 1, 2 або 3+ (для child-alimony)" },
                      "childAgeCategory": { "type": "string", "enum": ["under_6", "from_6_to_18"], "description": "Вік дитини (для child-alimony)" },
                      "violationType": { "type": "string", "enum": ["non_update_data", "ignoring_summons", "loss_military_ticket", "employer_violation"], "description": "Тип правопорушення (для tck-fines)" },
                      "category": { "type": "string", "enum": ["citizen", "official"], "description": "Категорія особи (для tck-fines)" },
                      "group": { "type": "string", "enum": ["1", "2", "3_5pct", "3_3pct"], "description": "Група єдиного податку ФОП (для fop)" },
                      "incomeAmount": { "type": "number", "description": "Дохід ФОП за період (для fop)" },
                      "period": { "type": "string", "enum": ["month", "quarter", "year"], "description": "Період розрахунку (для fop)" },
                      "rank": { "type": "string", "description": "Військове звання (slug: soldier, sergeant, lieutenant тощо, для military-pay)" },
                      "positionGrade": { "type": "integer", "description": "Тарифний розряд 1-60 (для military-pay)" },
                      "yearsOfService": { "type": "integer", "description": "Роки вислуги (для military-pay)" },
                      "combatDays": { "type": "integer", "description": "Дні бойових дій (для military-pay)" },
                      "hasZeroLine70k": { "type": "boolean", "description": "Виплата 70 000 грн за нульову лінію (для military-pay)" }
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Успішний результат розрахунку з нормативними посиланнями",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": { "type": "boolean" },
                    "calculator": { "type": "string" },
                    "statute": { "type": "string" },
                    "statutoryDate": { "type": "string" },
                    "result": { "type": "object" },
                    "consultationUrl": { "type": "string" },
                    "officialSource": { "type": "string" }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/directory/search-suggest": {
      "get": {
        "operationId": "searchDirectorySuggest",
        "summary": "Швидкий пошук адвокатів, бухгалтерів, міст та спеціалізацій в Україні",
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "required": true,
            "description": "Пошуковий запит (наприклад 'київ', 'влк', 'податки')",
            "schema": { "type": "string" }
          },
          {
            "name": "providerType",
            "in": "query",
            "required": false,
            "description": "'law_notary' для адвокатів чи 'accounting' для бухгалтерів",
            "schema": { "type": "string", "enum": ["law_notary", "accounting"], "default": "law_notary" }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": { "type": "integer", "default": 10 }
          }
        ],
        "responses": {
          "200": {
            "description": "Знайдені співпадіння",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "items": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "type": { "type": "string" },
                          "value": { "type": "string" },
                          "label": { "type": "string" }
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}