{
  "openapi": "3.0.3",
  "info": {
    "title": "Подсудность.рф API",
    "version": "1.0.0",
    "description": "Определение районного/городского суда и участка мирового судьи по адресу или координатам.",
    "contact": {
      "name": "Поддержка",
      "url": "https://территориальная-подсудность.рф/support"
    }
  },
  "servers": [
    {
      "url": "https://api.территориальная-подсудность.рф",
      "description": "Production"
    }
  ],
  "paths": {
    "/v1/": {
      "get": {
        "summary": "Поиск судов по адресу или координатам",
        "description": "Возвращает районный/городской суд и участок мирового судьи для указанного адреса или координат.",
        "parameters": [
          {
            "name": "token",
            "in": "query",
            "required": true,
            "description": "API-токен из личного кабинета",
            "schema": { "type": "string" }
          },
          {
            "name": "address",
            "in": "query",
            "required": false,
            "description": "Адрес одной строкой (взаимоисключающий с coords)",
            "schema": { "type": "string" },
            "example": "Москва, Тверская, 1"
          },
          {
            "name": "coords",
            "in": "query",
            "required": false,
            "description": "Координаты в формате 'долгота широта' через пробел (взаимоисключающий с address)",
            "schema": { "type": "string" },
            "example": "37.6173 55.755826"
          }
        ],
        "responses": {
          "200": {
            "description": "Успех или ошибка (HTTP всегда 200, признак ошибки — data.status=0)",
            "content": {
              "application/json": {
                "schema": {
                  "oneOf": [
                    { "$ref": "#/components/schemas/SearchSuccess" },
                    { "$ref": "#/components/schemas/Error" }
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/v1/account": {
      "get": {
        "summary": "Информация об аккаунте",
        "description": "Возвращает данные пользователя, тариф, баланс/лимит.",
        "parameters": [
          {
            "name": "token",
            "in": "query",
            "required": true,
            "schema": { "type": "string" }
          }
        ],
        "responses": {
          "200": {
            "description": "Успех или ошибка",
            "content": {
              "application/json": {
                "schema": {
                  "oneOf": [
                    { "$ref": "#/components/schemas/Account" },
                    { "$ref": "#/components/schemas/Error" }
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/api/": {
      "get": {
        "summary": "[Legacy] Алиас /v1/",
        "description": "Идентично /v1/. Поддерживается для обратной совместимости. Новые интеграции — на /v1/.",
        "deprecated": true,
        "parameters": [
          { "$ref": "#/paths/~1v1~1/get/parameters/0" },
          { "$ref": "#/paths/~1v1~1/get/parameters/1" },
          { "$ref": "#/paths/~1v1~1/get/parameters/2" }
        ],
        "responses": {
          "200": { "$ref": "#/paths/~1v1~1/get/responses/200" }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Court": {
        "type": "object",
        "properties": {
          "code": { "type": "string", "example": "77RS0007" },
          "title": { "type": "string", "example": "Тверской районный суд города Москвы" },
          "address": { "type": "string", "example": "127051, г. Москва, Цветной бульвар, д. 25а" },
          "site": { "type": "string", "format": "uri", "nullable": true },
          "email": { "type": "string", "format": "email", "nullable": true },
          "tel": { "type": "string", "nullable": true }
        }
      },
      "SearchSuccess": {
        "type": "object",
        "properties": {
          "data": {
            "type": "object",
            "properties": {
              "last": {
                "type": "number",
                "description": "Остаток на день (free) / руб. до исчерпания (balance)"
              },
              "status": { "type": "integer", "enum": [1] }
            }
          },
          "request": {
            "type": "object",
            "properties": {
              "address": { "type": "string", "nullable": true },
              "coords": { "type": "string", "nullable": true },
              "court_fs": {
                "oneOf": [{ "$ref": "#/components/schemas/Court" }, { "type": "null" }]
              },
              "court_ms": {
                "oneOf": [{ "$ref": "#/components/schemas/Court" }, { "type": "null" }]
              }
            }
          }
        }
      },
      "Error": {
        "type": "object",
        "properties": {
          "data": {
            "type": "object",
            "properties": {
              "status": { "type": "integer", "enum": [0] },
              "error": {
                "type": "string",
                "description": "Текст ошибки на русском",
                "example": "Дневной лимит запросов исчерпан"
              }
            }
          }
        }
      },
      "Account": {
        "type": "object",
        "properties": {
          "name": { "type": "string" },
          "email": { "type": "string", "format": "email" },
          "blocking": { "type": "boolean" },
          "balance": { "type": "number" },
          "tariff": { "type": "string", "enum": ["free", "balance"] },
          "price": { "type": "number", "nullable": true, "description": "Цена за запрос (только для balance)" },
          "count_last": { "type": "integer", "nullable": true, "description": "Остаток запросов сегодня (только для free)" },
          "count_max": { "type": "integer", "nullable": true, "description": "Дневной лимит (только для free)" }
        }
      }
    }
  }
}