openapi: 3.0.3
info:
  title: iot_connect
  version: 1.0.1780388990152
  description: Сервис iot_connect
  license:
    name: CC BY-NC-ND 4.0
    url: https://gitlab.infra.rtkit.dev/openapi/key/raw/main/LICENCE.md
tags:
  - name: ping(public)
    description: Методы ping. Не требуют авторизацию. Доступны из интернета
  - name: callback(auth)
    description: Методы callback. Требуют авторизацию. Доступны из интернета
  - name: manage(auth)
    description: Методы manage. Требуют авторизацию. Доступны из интернета
paths:
  /iot_connect/api/v1/callback/command:
    post:
      summary: |-
        Метод запроса внешнего IoT партнёра на изменение состояния устройства.
        Поддерживается только открытие домофона.
        Метод доступен для: TokenACF: Scope: sber_iot
      operationId: IotConnectCallbackService_PostCallbackCommand
      responses:
        "200":
          description: Успешный ответ
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/v1PostCallbackCommandResponse"
        "400":
          description: Ошибка
        "401":
          description: Запрос не авторизован
        "403":
          description: В доступе отказано
        "409":
          description: В базе данных хранится более новая версия объекта
        "500":
          description: Внутренняя ошибка сервиса
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/rpcStatus"
      tags:
        - callback(auth)
      security:
        - oauth2:
            - iot_connect:edit
          bearerHttp: []
      parameters:
        - in: header
          name: X-Request-Id
          schema:
            type: string
            format: uuid
          description: Уникальный идентификатор запроса. Создаётся клиентом на каждый запрос
        - in: header
          name: X-Device-Id
          schema:
            type: string
          description: Уникальный идентификатор устройства. Создаётся клиентом при первом
            запуске приложения. Если есть способ однозначно узнать идентификатор
            устройства, то создаётся на основе него и остаётся неизменным после
            переустановки приложения
        - in: header
          name: X-Api-Key
          schema:
            type: string
          description: Уникальный ключ для партнера. Создается администратором и
            передается партнерам.
        - in: header
          name: Canary
          schema:
            type: string
          description: Параметр балансировки запроса. Если для заголовка запроса
            установлено значение always, он будет перенаправлен на канареечный
            деплой. Если для заголовка установлено значение never, он никогда не
            будет перенаправлен на канареечный деплой
  /iot_connect/api/v1/callback/devices:
    get:
      summary: |-
        Метод получения устройств, доступных пользователю.
        Идентификатор пользователя - это subject из токена.
        Метод доступен для: TokenACF: Scope: sber_iot
      operationId: IotConnectCallbackService_GetCallbackDevices
      responses:
        "200":
          description: Успешный ответ
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/v1GetCallbackDevicesResponse"
        "400":
          description: Ошибка
        "401":
          description: Запрос не авторизован
        "403":
          description: В доступе отказано
        "500":
          description: Внутренняя ошибка сервиса
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/rpcStatus"
      tags:
        - callback(auth)
      security:
        - oauth2:
            - iot_connect:read
            - iot_connect:edit
          bearerHttp: []
      parameters:
        - in: header
          name: X-Request-Id
          schema:
            type: string
            format: uuid
          description: Уникальный идентификатор запроса. Создаётся клиентом на каждый запрос
        - in: header
          name: X-Device-Id
          schema:
            type: string
          description: Уникальный идентификатор устройства. Создаётся клиентом при первом
            запуске приложения. Если есть способ однозначно узнать идентификатор
            устройства, то создаётся на основе него и остаётся неизменным после
            переустановки приложения
        - in: header
          name: X-Api-Key
          schema:
            type: string
          description: Уникальный ключ для партнера. Создается администратором и
            передается партнерам.
        - in: header
          name: Canary
          schema:
            type: string
          description: Параметр балансировки запроса. Если для заголовка запроса
            установлено значение always, он будет перенаправлен на канареечный
            деплой. Если для заголовка установлено значение never, он никогда не
            будет перенаправлен на канареечный деплой
  /iot_connect/api/v1/callback/query:
    post:
      summary: |-
        Зачем.
        Метод получения состояния устройства.
        Идентификатор пользователя - это subject из токена.
        Метод доступен для: TokenACF: Scope: sber_iot
      operationId: IotConnectCallbackService_PostCallbackQuery
      responses:
        "200":
          description: Успешный ответ
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/v1PostCallbackQueryResponse"
        "400":
          description: Ошибка
        "401":
          description: Запрос не авторизован
        "403":
          description: В доступе отказано
        "409":
          description: В базе данных хранится более новая версия объекта
        "500":
          description: Внутренняя ошибка сервиса
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/rpcStatus"
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/v1PostCallbackQueryRequest"
        required: true
      tags:
        - callback(auth)
      security:
        - oauth2:
            - iot_connect:edit
          bearerHttp: []
      parameters:
        - in: header
          name: X-Request-Id
          schema:
            type: string
            format: uuid
          description: Уникальный идентификатор запроса. Создаётся клиентом на каждый запрос
        - in: header
          name: X-Device-Id
          schema:
            type: string
          description: Уникальный идентификатор устройства. Создаётся клиентом при первом
            запуске приложения. Если есть способ однозначно узнать идентификатор
            устройства, то создаётся на основе него и остаётся неизменным после
            переустановки приложения
        - in: header
          name: X-Api-Key
          schema:
            type: string
          description: Уникальный ключ для партнера. Создается администратором и
            передается партнерам.
        - in: header
          name: Canary
          schema:
            type: string
          description: Параметр балансировки запроса. Если для заголовка запроса
            установлено значение always, он будет перенаправлен на канареечный
            деплой. Если для заголовка установлено значение never, он никогда не
            будет перенаправлен на канареечный деплой
  /iot_connect/api/v1/callback/unlink:
    post:
      summary: |-
        Метод разъединения аккаунтов.
        Идентификатор пользователя - это subject из токена.
        Метод доступен для: TokenACF: Scope: sber_iot
      operationId: IotConnectCallbackService_PostCallbackUnlink
      responses:
        "200":
          description: Успешный ответ
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/v1PostCallbackUnlinkResponse"
        "400":
          description: Ошибка
        "401":
          description: Запрос не авторизован
        "403":
          description: В доступе отказано
        "409":
          description: В базе данных хранится более новая версия объекта
        "500":
          description: Внутренняя ошибка сервиса
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/rpcStatus"
      tags:
        - callback(auth)
      security:
        - oauth2:
            - iot_connect:edit
          bearerHttp: []
      parameters:
        - in: header
          name: X-Request-Id
          schema:
            type: string
            format: uuid
          description: Уникальный идентификатор запроса. Создаётся клиентом на каждый запрос
        - in: header
          name: X-Device-Id
          schema:
            type: string
          description: Уникальный идентификатор устройства. Создаётся клиентом при первом
            запуске приложения. Если есть способ однозначно узнать идентификатор
            устройства, то создаётся на основе него и остаётся неизменным после
            переустановки приложения
        - in: header
          name: X-Api-Key
          schema:
            type: string
          description: Уникальный ключ для партнера. Создается администратором и
            передается партнерам.
        - in: header
          name: Canary
          schema:
            type: string
          description: Параметр балансировки запроса. Если для заголовка запроса
            установлено значение always, он будет перенаправлен на канареечный
            деплой. Если для заголовка установлено значение never, он никогда не
            будет перенаправлен на канареечный деплой
  /iot_connect/api/v1/callback/user:
    get:
      summary: |-
        Метод получения пользователя для соединения аккаунтов.
        Идентификатор пользователя - это subject из токена.
        Метод доступен для: TokenACF: Scope: sber_iot
      operationId: IotConnectCallbackService_GetCallbackUser
      responses:
        "200":
          description: Успешный ответ
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/v1GetCallbackUserResponse"
        "400":
          description: Ошибка
        "401":
          description: Запрос не авторизован
        "403":
          description: В доступе отказано
        "500":
          description: Внутренняя ошибка сервиса
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/rpcStatus"
      tags:
        - callback(auth)
      security:
        - oauth2:
            - iot_connect:read
            - iot_connect:edit
          bearerHttp: []
      parameters:
        - in: header
          name: X-Request-Id
          schema:
            type: string
            format: uuid
          description: Уникальный идентификатор запроса. Создаётся клиентом на каждый запрос
        - in: header
          name: X-Device-Id
          schema:
            type: string
          description: Уникальный идентификатор устройства. Создаётся клиентом при первом
            запуске приложения. Если есть способ однозначно узнать идентификатор
            устройства, то создаётся на основе него и остаётся неизменным после
            переустановки приложения
        - in: header
          name: X-Api-Key
          schema:
            type: string
          description: Уникальный ключ для партнера. Создается администратором и
            передается партнерам.
        - in: header
          name: Canary
          schema:
            type: string
          description: Параметр балансировки запроса. Если для заголовка запроса
            установлено значение always, он будет перенаправлен на канареечный
            деплой. Если для заголовка установлено значение never, он никогда не
            будет перенаправлен на канареечный деплой
  /iot_connect/api/v1/manage/state:
    post:
      summary: >-
        Зачем.

        Ключ отправляет внешнему партнёру факт изменения состояния устройства.

        В данном случае имеется в виду переход состояния домофона из состояния "нет вызова в квартиру" -> "есть вызов в квартиру".

        Метод доступен для: admin
      operationId: IotConnectManageService_PostManageState
      responses:
        "200":
          description: Успешный ответ
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/v1PostManageStateResponse"
        "400":
          description: Ошибка
        "401":
          description: Запрос не авторизован
        "403":
          description: В доступе отказано
        "409":
          description: В базе данных хранится более новая версия объекта
        "500":
          description: Внутренняя ошибка сервиса
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/rpcStatus"
      parameters:
        - name: key
          description: Ключ состояния
          in: query
          required: false
          schema:
            type: string
        - in: header
          name: X-Request-Id
          schema:
            type: string
            format: uuid
          description: Уникальный идентификатор запроса. Создаётся клиентом на каждый запрос
        - in: header
          name: X-Device-Id
          schema:
            type: string
          description: Уникальный идентификатор устройства. Создаётся клиентом при первом
            запуске приложения. Если есть способ однозначно узнать идентификатор
            устройства, то создаётся на основе него и остаётся неизменным после
            переустановки приложения
        - in: header
          name: X-Api-Key
          schema:
            type: string
          description: Уникальный ключ для партнера. Создается администратором и
            передается партнерам.
        - in: header
          name: Canary
          schema:
            type: string
          description: Параметр балансировки запроса. Если для заголовка запроса
            установлено значение always, он будет перенаправлен на канареечный
            деплой. Если для заголовка установлено значение never, он никогда не
            будет перенаправлен на канареечный деплой
      tags:
        - manage(auth)
      security:
        - oauth2:
            - iot_connect:edit
          bearerHttp: []
  "/iot_connect/api/v1/manage/user/{userId}/detach":
    put:
      summary: |-
        Метод разъединения аккаунтов.
        Метод доступен для: admin
      operationId: IotConnectManageService_PutManageUserDetach
      responses:
        "200":
          description: Успешный ответ
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/v1PutManageUserDetachResponse"
        "400":
          description: Ошибка
        "401":
          description: Запрос не авторизован
        "403":
          description: В доступе отказано
        "409":
          description: В базе данных хранится более новая версия объекта
        "500":
          description: Внутренняя ошибка сервиса
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/rpcStatus"
      parameters:
        - name: userId
          description: Идентификатор пользователя
          in: path
          required: true
          schema:
            type: integer
            format: int32
        - in: header
          name: X-Request-Id
          schema:
            type: string
            format: uuid
          description: Уникальный идентификатор запроса. Создаётся клиентом на каждый запрос
        - in: header
          name: X-Device-Id
          schema:
            type: string
          description: Уникальный идентификатор устройства. Создаётся клиентом при первом
            запуске приложения. Если есть способ однозначно узнать идентификатор
            устройства, то создаётся на основе него и остаётся неизменным после
            переустановки приложения
        - in: header
          name: X-Api-Key
          schema:
            type: string
          description: Уникальный ключ для партнера. Создается администратором и
            передается партнерам.
        - in: header
          name: Canary
          schema:
            type: string
          description: Параметр балансировки запроса. Если для заголовка запроса
            установлено значение always, он будет перенаправлен на канареечный
            деплой. Если для заголовка установлено значение never, он никогда не
            будет перенаправлен на канареечный деплой
      tags:
        - manage(auth)
      security:
        - oauth2:
            - iot_connect:edit
          bearerHttp: []
  /iot_connect/api/v1/ping:
    get:
      summary: |-
        Метод проверки доступности сервиса.
        Не требует авторизации
      operationId: SystemService_GetPing
      responses:
        "200":
          description: Успешный ответ
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/v1GetPingResponse"
        "400":
          description: Ошибка
        "500":
          description: Внутренняя ошибка сервиса
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/rpcStatus"
      tags:
        - ping(public)
      parameters:
        - in: header
          name: X-Request-Id
          schema:
            type: string
            format: uuid
          description: Уникальный идентификатор запроса. Создаётся клиентом на каждый запрос
        - in: header
          name: X-Device-Id
          schema:
            type: string
          description: Уникальный идентификатор устройства. Создаётся клиентом при первом
            запуске приложения. Если есть способ однозначно узнать идентификатор
            устройства, то создаётся на основе него и остаётся неизменным после
            переустановки приложения
        - in: header
          name: X-Api-Key
          schema:
            type: string
          description: Уникальный ключ для партнера. Создается администратором и
            передается партнерам.
        - in: header
          name: Canary
          schema:
            type: string
          description: Параметр балансировки запроса. Если для заголовка запроса
            установлено значение always, он будет перенаправлен на канареечный
            деплой. Если для заголовка установлено значение never, он никогда не
            будет перенаправлен на канареечный деплой
