openapi: 3.0.0
servers:
  - url: https://api.tpsgate.com/integration-api
    description: Основной сервер интеграции
info:
  description: |
    Документация интеграционного API.

    # API TPS Gate для партнёров сервиса
    В документе описан API TPS Gate.

    API позволяет встроить возможности партнерского интерфейса TPS Gate в вашу собственную систему. Основными возможностями являются:

     - Выгрузка информации о парковках и шлагбаумах.
     - Открытие шлагбаумов.

    # Как получить авторизованный доступ к парковке
    Для авторизации доступа на парковку мы используем телефон клиента, который вы присылаете нам с запросом на открытие или получение парковки. Если телефон клиента существует
    в базе данных автопарка, то мы можем предоставить водителю доступ к парковке, в противном случае мы отправим вам сообщение "Доступ запрещен".

    Вы можете отправить нам телефон в следующем формате:

    - XXXXX - последние реальные пять цифр номера телефона, вы отправляете нам часть номера телефона, а не полный реальный номер.

    # Content-Type
    Все ваши запросы должны быть отправлены как HTTP с JSON. Пожалуйста, проверьте ваши заголовки и установите заголовок 'Content-Type' = 'application/json'.

    ## Типы Объектов
    В нашем API используются следующие типы объектов для представления различных точек доступа или преград. Ниже приведен список этих типов вместе с их описанием:

    | Тип объекта      | Описание         |
    | ---------------- | ---------------- |
    | gate             | Шлагбаум         |
    | door             | Подъездная дверь |
    | barrier          | Ворота           |
    | wicket           | Калитка          |
    | other            | Иное             |

    Эти типы объектов помогают указать, с каким видом точки доступа вы взаимодействуете при выполнении API-запросов. Пожалуйста, используйте соответствующий тип для получения корректных ответов.

  version: 0.0.6
  title: TPS Gateway
  contact:
    name: Integration API Gateway support
    email: info@tpsgate.com

tags:
  - name: gates
    description: Шлагбаумы и парковки
    x-displayName: Шлагбаумы
x-tagGroups:
  - name: General
    tags:
      - gates
