openapi: 3.0.3
info:
  title: iot_connect
  version: 1.0.1780033454859
  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: 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/googlerpcStatus"
      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: |-
        Метод получения устройств, доступных пользователю.
        Метод доступен для: TokenACF: Scope: 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/googlerpcStatus"
      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/status:
    post:
      summary: |-
        Метод получения внешним партнёром состояния устройства.
        Метод доступен для: TokenACF: Scope: iot
      operationId: IotConnectCallbackService_PostCallbackStatus
      responses:
        "200":
          description: Успешный ответ
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/v1PostCallbackStatusResponse"
        "400":
          description: Ошибка
        "401":
          description: Запрос не авторизован
        "403":
          description: В доступе отказано
        "409":
          description: В базе данных хранится более новая версия объекта
        "500":
          description: Внутренняя ошибка сервиса
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/googlerpcStatus"
      parameters:
        - name: data
          description: Массив домофонов пользователя
          in: query
          required: false
          explode: true
          schema:
            type: array
            items:
              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:
        - callback(auth)
      security:
        - oauth2:
            - iot_connect:edit
          bearerHttp: []
  /iot_connect/api/v1/callback/unlink:
    post:
      summary: |-
        Метод сообщения от внешнего IoT партнёра о разъединении аккаунтов.
        Метод доступен для: TokenACF: Scope: 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/googlerpcStatus"
      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: |-
        Метод получения пользователя.
        Метод доступен для: TokenACF: Scope: 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/googlerpcStatus"
      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/googlerpcStatus"
      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/unlink_user:
    post:
      summary: >-
        Внешний партнёр IoT отправляет в Ключ сообщение, что пользователь
        разъединил свой ID и аккаунт Ключа. Аккаунты на стороне партнёра
        разъединяются независимо от ответа вендора.

        Ссылка на раздел документации: https://developers.sber.ru/docs/ru/smarthome/c2c/webhook-post-unlink.

        Метод доступен для: admin
      operationId: IotConnectManageService_PostManageUnlinkUser
      responses:
        "200":
          description: Успешный ответ
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/v1PostManageUnlinkUserResponse"
        "400":
          description: Ошибка
        "401":
          description: Запрос не авторизован
        "403":
          description: В доступе отказано
        "409":
          description: В базе данных хранится более новая версия объекта
        "500":
          description: Внутренняя ошибка сервиса
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/googlerpcStatus"
      tags:
        - manage(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/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/googlerpcStatus"
      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:
    googlerpcStatus:
      type: object
      properties:
        code:
          type: integer
          format: int32
        message:
          type: string
        details:
          type: array
          items:
            $ref: "#/components/schemas/protobufAny"
      title: Ошибка транспортного слоя в потоковом ответе
    protobufAny:
      type: object
      properties:
        "@type":
          type: string
      additionalProperties: {}
      title: Произвольный JSON
    v1Device:
      type: object
      properties:
        userId:
          type: integer
          format: int32
          title: Идентификатор пользователя
        id:
          type: string
          title: Коммент 1
        parentId:
          type: string
          title: Коммент 1
        name:
          type: string
          title: Коммент 1
        defaultName:
          type: string
          title: Коммент 1
        home:
          type: string
          title: Коммент 1
        room:
          type: string
          title: Коммент 1
        groups:
          type: array
          items:
            type: string
          title: Коммент 1
        modelId:
          type: string
          title: Коммент 1
        hwVersion:
          type: string
          title: Коммент 1
        swVersion:
          type: string
          title: Коммент 1
      title: Объект устройства
    v1GetCallbackDevicesResponse:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: "#/components/schemas/v1Device"
          title: Массив домофонов пользователя
      title: Ответ на запрос списка домофонов пользователя в виде связки
        квартира-домофон, к которым имеет доступ пользователь
    v1GetCallbackUserResponse:
      type: object
      properties:
        data:
          type: integer
          format: int32
          title: Идентификатор пользователя
      title: Ответ на запрос идентификатора пользователя Ключ
    v1GetPingResponse:
      type: object
      title: Ответ на запрос доступности сервиса
    v1PostCallbackCommandResponse:
      type: object
      title: Ответ на запрос на изменение статуса домофона
    v1PostCallbackStatusResponse:
      type: object
      properties:
        data:
          title: Коммент
          allOf:
            - $ref: "#/components/schemas/v1PostCallbackStatusResponseStatus"
      title: Ответ на запрос статуса домофонов пользователя
    v1PostCallbackStatusResponseStatus:
      type: object
      properties:
        userId:
          type: integer
          format: int32
          title: Идентификатор пользователя
        id:
          type: string
          title: Коммент 1
        parentId:
          type: string
          title: Коммент 1
        name:
          type: string
          title: Коммент 1
        defaultName:
          type: string
          title: Коммент 1
        home:
          type: string
          title: Коммент 1
        room:
          type: string
          title: Коммент 1
        groups:
          type: array
          items:
            type: string
          title: Коммент 1
        modelId:
          type: string
          title: Коммент 1
        hwVersion:
          type: string
          title: Коммент 1
        swVersion:
          type: string
          title: Коммент 1
      title: Коммент 1
    v1PostCallbackUnlinkResponse:
      type: object
      title: Ответ на запрос-информирование о разъединении аккаунтов
    v1PostManageStateResponse:
      type: object
      title: Ответ
    v1PostManageUnlinkUserResponse:
      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
