docxTemplater/openapi.yaml

openapi: 3.0.0
info:
  description: "Шаблонизатор документов PenaHub для AMO CRM"
  version: 1.0.2
  title: "PenaHub Template generator"

servers:
  - url: https://tempgen.pena.digital

tags:
  - name: amo
    description: "Все что связано с amo"
  - name: yadisk
    description: "Все что связано с хранилищем Yandex Disk"
  - name: gdisk
    description: "Все что связано с хранилищем Google Disk"
  - name: template
    description: "Все что связано с шаблонами"
  - name: group
    description: "Все что связано с группами шаблонов"
  - name: generator
    description: "Генерация документов"

paths:
  # Amo endpoints
  /amo:
    get:
      tags:
        - amo
      summary: "Сохранение amo токена аккаунта"
      description: "Вебхук предназначен для получения токена, после перехода по ссылке и подтверждения прав пользователем. 
      После успешного выполнения перенаправляет на страницу настроек плагина в AMO CRM"
      operationId: AmoSaveToken
      parameters:
        - $ref: "#/components/parameters/access_token"
        - $ref: "#/components/parameters/code"
        - $ref: "#/components/parameters/client_id"
        - $ref: "#/components/parameters/expires_in"
        - $ref: "#/components/parameters/token_type"
        - $ref: "#/components/parameters/refresh_token"
        - $ref: "#/components/parameters/state"
        - $ref: "#/components/parameters/from_widget"
        - $ref: "#/components/parameters/referer"
      responses:
        308:
          description: "Permanent Redirect. Успешно"
        400:
          $ref: "#/components/responses/BadRequest"
        401:
          description: "Unauthorized. State-токен не совпадает с ожидаемым"
          content:
            application/json:
              schema:
                type: string
                example: "{error}"
        403:
          description: "Forbidden. Amo клиент выдал ошибку"
        500:
          $ref: "#/components/responses/InternalServerError"

  /amo/state:
    get:
      tags:
        - amo
      summary: "Получить состояние аккаунта пользователя в Amo"
      description: "Возвращает актуальное состояние аккаунта пользователя в AMO CRM. Авторизация происходит либо по jwt 
      «AMO CRM» или «PenaHub»"
      responses:
        200:
          $ref: "#/components/responses/RespAmoState"
        401:
          $ref: "#/components/responses/Unauthorized"
        500:
          $ref: "#/components/responses/InternalServerError"

  /amo/access_rules:
    post:
      tags:
        - amo
      summary: "Задать правила для пользователей AMO CRM"
      description: "Необходимо указывать сразу полный перечень правил, т.к. запись в БД просто перезаписывается"
      requestBody:
        $ref: "#/components/requestBodies/ReqAmoAccessRules"
      responses:
        200:
          description: "Успешно"
        401:
          $ref: "#/components/responses/Unauthorized"
        500:
          $ref: "#/components/responses/InternalServerError"

  # Yandex Disk endpoints
  /yadisk:
    get:
      tags:
        - yadisk
      summary: "Сохранение yandex токена"
      description: "Вебхук предназначен для получения токена, после перехода по ссылке и подтверждения прав пользователем. 
      После успешного выполнения перенаправляет на страницу настроек плагина в AMO CRM"
      operationId: YaDiskSaveToken
      parameters:
        - $ref: "#/components/parameters/access_token"
        - $ref: "#/components/parameters/code"
        - $ref: "#/components/parameters/expires_in"
        - $ref: "#/components/parameters/token_type"
        - $ref: "#/components/parameters/refresh_token"
        - $ref: "#/components/parameters/state"
        - name: scope
          in: query
          schema:
            type: string
        - name: error
          in: query
          schema:
            type: string
      responses:
        308:
          description: "Permanent Redirect. Успешно"
        400:
          $ref: "#/components/responses/BadRequest"
        401:
          description: "Unauthorized. State-токен не совпадает с ожидаемым"
          content:
            application/json:
              schema:
                type: string
                example: "{error}"
        403:
          description: "Forbidden. yandex клиент выдал ошибку"
        500:
          $ref: "#/components/responses/InternalServerError"

  /yadisk/setSettings:
    post:
      tags:
        - yadisk
      summary: "Задать настройки для хранилища"
      requestBody:
        $ref: "#/components/requestBodies/ReqYaDiskSetSettings"
      responses:
        200:
          description: "Успешно"

  # Google Disk endpoints

  # Template endpoints

  /template/set:


  # TemplateGroup endpoints

  # Group endpoints