components:
  schemas:
    ModelFeatureType:
      type: string
      enum:
        - INCOMING_CALL
        - ONLINE
        - REJECT_CALL
        - UNLOCK
      description: |-
        - FEATURE_TYPE_UNKNOWN: Значение не указано
         - INCOMING_CALL: Сигнализация о поступившем звонке
         - ONLINE: Сигнализация о доступности устройства
         - REJECT_CALL: Отклонение звонка
         - UNLOCK: Открытие замка
      title: Список функций устройства
    ValueValueEnumType:
      type: string
      enum:
        - REJECT
        - UNLOCK
      description: |-
        - VALUE_ENUM_TYPE_UNKNOWN: Значение не указано
         - REJECT: Отклонение звонка
         - UNLOCK: Открытие замка
      title: Значения команд на изменение статуса устройства типа перечисление
    protobufAny:
      type: object
      properties:
        "@type":
          type: string
      additionalProperties: {}
      title: Произвольный JSON
    rpcStatus:
      type: object
      properties:
        code:
          type: integer
          format: int32
        message:
          type: string
        details:
          type: array
          items:
            $ref: "#/components/schemas/protobufAny"
      title: Ошибка транспортного слоя
    v1Device:
      type: object
      properties:
        id:
          type: string
          title: |-
            Идентификатор устройства на платформе Ключ.
            Конкатенация user_id и device_id плафтормы Ключ
        name:
          type: string
          title: Название устройства на платформе Ключ
        defaultName:
          type: string
          title: Название устройства от производителя
        home:
          type: string
          title: Адрес дома, где установлено устройство
        room:
          type: string
          title: Название или номер подъезда
        model:
          title: Тип устройства
          allOf:
            - $ref: "#/components/schemas/v1Model"
        hwVersion:
          type: string
          title: HW версия устройства
        swVersion:
          type: string
          title: SW версия устройства
      title: Объект устройства
    v1DeviceCommand:
      type: object
      properties:
        key:
          title: Тип команды на изменение статуса устройства
          allOf:
            - $ref: "#/components/schemas/v1DeviceCommandKeyType"
        value:
          title: Значение команды на изменение статуса устройства
          allOf:
            - $ref: "#/components/schemas/v1DeviceCommandValue"
      title: Команды на изменение статуса устройства
    v1DeviceCommandArray:
      type: object
      properties:
        states:
          type: array
          items:
            $ref: "#/components/schemas/v1DeviceCommand"
          title: Команды на изменение статуса устройства
      title: Массив команд на изменение статуса устройства
    v1DeviceCommandKeyType:
      type: string
      enum:
        - REJECT_CALL
        - UNLOCK
      description: |-
        - KEY_TYPE_UNKNOWN: Значение не указано
         - REJECT_CALL: Отклонение звонка
         - UNLOCK: Открытие замка
      title: Список ключей команд на изменение статуса устройства
    v1DeviceCommandValue:
      type: object
      properties:
        type:
          title: Тип значения команды на изменение статуса устройства
          allOf:
            - $ref: "#/components/schemas/v1DeviceCommandValueType"
        enum_value:
          title: Значения команды на изменение статуса устройства типа перечисление
          allOf:
            - $ref: "#/components/schemas/ValueValueEnumType"
      title: Значение команды на изменение статуса устройства
    v1DeviceCommandValueType:
      type: string
      enum:
        - ENUM
      description: |-
        - TYPE_UNKNOWN: Значение не указано
         - ENUM: Перечисление
      title: Тип значения команд на изменение статуса устройства
    v1DeviceState:
      type: object
      properties:
        key:
          title: Тип статуса устройства
          allOf:
            - $ref: "#/components/schemas/v1DeviceStateKeyType"
        value:
          title: Значение статуса устройства
          allOf:
            - $ref: "#/components/schemas/v1DeviceStateValue"
      title: Статус устройства
    v1DeviceStateArray:
      type: object
      properties:
        states:
          type: array
          items:
            $ref: "#/components/schemas/v1DeviceState"
          title: Статусы устройства
      title: Массив статусов устройства
    v1DeviceStateKeyType:
      type: string
      enum:
        - ONLINE
      description: |-
        - KEY_TYPE_UNKNOWN: Значение не указано
         - ONLINE: Статус доступности устройства
      title: Список ключей статусов устройства
    v1DeviceStateValue:
      type: object
      properties:
        type:
          title: Тип значения статуса устройства
          allOf:
            - $ref: "#/components/schemas/v1DeviceStateValueType"
        bool_value:
          type: boolean
          title: Значение логического типа
      title: Значение статуса устройства
    v1DeviceStateValueType:
      type: string
      enum:
        - BOOL
      description: |-
        - TYPE_UNKNOWN: Значение не указано
         - BOOL: Логический тип
      title: Тип значения статуса устройства
    v1GetCallbackDevicesResponse:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: "#/components/schemas/v1Device"
          title: Домофоны, доступные пользователю
      title: Ответ на запрос метода получения устройств, доступных пользователю
    v1GetCallbackUserResponse:
      type: object
      properties:
        user_id:
          type: integer
          format: int32
          title: Идентификатор пользователя
      title: Ответ на запрос метода получения пользователя для соединения аккаунтов
    v1GetPingResponse:
      type: object
      title: Ответ на запрос доступности сервиса
    v1Model:
      type: object
      properties:
        id:
          type: string
          title: Идентификатор модели
        manufacturer:
          type: string
          title: Производитель
        model:
          type: string
          title: Название модели
        hwVersion:
          type: string
          title: Версия оборудования
        swVersion:
          type: string
          title: Версия прошивки
        description:
          type: string
          title: Описание
        category:
          type: string
          title: Категория устройства
        features:
          type: array
          items:
            $ref: "#/components/schemas/ModelFeatureType"
          title: Список функций
      title: Объект Модель устройства
    v1PostCallbackCommandResponse:
      type: object
      title: Ответ на запрос на изменение статуса домофона
    v1PostCallbackQueryRequest:
      type: object
      properties:
        devices:
          type: array
          items:
            type: string
          title: Массив идентификаторов домофонов пользователя
      title: Запрос статуса домофонов пользователя
    v1PostCallbackQueryResponse:
      type: object
      properties:
        devices:
          type: object
          additionalProperties:
            $ref: "#/components/schemas/v1DeviceStateArray"
          title: Массив домофонов со статусами
      title: Ответ на запрос статуса домофонов пользователя
    v1PostCallbackUnlinkResponse:
      type: object
      title: Ответ на запрос метода разъединения аккаунтов
    v1PostManageStateResponse:
      type: object
      title: Ответ
    v1PutManageUserDetachResponse:
      type: object
      title: Ответ на запрос метода разъединения аккаунтов
  securitySchemes:
    bearerHttp:
      type: http
      scheme: bearer
      bearerFormat: JWT
    oauth2:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: https://oauth2-staging.k8s.key.rt.ru/oauth2/token
          scopes:
            iot_connect:edit: Предоставляет полный доступ в сервис iot_connect
            iot_connect:read: Предоставляет доступ на чтение данных из сервиса iot_connect
servers:
  - url: https://keyapis-staging.k8s.key.rt.ru
    description: staging
  - url: https://{feature}.k8s.key.rt.ru/
    description: https feature
    variables:
      feature:
        default: ""
        description: Feature name
  - url: http://{feature}.k8s.key.rt.ru/
    description: http feature
    variables:
      feature:
        default: ""
        description: Feature name
  - url: https://localhost:3001
    description: localhost
  - url: https://keyapis.key.rt.ru
    description: production
