{
  "openapi": "3.1.0",
  "info": {
    "title": "paid-api/index-by-directions",
    "version": "1.0.0"
  },
  "servers": [
    {
      "url": "/"
    },
    {
      "url": "https://api.ati.su"
    }
  ],
  "security": [
    {
      "BearerAuth": []
    }
  ],
  "paths": {
    "/index/license/v1/index_by_direction": {
      "post": {
        "tags": [
          "Внешнее АПИ"
        ],
        "summary": "Возвращает значения индекса по направлению за период",
        "description": "Возвращает значения индекса ATI.SU по одному направлению и типу кузова по датам расчёта с DateFrom по DateTo включительно. Направление задаётся парой городов From и To из ответа GET /index/license/v1/directions. До 01.08.2025 индекс считался раз в неделю, по средам, с 01.08.2025 — каждый день.",
        "operationId": "index_by_direction_license_v1_index_by_direction_post",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/LicenseIndexByDirectionRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "Значения индекса направления по датам периода.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/LicenseIndexByDirectionResponse"
                }
              }
            }
          },
          "401": {
            "description": "Токен не передан, невалиден или просрочен. Отвечает API Gateway, тело ответа не в формате JSON."
          },
          "402": {
            "description": "Лицензия «API Средних ставок» у фирмы есть, но не действует на текущую дату.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorFormatResponse"
                },
                "example": {
                  "error": "Access error",
                  "reason": "Действие вашего доступа закончилось.",
                  "details": null
                }
              }
            }
          },
          "403": {
            "description": "У фирмы нет лицензии «API Средних ставок».",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorFormatResponse"
                },
                "example": {
                  "error": "Access error",
                  "reason": "Оплатите лицензию для получения доступа.",
                  "details": null
                }
              }
            }
          },
          "404": {
            "description": "Направления нет среди направлений индекса: в error и reason — «Направление не найдено.». За период нет ни одного значения индекса: в error — «За данный временной период у нас нет данных!», в reason — период из запроса.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorFormatResponse"
                },
                "example": {
                  "error": "Направление не найдено.",
                  "reason": "Направление не найдено.",
                  "details": null
                }
              }
            }
          },
          "422": {
            "description": "Тело запроса не прошло проверку: невалидный JSON, не передано обязательное поле, значение не того типа, неизвестный тип кузова, дата не в формате YYYY-MM-DD или конец периода раньше начала.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ValidationErrorFormatResponse"
                },
                "example": {
                  "error": "validation_errors",
                  "reason": "Произошли ошибки валидации",
                  "error_list": [
                    {
                      "error": "Тип поданного параметра отличается от ожидаемого - Value error, Неправильное зачение типа кузова. Возможные значения: all, close, open, ref.",
                      "reason": "location: , ('body', 'CarType'); type: value_error"
                    }
                  ]
                }
              }
            }
          },
          "503": {
            "description": "Не удалось проверить лицензию фирмы, повторите запрос позже.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorFormatResponse"
                },
                "example": {
                  "error": "billing_unavailable",
                  "reason": "Не удалось проверить лицензии, попробуйте позже.",
                  "details": null
                }
              }
            }
          }
        }
      }
    },
    "/index/license/v1/directions": {
      "get": {
        "tags": [
          "Внешнее АПИ"
        ],
        "summary": "Возвращает направления индекса",
        "description": "Возвращает 100 самых популярных направлений РФ, по которым считается индекс ATI.SU. Вызывайте метод перед POST /index/license/v1/index_by_direction: пару городов From и To для запроса берите из этого списка.",
        "operationId": "get_directions_license_v1_directions_get",
        "responses": {
          "200": {
            "description": "Направления индекса.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/LicenseDirectionsResponse"
                }
              }
            }
          },
          "401": {
            "description": "Токен не передан, невалиден или просрочен. Отвечает API Gateway, тело ответа не в формате JSON."
          },
          "402": {
            "description": "Лицензия «API Средних ставок» у фирмы есть, но не действует на текущую дату.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorFormatResponse"
                },
                "example": {
                  "error": "Access error",
                  "reason": "Действие вашего доступа закончилось.",
                  "details": null
                }
              }
            }
          },
          "403": {
            "description": "У фирмы нет лицензии «API Средних ставок».",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorFormatResponse"
                },
                "example": {
                  "error": "Access error",
                  "reason": "Оплатите лицензию для получения доступа.",
                  "details": null
                }
              }
            }
          },
          "503": {
            "description": "Не удалось проверить лицензию фирмы, повторите запрос позже.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorFormatResponse"
                },
                "example": {
                  "error": "billing_unavailable",
                  "reason": "Не удалось проверить лицензии, попробуйте позже.",
                  "details": null
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "ValidationErrorFormatResponse": {
        "properties": {
          "error": {
            "type": "string",
            "title": "Error",
            "description": "Код ошибки, всегда `validation_errors`.",
            "example": "validation_errors"
          },
          "reason": {
            "type": "string",
            "title": "Reason",
            "description": "Причина ошибки для человека.",
            "example": "Произошли ошибки валидации"
          },
          "error_list": {
            "items": {
              "$ref": "#/components/schemas/ValidationErrorItem"
            },
            "type": "array",
            "title": "Error List",
            "description": "Ошибки валидации. В списке одна ошибка — первая найденная.",
            "example": [
              {
                "error": "Тип поданного параметра отличается от ожидаемого - Value error, Неправильное зачение типа кузова. Возможные значения: all, close, open, ref.",
                "reason": "location: , ('body', 'CarType'); type: value_error"
              }
            ]
          }
        },
        "type": "object",
        "required": [
          "error",
          "reason",
          "error_list"
        ],
        "title": "Ответ: ошибка валидации",
        "description": "Ошибка валидации запроса: тело не прошло проверку типов и значений.",
        "example": {
          "error": "validation_errors",
          "reason": "Произошли ошибки валидации",
          "error_list": [
            {
              "error": "Тип поданного параметра отличается от ожидаемого - Value error, Неправильное зачение типа кузова. Возможные значения: all, close, open, ref.",
              "reason": "location: , ('body', 'CarType'); type: value_error"
            }
          ]
        }
      },
      "LicenseDirectionsResponse": {
        "properties": {
          "Directions": {
            "items": {
              "$ref": "#/components/schemas/LicenseDirection"
            },
            "type": "array",
            "title": "Directions",
            "description": "100 самых популярных направлений РФ из общего индекса ATI.SU. `From.Id` и `To.Id` направления подставляйте в запрос `POST /index/license/v1/index_by_direction`.",
            "example": [
              {
                "From": {
                  "Id": 1,
                  "Name": "Санкт-Петербург"
                },
                "To": {
                  "Id": 3611,
                  "Name": "Москва"
                }
              },
              {
                "From": {
                  "Id": 3611,
                  "Name": "Москва"
                },
                "To": {
                  "Id": 135,
                  "Name": "Нижний Новгород"
                }
              }
            ]
          }
        },
        "type": "object",
        "required": [
          "Directions"
        ],
        "title": "Ответ: список направлений",
        "description": "Направления, по которым считается индекс.",
        "example": {
          "Directions": [
            {
              "From": {
                "Id": 1,
                "Name": "Санкт-Петербург"
              },
              "To": {
                "Id": 3611,
                "Name": "Москва"
              }
            },
            {
              "From": {
                "Id": 3611,
                "Name": "Москва"
              },
              "To": {
                "Id": 135,
                "Name": "Нижний Новгород"
              }
            }
          ]
        }
      },
      "ErrorFormatResponse": {
        "properties": {
          "error": {
            "type": "string",
            "title": "Error",
            "description": "Код или текст ошибки.",
            "example": "Access error"
          },
          "reason": {
            "type": "string",
            "title": "Reason",
            "description": "Причина ошибки для человека.",
            "example": "Оплатите лицензию для получения доступа."
          },
          "details": {
            "anyOf": [
              {
                "type": "object"
              },
              {
                "type": "null"
              }
            ],
            "title": "Details",
            "description": "Дополнительные сведения об ошибке. null, если их нет.",
            "example": null
          }
        },
        "type": "object",
        "required": [
          "error",
          "reason",
          "details"
        ],
        "title": "Ответ: Формат ответа при ошибке",
        "description": "Ошибка в формате ATI.SU: код или текст ошибки, причина и дополнительные сведения.",
        "example": {
          "error": "Access error",
          "reason": "Оплатите лицензию для получения доступа.",
          "details": null
        }
      },
      "LicenseIndexByDirectionRequest": {
        "properties": {
          "DateFrom": {
            "type": "string",
            "format": "date",
            "title": "Datefrom",
            "description": "Начало периода включительно, в формате YYYY-MM-DD.",
            "example": "2026-09-01"
          },
          "DateTo": {
            "type": "string",
            "format": "date",
            "title": "Dateto",
            "description": "Конец периода включительно, в формате YYYY-MM-DD. Не раньше `DateFrom`.",
            "example": "2026-09-03"
          },
          "From": {
            "allOf": [
              {
                "$ref": "#/components/schemas/GeoPoint"
              }
            ],
            "description": "Город загрузки. Пара `From` и `To` — одно из направлений индекса: подставьте `From.Id` и `To.Id` из ответа `GET /index/license/v1/directions`."
          },
          "To": {
            "allOf": [
              {
                "$ref": "#/components/schemas/GeoPoint"
              }
            ],
            "description": "Город разгрузки. Пара `From` и `To` — одно из направлений индекса: подставьте `From.Id` и `To.Id` из ответа `GET /index/license/v1/directions`.",
            "example": {
              "Id": 3611
            }
          },
          "CarType": {
            "type": "string",
            "title": "Cartype",
            "description": "Тип кузова. Если не передан — `all`.\n* `ref` – Рефрижераторы\n\n* `close` – Закрытые\n\n* `open` – Открытые\n\n* `all` – Все типы",
            "default": "all",
            "example": "ref"
          }
        },
        "type": "object",
        "required": [
          "DateFrom",
          "DateTo",
          "From",
          "To"
        ],
        "title": "Запрос: Параметры для получения индекса по направлению.",
        "description": "Тело запроса значений индекса по направлению за период.",
        "example": {
          "DateFrom": "2026-09-01",
          "DateTo": "2026-09-03",
          "From": {
            "Id": 1
          },
          "To": {
            "Id": 3611
          },
          "CarType": "ref"
        }
      },
      "LicenseIndexByDirectionResponse": {
        "properties": {
          "Data": {
            "anyOf": [
              {
                "items": {
                  "$ref": "#/components/schemas/LicenseTimePoint"
                },
                "type": "array"
              },
              {
                "type": "null"
              }
            ],
            "title": "Data",
            "description": "Значения индекса направления по датам периода. До 01.08.2025 индекс считался раз в неделю, по средам, с 01.08.2025 — каждый день. Даты без расчёта в ответ не попадают. В ответе 200 массив не пустой: если значений за период нет, метод отвечает 404.",
            "example": [
              {
                "Date": "2026-09-01",
                "Index": 1390
              },
              {
                "Date": "2026-09-02",
                "Index": 1402
              },
              {
                "Date": "2026-09-03",
                "Index": 1411
              }
            ]
          }
        },
        "type": "object",
        "required": [
          "Data"
        ],
        "title": "Ответ: Динамика индекса по направлению",
        "description": "Значения индекса по направлению за период.",
        "example": {
          "Data": [
            {
              "Date": "2026-09-01",
              "Index": 1390
            },
            {
              "Date": "2026-09-02",
              "Index": 1402
            },
            {
              "Date": "2026-09-03",
              "Index": 1411
            }
          ]
        }
      },
      "ValidationErrorItem": {
        "properties": {
          "error": {
            "type": "string",
            "title": "Error",
            "description": "Текст ошибки: «Тип поданного параметра отличается от ожидаемого - » и сообщение валидатора.",
            "example": "Тип поданного параметра отличается от ожидаемого - Value error, Неправильное зачение типа кузова. Возможные значения: all, close, open, ref."
          },
          "reason": {
            "type": "string",
            "title": "Reason",
            "description": "Где ошибка и какого она типа: в `location` — путь к полю в теле запроса, в `type` — тип ошибки. У проверки порядка дат путь без имени поля: `('body',)`.",
            "example": "location: , ('body', 'CarType'); type: value_error"
          }
        },
        "type": "object",
        "required": [
          "error",
          "reason"
        ],
        "title": "Подпараметр ответа: ошибка валидации",
        "description": "Одна ошибка валидации запроса.",
        "example": {
          "error": "Тип поданного параметра отличается от ожидаемого - Value error, Неправильное зачение типа кузова. Возможные значения: all, close, open, ref.",
          "reason": "location: , ('body', 'CarType'); type: value_error"
        }
      },
      "LicenseDirection": {
        "properties": {
          "From": {
            "allOf": [
              {
                "$ref": "#/components/schemas/GeoPointFull"
              }
            ],
            "description": "Город загрузки."
          },
          "To": {
            "allOf": [
              {
                "$ref": "#/components/schemas/GeoPointFull"
              }
            ],
            "description": "Город разгрузки.",
            "example": {
              "Id": 3611,
              "Name": "Москва"
            }
          }
        },
        "type": "object",
        "required": [
          "From",
          "To"
        ],
        "title": "Подпараметр ответа: направление",
        "description": "Направление индекса: город загрузки и город разгрузки.",
        "example": {
          "From": {
            "Id": 1,
            "Name": "Санкт-Петербург"
          },
          "To": {
            "Id": 3611,
            "Name": "Москва"
          }
        }
      },
      "LicenseTimePoint": {
        "properties": {
          "Date": {
            "type": "string",
            "format": "date",
            "title": "Date",
            "description": "Дата расчёта индекса в формате YYYY-MM-DD.",
            "example": "2026-09-01"
          },
          "Index": {
            "type": "integer",
            "title": "Index",
            "description": "Значение индекса на эту дату, в условных единицах.",
            "example": 2760
          }
        },
        "type": "object",
        "required": [
          "Date",
          "Index"
        ],
        "title": "Подпараметр ответа: Значение индекса в конкретную дату",
        "description": "Значение индекса на дату расчёта.",
        "example": {
          "Date": "2026-09-01",
          "Index": 2760
        }
      },
      "GeoPoint": {
        "properties": {
          "Id": {
            "type": "integer",
            "title": "Id",
            "description": "ID города из [геословаря ATI.SU](https://ati.su/developers/api/dictionaries/geo/#post-v1-autocomplete-suggestions).",
            "example": 1
          }
        },
        "type": "object",
        "required": [
          "Id"
        ],
        "title": "GeoPoint",
        "description": "Город направления.",
        "example": {
          "Id": 1
        }
      },
      "GeoPointFull": {
        "properties": {
          "Id": {
            "type": "integer",
            "title": "Id",
            "description": "ID города из [геословаря ATI.SU](https://ati.su/developers/api/dictionaries/geo/#post-v1-autocomplete-suggestions).",
            "example": 1
          },
          "Name": {
            "type": "string",
            "title": "Name",
            "description": "Название города.",
            "example": "Санкт-Петербург"
          }
        },
        "type": "object",
        "required": [
          "Id",
          "Name"
        ],
        "title": "GeoPointFull",
        "description": "Город направления с названием.",
        "example": {
          "Id": 1,
          "Name": "Санкт-Петербург"
        }
      }
    },
    "securitySchemes": {
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "JWT",
        "description": "Authorization: Bearer {authorizationToken}"
      }
    }
  }
}