components:
  parameters:
    access_token:
      name: access_token
      in: query
      required: true
      schema:
        type: string
    code:
      name: code
      in: query
      schema:
        type: string
    client_id:
      name: client_id
      in: query
      schema:
        type: string
    expires_in:
      name: expires_in
      in: query
      schema:
        type: integer
        format: timestamp
    token_type:
      name: token_type
      in: query
      schema:
        type: string
    refresh_token:
      name: refresh_token
      in: query
      schema:
        type: string
    state:
      name: state
      in: query
      required: true
      schema:
        type: string
    from_widget:
      name: from_widget
      in: query
      schema:
        type: string
    referer:
      name: referer
      in: query
      schema:
        type: string
  schemas:
    Amo:
      type: object
      description: "Amo data"
      properties:
        id:
          $ref: "#/components/defaultSchemas/id"
        user_id:
          $ref: "#/components/defaultSchemas/user_id"
        account_id:
          type: string
          description: "Идентификатор аккаунта в AMO CRM"
          example: "123145"
        subdomain:
          type: string
          description: "Субдомен в AMO CRM"
          example: "subdomain"
        referer:
          type: string
          description: "Адрес аккаунта в AMO CRM"
          example: "subdomain.amocrm.ru"
        from_widget:
          type: string
          description: ""
          example: ""
        access_rules:
          $ref: "#/components/schemas/AmoAccessRules"
        is_deleted:
          $ref: "#/components/defaultSchemas/is_deleted"
        created_at:
          $ref: "#/components/defaultSchemas/created_at"
        updated_at:
          $ref: "#/components/defaultSchemas/updated_at"

    AmoAccessRules:
      type: object
      description: "Разрешения для пользователей плагина в AMO CRM"
      properties:
        visibility:
          type: array
          description: "Видимость"
          items:
            type: integer
            example: [ 1, 23, 4 ]
        creation:
          type: array
          description: "Создание"
          items:
            type: integer
            example: [ 1, 2413, 5 ]
        delete:
          type: array
          description: "Удаление"
          items:
            type: integer
            example: [ 11234, 2413, 5 ]

    GDisk:
      type: object
      description: "Google Disk"
      properties:
        id:
          $ref: "#/components/defaultSchemas/id"
        user_id:
          $ref: "#/components/defaultSchemas/user_id"
        email:
          type: string
          description: "E-mail профиля Google"
          example: "johndoe@gmail.com"
        display_name:
          type: string
          description: "Отображаемое имя профиля Google"
          example: "John Doe"
        photo_link:
          type: string
          description: "Аватарка профиля Google"
          example: "https://lh3.googleusercontent.com/a/default-user=s64"
        name:
          type: string
          description: "Пользовательское название хранилища"
          example: "Google Disk (johndoe@gmail.com)"
        default_folder:
          type: string
          description: "Название стандартной папки приложения"
          example: "Template Generator"
        default_folder_id:
          type: string
          description: "Идентификатор папки в Google Disk"
          example: "1Qi0a0gEiuyZfgNm_DMg2-YAS9wtkZ3oQ"
        template_folder:
          type: string
          description: "Название папки с шаблонами"
          example: "templates"
        template_folder_id:
          type: string
          description: "Идентификатор папки с шаблонами в Google Disk"
          example: "Q230gEiuyASasdgNm_DMg2-YAS9wtkZadf"
        save_folder:
          type: string
          description: "Название папки с сгенерированными файлами"
          example: "saved"
        save_folder_id:
          type: string
          description: "Идентификатор папки с сгенерированными файлами в Google Disk"
          example: "a230gEiuyAaser1Nm_DMg2-YAS9wtfadtr"
        is_deleted:
          $ref: "#/components/defaultSchemas/is_deleted"
        created_at:
          $ref: "#/components/defaultSchemas/created_at"
        updated_at:
          $ref: "#/components/defaultSchemas/updated_at"

    YaDisk:
      type: object
      description: "Yandex Disk"
      properties:
        id:
          $ref: "#/components/defaultSchemas/id"
        user_id:
          $ref: "#/components/defaultSchemas/user_id"
        uid:
          type: string
          description: "Yandex UID"
        login:
          type: string
          description: "Yandex login"
          example: "johndoe"
        display_name:
          type: string
          description: "Отображаемое имя профиля Yandex"
          example: "John Doe"
        name:
          type: string
          description: "Пользовательское название хранилища"
          example: "Yandex Disk (johndoe)"
        template_folder:
          type: string
          description: "Путь до папки с шаблонами"
          example: "disk:/Template Generator/templates"
        save_folder:
          type: string
          description: "Путь до папки с сгенерированными файлами"
          example: "disk:/Template Generator/saved"
        is_deleted:
          $ref: "#/components/defaultSchemas/is_deleted"
        created_at:
          $ref: "#/components/defaultSchemas/created_at"
        updated_at:
          $ref: "#/components/defaultSchemas/updated_at"

    Template:
      type: object
      description: "Модель шаблона"
      properties:
        id:
          $ref: "#/components/defaultSchemas/id"
        user_id:
          $ref: "#/components/defaultSchemas/user_id"
        lead_id:
          type: string
          description: "Идентификатор сделки в AMO CRM"
          example: 412345
        name:
          type: string
          description: "Название шаблона"
          example: "Шаблон договора купли-продажи"
        file:
          type: string
          description: "Идентификатор или путь файла в хранилище"
        storage_id:
          type: string
          description: "Идентификатор хранилища"
          example: "635520d143ebb05286f4fba6"
        storage_type:
          type: string
          description: "Тип хранилища"
          example: "yadisk"
        group_ids:
          type: array
          description: "Идентификаторы групп, к которым привязан шаблон"
          items:
            type: string
            example: [ "635520d143ebb05286f4fba6", "123520d143fa3e5286f4fbaq" ]
        is_deleted:
          $ref: "#/components/defaultSchemas/is_deleted"
        created_at:
          $ref: "#/components/defaultSchemas/created_at"
        updated_at:
          $ref: "#/components/defaultSchemas/updated_at"

    TemplateGroup:
      type: object
      description: "Модель группы шаблона"
      properties:
        id:
          $ref: "#/components/defaultSchemas/id"
        user_id:
          $ref: "#/components/defaultSchemas/user_id"
        name:
          type: string
          description: "Название группы"
          example: "Договоры ООО «Рога и Копыта»"
        is_deleted:
          $ref: "#/components/defaultSchemas/is_deleted"
        created_at:
          $ref: "#/components/defaultSchemas/created_at"
        updated_at:
          $ref: "#/components/defaultSchemas/updated_at"

  responses:
    # Amo responses
    RespAmoState:
      description: "Успешно"
      content:
        application/json:
          schema:
            type: object
            properties:
              gen_count:
                description: "Количество оставшихся генераций на аккаунте"
                type: integer
                example: 97
              auth_yandex_url:
                type: string
                description: "Ссылка для авторизации приложения в Yandex Disk"
                example: "https://oauth.yandex.ru/authorize?..."
              auth_google_url:
                type: string
                description: "Ссылка для авторизации приложения в Google Disk"
                example: "https://accounts.google.com/o/oauth2/auth?..."
              storages:
                type: object
                description: "Данные по хранилищам"
                properties:
                  gdisk:
                    type: array
                    description: "Авторизованные Google Disk хранилища"
                    items:
                      $ref: "#/components/schemas/GDisk"
                  yadisk:
                    type: array
                    description: "Авторизованные Yandex Disk хранилища"
                    items:
                      $ref: "#/components/schemas/YaDisk"

    # Template Responses

    RespTemplateSet:
      description: "Успешно"
      content:
        application/json:
          schema:
            type: object
            properties:
              template_id:
                type: string
                example: "635520d143ebb05286f4fba6"

    InternalServerError:
      description: "Internal Server Error. Непредвиденная ошибка."
      content:
        application/json:
          schema:
            type: string
            title: Internal server
            example: "{error}"

    BadRequest:
      description: "Bad Request. Ошибка в запросе"
      content:
        application/json:
          schema:
            oneOf:
              - type: string
                example: "{value} required"

    Unauthorized:
      description: "Unauthorized. Пользователь не авторизован"
      content:
        application/json:
          schema:
            oneOf:
              - type: string
                title: Unauthorized
                example: "unauthorized"
              - type: string
                title: Unauthirized
                example: "need admin access"

  requestBodies:
    # Amo requests
    ReqAmoAccessRules:
      content:
        application/json:
          schema:
            type: object
            properties:
              visibility:
                type: array
                description: "Видимость"
                items:
                  type: integer
                  description: "Идентификатор пользователя AMO CRM"
                  example: [ 122131, 423345, 561345 ]
              creation:
                type: array
                description: "Создание"
                items:
                  type: integer
                  description: "Идентификатор пользователя AMO CRM"
                  example: [ 122131, 423345, 561345 ]
              delete:
                type: array
                description: "Удаление"
                items:
                  type: integer
                  description: "Идентификатор пользователя AMO CRM"
                  example: [ 122131, 423345, 561345 ]

    # Yadisk requests
    ReqYaDiskSetSettings:
      content:
        application/json:
          schema:
            type: object
            properties:
              id:
                $ref: "#/components/schemas/YaDisk/properties/id"
              name:
                $ref: "#/components/schemas/YaDisk/properties/name"
              template_folder:
                $ref: "#/components/schemas/YaDisk/properties/template_folder"
              save_folder:
                $ref: "#/components/schemas/YaDisk/properties/save_folder"



    # Template requests
    ReqTemplateSet:
      content:
        application/json:
          schema:
            type: object
            properties:
              lead_id:
                type: integer
                description: "Идентификатор сделки в AMO CRM"
                example: 143513
                required: true
              template_id:
                type: string
                description: ""
  defaultSchemas:
    id:
      type: string
      description: "Уникальный идентификатор"
      example: "635520d143ebb05286f4fba6"
      required: true
    user_id:
      type: string
      description: "Уникальный идентификатор пользователя"
      example: "62ac67a1471fd0f7892353bf"
      required: true
    created_at:
      type: string
      format: date-time
      description: "Время создания записи"
      example: "2022-10-23T11:09:05.35Z"
    updated_at:
      type: string
      format: date-time
      description: "Время последнего обновления записи"
      example: "2022-10-23T11:09:05.35Z"
    is_deleted:
      type: boolean
      description: "Флаг удаления"
      example: false