paths:
  /v4/opengate:
    post:
      tags:
        - gates
      summary: Открытие шлагбаума
      description: |
        Запрос на открытие шлагбаума. Ответ вернется после открытия шлагбаума, не раньше.
        Запрос на открытие шлагбаума (и отображать кнопку для открытия) можно лишь в том случае если у курьера есть основание для открытия - заказ по данном адресу.
      requestBody:
        required: true
        $ref: "#/components/requestBodies/OpenGateRequestBodyV4"
      security:
        - api_key: [ ]
      responses:
        "200":
          description: Выполнено успешно
          content:
            application/json:
              schema:
              $ref: "#/components/schemas/OpenGateResponseOKBodyV4"
        "400":
          description: |
            Не корректный запрос. Значение кодов ошибок:

            - lat_is_not_found - Широта не найдена
            - lon_is_not_found - Долгота не найдена
            - lat_is_not_valid - Широта не валидна
            - lon_is_not_valid - Долгота не валидна
            - id_is_not_found  - id шлагбаума не найден
            - id_is_not_valid  - id шлагбаума не валиден
            - driver_phone_is_not_found - Телефон водителя не найден
            - driver_phone_is_invalid - Телефон водителя не валиден
            - tenant_phone_is_not_found - Телефон жильца не найден
            - tenant_phone_is_invalid -  Телефон жильца не валиден
            - invalid_request -  Некорректный запрос
            - opening_gate_error -  Шлагбаум не открылся
            - invalid_fleet - secretkey или интеграция автопарка не валидна
            - gate_not_found - Шлагбаум не найден
          content:
            application/json:
              schema:
              $ref: "#/components/schemas/OpenGateResponseError400BodyV4"
        "401":
          description: |
            Ошибка авторизации. Значение кодов ошибок:

            - unauthorized - secretkey некорректный

          content:
            application/json:
              schema:
              $ref: "#/components/schemas/OpenGateResponseError401BodyV4"
        "429":
          description: |
            Превышен лимит запросов. Значение кодов ошибок:

            - too_many_requests - Превышение ежедневного или ежеминутного лимита
          content:
            application/json:
              schema:
              $ref: "#/components/schemas/OpenGateResponseError429BodyV4"
  /v4/parking:
    get:
      parameters:
        - name: lat
          in: query
          required: false
          example: 55.7319
          schema:
            type: number
          description: Широта для ограничения поиска по радиусу
        - name: lon
          in: query
          required: false
          example: 37.4718
          schema:
            type: number
          description: Долгота для ограничения поиска по радиусу
        - name: radiusM
          in: query
          required: false
          schema:
            type: number
            default: 50000
          description: Радиус поиска в метрах. По умолчанию 50000 метров
      tags:
        - gates
      summary: Получение списка работающих шлагбаумов
      description: |
        Запрос на получение всех работающих шлагбаумов. Возвращает список работающих шлагбаумов, которые прикреплены к определенной парковке.
        Добавте в header 'Ignore-Cache' чтобы избежать 304 статуса и всегда получать ответ.

        Обратите внимание! Если вы пытаетесь открыть шлагбаум у которого флаг 'returnFullInfo:true', то Вы сможете открыть этот шлагбаум только при условии,
        что Вы отправите нам полную информацию о заказе: ID заказа (orderId), Адрес с указанием квартиры (orderCountry, orderCity, orderStreet, orderBuilding, orderApartment),
        5 последних цифр номера телефона водителя (driverPhone) и заказчика (tenantPhone), ID водителя (driverId), номер машины (carNumber).
      security:
        - api_key: [ ]
      responses:
        "200":
          description: Выполнено успешно
          content:
            application/json:
              schema:
              $ref: "#/components/schemas/GetParkingResponseOKBodyV4"
        "400":
          description: |
            Не корректный запрос. Значение кодов ошибок:

            - error - Другая ошибка

          content:
            application/json:
              schema:
              $ref: "#/components/schemas/GetParkingResponseError400BodyV4"
        "401":
          description: |
            Ошибка авторизации. Значение кодов ошибок:

            - unauthorized - secretkey некорректный
          content:
            application/json:
              schema:
              $ref: "#/components/schemas/GetParkingResponseError401BodyV4"
        "429":
          description: |
            Превышен лимит запросов. Значение кодов ошибок:

            - too_many_requests - Превышение ежедневного или ежеминутного лимита
          content:
            application/json:
              schema:
              $ref: "#/components/schemas/GetParkingResponseError429BodyV4"
  /v6/parking:
    post:
      tags:
        - gates
      summary: Получение шлагбаумов по списку заказов
      description: Запрос по списку заказов
      security:
        - api_key: [ ]
      requestBody:
        required: true
        $ref: "#/components/requestBodies/PostParkingRequestBodyV6"
      responses:
        "200":
          description: |
            Выполнено успешно, коды ошибок позиций.
            - order_id_in_orders_is_not_found - Поле orderId в одном из заказов отсутствует
            - lat_in_orders_is_not_found - Поле lat в одном из заказов отсутствует
            - lon_in_orders_is_not_found - Поле lon в одном из заказов отсутствует
            - country_in_orders_is_not_found - Поле country в одном из заказов отсутствует
            - city_in_orders_is_not_found - Поле city в одном из заказов отсутствует
            - street_in_orders_is_not_found - Поле street в одном из заказов отсутствует
            - building_in_orders_is_not_found - Поле building в одном из заказов отсутствует
            - tenant_phone_in_orders_is_not_found - Поле tenantPhone в одном из заказов отсутствует
            - tenant_phone_in_orders_is_invalid - Поле tenantPhone в одном из заказов не соответствует формату XXXXX
            - country_in_orders_is_invalid - Поле country в одном из заказов имеет не соответсвует одному из двух значений - "Беларусь" или "Россия"
            - parking_not_found - Не удалось найти парковку
            - all_gates_unavailable_or_dont_exist - Все шлагбаумы данной парковки отсутствуют или в данный момент недоступны
          content:
            application/json:
              schema:
              $ref: "#/components/schemas/PostParkingResponseOKBodyV6"
        "400":
          description: |
            Не корректный запрос. Значение кодов ошибок:

            - orders_are_not_found - Список заказов не найден
            - error - Ошибка, повторите запрос позже

          content:
            application/json:
              schema:
              $ref: "#/components/schemas/PostParkingResponseError400V6"
        "401":
          description: |
            Ошибка авторизации. Значение кодов ошибок:

            - unauthorized - Не авторизован

          content:
            application/json:
              schema:
              $ref: "#/components/schemas/PostParkingResponseError401V6"
components:
  securitySchemes:
    api_key:
      description: >
        Secret key (в примере тестовый ключ)
      type: apiKey
      name: SecretKey
      in: header
      example: "61fbd0678260aa033dedf244"
  schemas:
    PostParkingResponseError401V6:
      type: object
      required:
        - code
        - message
      properties:
        code:
          type: string
          enum:
            - unauthorized
          description: Коды ошибок
          example: unauthorized
        message:
          type: string
          description: Читабельное сообщение об ошибке
          example: Не верный формат данных
    PostParkingResponseError400V6:
      type: object
      required:
        - code
        - message
      properties:
        code:
          type: string
          enum:
            - wrong_format
            - orders_are_not_found
            - error
          description: Коды ошибок
          example: wrong_format
        message:
          type: string
          description: Читабельное сообщение об ошибке
          example: Не верный формат данных
    PostParkingResponseOKItemAddressV6:
      type: object
      required:
        - country
        - city
        - street
        - building
      properties:
        country:
          type: string
          description: Страна заказа
          example: "Россия"
        city:
          type: string
          description: Город заказа
          example: "Москва"
        street:
          type: string
          description: Улица заказа
          example: "Тарутинская"
        building:
          type: string
          description: Номер дома заказа
          example: "1"
    PostParkingResponseOKItemGatesItemV6:
      type: object
      required:
        - id
        - name
        - lat
        - lon
        - photo
        - objectType
      properties:
        id:
          type: string
          description: Id устройства
          example: "616e62c9e2f5b58c2377c103"
        name:
          type: string
          description: Название устройства
          example: "Тарутинская 1"
        lat:
          type: number
          description: Координата lat устройства
          example: 55.731951
        lon:
          type: number
          description: Координата lon устройства
          example: 37.471812
        photo:
          type: string
          description: Ссылка на картинку шлагбаума
          example: "https://storage.yandexcloud.net/tpsgate-images/gates-images-full/60be3c82c0c9ce80945b23f1.jpg"
        number:
          type: string
          description: Номер шлагбаума
          example: "2"
        objectType:
          type: string
          description: Тип устройства (шлагбаум, домофон)
          example: "barrier"
    PostParkingResponseOKItemGatesArrayV6:
      type: array
      items:
        $ref: '#/components/schemas/PostParkingResponseOKItemGatesItemV6'
    PostParkingResponseOKItemV6:
      type: object
      required:
        - orderId
        - id
        - address
        - rules
        - gates
        - success
      properties:
        orderId:
          type: string
          description: Уникальный номер заказа
          example: "4342354363"
        id:
          type: string
          description: Id парковки
          example: "60be42ffc0c9ce85465b2416"
        address:
          $ref: "#/components/schemas/PostParkingResponseOKItemAddressV6"
        rules:
          type: string
          description: "Правила парковки"
        gates:
          $ref: "#/components/schemas/PostParkingResponseOKItemGatesArrayV6"
        success:
          type: boolean
          description: Заказ обработан успешно или нет
        errorCode:
          type: string
          description: Код ошибки, если ошибка
        errorMessage:
          type: string
          description: Читабельное сообщение об ошибке
    PostParkingResponseOKBodyV6:
      type: array
      items:
        $ref: '#/components/schemas/PostParkingResponseOKItemV6'
    ParkingGatesV4:
      type: object
      properties:
        gateId:
          type: string
          description: Идентификатор шлагбаума
          example: "6274ec3567456841a091a869"
        lat:
          type: number
          description: Широта
          example: 55.7604864201484
        lon:
          type: number
          description: Долгота
          example: 37.6273410144392
        photoUrl:
          type: string
          description: Урл изображения
          example: "https://s3.eu-central-1.amazonaws.com/bucket-dev.tpsgate.com/barrier.png"
        name:
          type: string
          description: Наименование
          example: "На выезде"
        gateNumber:
          type: number
          description: Номер
          example: 1
        objectType:
          type: string
          description: Тип объекта
          example: "barrier"
    ParkingGatesArrayV4:
      type: array
      items:
        $ref: "#/components/schemas/ParkingGatesV4"
    ParkingAddressesV4:
      type: object
      properties:
        country:
          type: string
          description: Страна
          example: "Россия"
        city:
          type: string
          description: Город
          example: "Москва"
        street:
          type: string
          description: Улица
          example: "Неглинная улица"
        building:
          type: string
          description: Строение
          example: "13"
    ParkingAddressesArrayV4:
      type: array
      items:
        $ref: "#/components/schemas/ParkingAddressesV4"
    GetParkingResponseOKBodyV4:
      title: Информация о работающих шлагбаумах
      type: object
      properties:
        parkingId:
          type: string
          description: Идентификатор шлагбаума
          example: "611e4c753ca3b73688cad96e"
        rules:
          type: string
          description: Правило
          example: "Не ставить машину у знаков"
        addresses:
          $ref: "#/components/schemas/ParkingAddressesArrayV4"
          description: Список адресов
        gates:
          $ref: "#/components/schemas/ParkingGatesArrayV4"
          description: Список шлагбаумов
    OpenGateResponseError400BodyV4:
      title: Ошибка при выполнении запроса
      type: object
      required:
        - code
        - message
      properties:
        code:
          description: Статус запроса
          type: string
          enum:
            - lat_is_not_found
            - lon_is_not_found
            - lat_is_not_valid
            - lon_is_not_valid
            - id_is_not_found
            - id_is_not_valid
            - driver_phone_is_not_found
            - driver_phone_is_invalid
            - tenant_phone_is_not_found
            - tenant_phone_is_invalid
            - invalid_request
            - opening_gate_error
            - invalid_fleet
            - gate_not_found
        message:
          description: Локализованное сообщение об ошибке
          type: string
    GetParkingResponseError400BodyV4:
      title: Ошибка при выполнении запроса
      type: object
      required:
        - code
        - message
      properties:
        code:
          description: Статус запроса
          type: string
          enum:
            - error
        message:
          description: Локализованное сообщение об ошибке
          type: string
    GetParkingResponseError401BodyV4:
      title: Ошибка при выполнении запроса
      type: object
      required:
        - code
        - message
      properties:
        code:
          description: Статус запроса
          type: string
          enum:
            - unauthorized
        message:
          description: Локализованное сообщение об ошибке
          type: string
    GetParkingResponseError429BodyV4:
      title: Ошибка при выполнении запроса
      type: object
      required:
        - code
        - message
      properties:
        code:
          description: Статус запроса
          type: string
          enum:
            - too_many_requests
        message:
          description: Локализованное сообщение об ошибке
          type: string
    OpenGateResponseError401BodyV4:
      title: Ошибка при выполнении запроса
      type: object
      required:
        - code
        - message
      properties:
        code:
          description: Статус запроса
          type: string
          enum:
            - unauthorized
        message:
          description: Локализованное сообщение об ошибке
          type: string
    OpenGateResponseError429BodyV4:
      title: Ошибка при выполнении запроса
      type: object
      required:
        - code
        - message
      properties:
        code:
          description: Статус запроса
          type: string
          enum:
            - too_many_requests
        message:
          description: Локализованное сообщение об ошибке
          type: string
    OpenGateResponseOKBodyV4:
      title: Успешный ответ на запрос
      type: object
    PostParkingRequestBodyArrayV6:
      type: array
      items:
        $ref: "#/components/schemas/PostParkingRequestBodyArrayItemV6"
    PostParkingRequestBodyArrayItemV6:
      title: Заказ
      type: object
      required:
        - orderId
        - lat
        - lon
        - country
        - city
        - street
        - building
        - tenantPhone
      properties:
        orderId:
          type: string
          description: Уникальный номер заказа (генерируется на стороне клиента)
          example: "12"
        lat:
          type: number
          description: Координаты адреса заказа (lat) [-90; 90]
          example: 55.731951
        lon:
          type: number
          description: Координата адреса заказа (lon) [-180; 180]
          example: 37.471812
        country:
          type: string
          description: Страна заказа ['Беларусь', 'Россия']
          example: "Россия"
        city:
          type: string
          description: Город заказа
          example: "Москва"
        street:
          type: string
          description: Улица заказа
          example: "Тарутинская"
        building:
          type: string
          description: Номер дома заказа
          example: "1"
        tenantPhone:
          type: string
          description: Последние цифры в номере тел. клиента (мин. 5 цифр - XXXXX)
          example: "42040"
    PostParkingRequestBodyV6Payload:
      titpe: Запрос шлагбаумов по списку заказов, версия сервиса 6
      type: object
      properties:
        orders:
          $ref: "#/components/schemas/PostParkingRequestBodyArrayV6"
          description: Список заказов
    OpenGateRequestBodyV4Payload:
      title: Запрос на открытие шлагбаума, версия сервиса 4
      type: object
      required:
        - id
        - lat
        - lon
        - driverPhone
        - tenantPhone
        - orderCountry
        - orderCity
        - orderStreet
        - orderBuilding
        - orderUnit
      properties:
        id:
          description: Идентификатор шлагбаума (Required) (Шестнадцатеричная строка, 24 символа)
          type: string
          example: "60ebf29ac92d5772760435f2"
        lat:
          description: Координаты широты пользователя [-90; 90]
          type: number
          example: 55.7319
        lon:
          description: Координаты долготы пользователя [-180; 180]
          type: number
          example: 37.4718
        driverPhone:
          description: Последние 5 цифр номера телефона водителя - XXXXX
          type: string
          example: "42040"
        tenantPhone:
          description: Последние 5 цифр номера телефона клиента - XXXXX
          type: string
          example: "42040"
        orderId:
          description: Идентификатор заказа
          type: string
          example: "12"
        orderCountry:
          description: Адрес заказа (страна)
          type: string
          example: "Россия"
        orderCity:
          description: Адрес заказа (город)
          type: string
          example: "Москва"
        orderStreet:
          description: Адрес заказа (улица)
          type: string
          example: "Большая Никитская"
        orderBuilding:
          description: Адрес заказа (номер здания)
          type: string
          example: "7"
        orderUnit:
          description: Адрес заказа (номер квартиры) для частного дома "0" строкой
          type: string
          example: "10"
        driverId:
          description: Идентификатор водителя
          type: string
          example: "ec4fd4df"
        carNumber:
          description: Номер машины
          type: string
          example: "А234АА191"
      additionalProperties: true
  requestBodies:
    OpenGateRequestBodyV4:
      content:
        application/json:
          schema:
            allOf:
              - description: Пример запроса на открытие шлагбаума
              - $ref: "#/components/schemas/OpenGateRequestBodyV4Payload"
    PostParkingRequestBodyV6:
      content:
        application/json:
          schema:
            allOf:
              - description: Запрос шлагбаумов по списку заказов
              - $ref: "#/components/schemas/PostParkingRequestBodyV6Payload"
  examples:
    Order:
      value:
        quantity: 1
        shipDate: "2018-10-19T16:46:45Z"
        status: placed
        complete: false
