added openapi doc with cursor

openapi.yaml

@@ -0,0 +1,917 @@
+openapi: 3.0.3
+info:
+  title: Bitrix Integration API
+  description: API для интеграции с Bitrix24
+  version: 1.0.0
+  contact:
+    name: API Support
+
+tags:
+  - name: Users
+    description: Управление пользователями Bitrix
+  - name: Account
+    description: Управление аккаунтами
+  - name: Steps
+    description: Управление этапами (стадиями)
+  - name: Pipelines
+    description: Управление воронками
+  - name: Rules
+    description: Управление правилами для опросов
+  - name: Fields
+    description: Управление полями
+  - name: Webhook
+    description: Webhook для авторизации Bitrix
+
+paths:
+  /bitrix:
+    get:
+      tags:
+        - Account
+      summary: Health check
+      description: Проверка работоспособности API
+      security:
+        - BearerAuth: []
+      responses:
+        '200':
+          description: OK
+          content:
+            application/json:
+              schema:
+                type: string
+                example: "OK"
+
+  /bitrix/users:
+    get:
+      tags:
+        - Users
+      summary: Получить список пользователей с пагинацией
+      description: Возвращает список пользователей Bitrix с поддержкой пагинации
+      security:
+        - BearerAuth: []
+      parameters:
+        - name: page
+          in: query
+          description: Номер страницы
+          required: false
+          schema:
+            type: integer
+            default: 1
+            minimum: 1
+        - name: size
+          in: query
+          description: Размер страницы
+          required: false
+          schema:
+            type: integer
+            default: 25
+            minimum: 1
+      responses:
+        '200':
+          description: Успешный ответ
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/UserListBitrixResp'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '500':
+          $ref: '#/components/responses/InternalServerError'
+
+    patch:
+      tags:
+        - Users
+      summary: Обновить список пользователей
+      description: Запускает обновление списка пользователей из Bitrix
+      security:
+        - BearerAuth: []
+      responses:
+        '200':
+          description: Успешно запущено обновление
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '500':
+          $ref: '#/components/responses/InternalServerError'
+
+  /bitrix/account:
+    get:
+      tags:
+        - Account
+      summary: Получить текущий аккаунт
+      description: Возвращает информацию о текущем аккаунте Bitrix
+      security:
+        - BearerAuth: []
+      responses:
+        '200':
+          description: Успешный ответ
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/BitrixAccount'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '404':
+          description: Аккаунт не найден
+        '500':
+          $ref: '#/components/responses/InternalServerError'
+
+    post:
+      tags:
+        - Account
+      summary: Подключить аккаунт
+      description: Подключает аккаунт Bitrix к системе
+      security:
+        - BearerAuth: []
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required:
+                - client_bitrix_url
+              properties:
+                client_bitrix_url:
+                  type: string
+                  description: URL клиента Bitrix
+                  example: "https://example.bitrix24.ru"
+      responses:
+        '200':
+          description: Аккаунт успешно подключен
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/BitrixAccount'
+        '400':
+          description: Неверные данные запроса
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '500':
+          $ref: '#/components/responses/InternalServerError'
+
+    delete:
+      tags:
+        - Account
+      summary: Мягкое удаление аккаунта
+      description: Выполняет мягкое удаление аккаунта
+      security:
+        - BearerAuth: []
+      responses:
+        '200':
+          description: Аккаунт успешно удален
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '500':
+          $ref: '#/components/responses/InternalServerError'
+
+  /bitrix/steps:
+    get:
+      tags:
+        - Steps
+      summary: Получить список этапов с пагинацией
+      description: Возвращает список этапов (стадий) с поддержкой пагинации
+      security:
+        - BearerAuth: []
+      parameters:
+        - name: page
+          in: query
+          description: Номер страницы
+          required: false
+          schema:
+            type: integer
+            default: 1
+            minimum: 1
+        - name: size
+          in: query
+          description: Размер страницы
+          required: false
+          schema:
+            type: integer
+            default: 25
+            minimum: 1
+      responses:
+        '200':
+          description: Успешный ответ
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/UserListBitrixStepsResp'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '404':
+          description: Этапы не найдены
+        '500':
+          $ref: '#/components/responses/InternalServerError'
+
+    patch:
+      tags:
+        - Steps
+      summary: Обновить список этапов
+      description: Запускает обновление списка этапов из Bitrix
+      security:
+        - BearerAuth: []
+      responses:
+        '200':
+          description: Успешно запущено обновление
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '500':
+          $ref: '#/components/responses/InternalServerError'
+
+  /bitrix/pipelines:
+    get:
+      tags:
+        - Pipelines
+      summary: Получить список воронок с пагинацией
+      description: Возвращает список воронок с поддержкой пагинации
+      security:
+        - BearerAuth: []
+      parameters:
+        - name: page
+          in: query
+          description: Номер страницы
+          required: false
+          schema:
+            type: integer
+            default: 1
+            minimum: 1
+        - name: size
+          in: query
+          description: Размер страницы
+          required: false
+          schema:
+            type: integer
+            default: 25
+            minimum: 1
+      responses:
+        '200':
+          description: Успешный ответ
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/UserBitrixListPipelinesResp'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '404':
+          description: Воронки не найдены
+        '500':
+          $ref: '#/components/responses/InternalServerError'
+
+    patch:
+      tags:
+        - Pipelines
+      summary: Обновить список воронок
+      description: Запускает обновление списка воронок из Bitrix
+      security:
+        - BearerAuth: []
+      responses:
+        '200':
+          description: Успешно запущено обновление
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '500':
+          $ref: '#/components/responses/InternalServerError'
+
+  /bitrix/rules/{quizID}:
+    get:
+      tags:
+        - Rules
+      summary: Получить правила для опроса
+      description: Возвращает правила настройки для указанного опроса
+      security:
+        - BearerAuth: []
+      parameters:
+        - name: quizID
+          in: path
+          required: true
+          description: ID опроса
+          schema:
+            type: integer
+            example: 123
+      responses:
+        '200':
+          description: Успешный ответ
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/BitrixRule'
+        '400':
+          description: Неверный quizID
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '404':
+          description: Правила не найдены
+        '500':
+          $ref: '#/components/responses/InternalServerError'
+
+    post:
+      tags:
+        - Rules
+      summary: Создать правила для опроса
+      description: Создает новые правила настройки для указанного опроса
+      security:
+        - BearerAuth: []
+      parameters:
+        - name: quizID
+          in: path
+          required: true
+          description: ID опроса
+          schema:
+            type: integer
+            example: 123
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/BitrixRulesReq'
+      responses:
+        '200':
+          description: Правила успешно созданы
+        '400':
+          description: Неверные данные запроса
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '404':
+          description: Пользователь не найден для этого правила
+        '500':
+          description: Внутренняя ошибка сервера или правила уже существуют
+
+    patch:
+      tags:
+        - Rules
+      summary: Изменить правила для опроса
+      description: Обновляет существующие правила настройки для указанного опроса
+      security:
+        - BearerAuth: []
+      parameters:
+        - name: quizID
+          in: path
+          required: true
+          description: ID опроса
+          schema:
+            type: integer
+            example: 123
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/BitrixRulesReq'
+      responses:
+        '200':
+          description: Правила успешно обновлены
+        '400':
+          description: Неверные данные запроса
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '404':
+          description: Правила не найдены
+        '500':
+          $ref: '#/components/responses/InternalServerError'
+
+  /bitrix/fields:
+    get:
+      tags:
+        - Fields
+      summary: Получить список полей с пагинацией
+      description: Возвращает список полей с поддержкой пагинации
+      security:
+        - BearerAuth: []
+      parameters:
+        - name: page
+          in: query
+          description: Номер страницы
+          required: false
+          schema:
+            type: integer
+            default: 1
+            minimum: 1
+        - name: size
+          in: query
+          description: Размер страницы
+          required: false
+          schema:
+            type: integer
+            default: 25
+            minimum: 1
+      responses:
+        '200':
+          description: Успешный ответ
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/UserListBitrixFieldsResp'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '404':
+          description: Поля не найдены
+        '500':
+          $ref: '#/components/responses/InternalServerError'
+
+    patch:
+      tags:
+        - Fields
+      summary: Обновить список кастомных полей
+      description: Запускает обновление списка кастомных полей из Bitrix
+      security:
+        - BearerAuth: []
+      responses:
+        '200':
+          description: Успешно запущено обновление
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '500':
+          $ref: '#/components/responses/InternalServerError'
+
+  /webhook/create:
+    get:
+      tags:
+        - Webhook
+      summary: Создать webhook для авторизации
+      description: Обрабатывает callback от Bitrix для создания webhook и авторизации
+      parameters:
+        - name: code
+          in: query
+          required: true
+          description: Первый авторизационный код
+          schema:
+            type: string
+        - name: domain
+          in: query
+          required: true
+          description: Домен портала, на котором происходит авторизация
+          schema:
+            type: string
+            example: "example.bitrix24.ru"
+        - name: state
+          in: query
+          required: true
+          description: Значение, переданное в первом запросе (base64 encoded)
+          schema:
+            type: string
+        - name: scope
+          in: query
+          required: false
+          description: Список прав доступа к REST API
+          schema:
+            type: string
+        - name: member_id
+          in: query
+          required: true
+          description: Уникальный идентификатор портала - id битрикса главного
+          schema:
+            type: string
+        - name: server_domain
+          in: query
+          required: true
+          description: Домен сервера авторизации
+          schema:
+            type: string
+      responses:
+        '302':
+          description: Редирект на указанный URL после успешной авторизации
+        '400':
+          description: Отсутствуют обязательные поля или неверный формат state
+        '500':
+          description: Внутренняя ошибка сервера
+
+components:
+  securitySchemes:
+    BearerAuth:
+      type: http
+      scheme: bearer
+      bearerFormat: JWT
+      description: JWT токен авторизации
+
+  responses:
+    Unauthorized:
+      description: Не авторизован
+      content:
+        application/json:
+          schema:
+            type: string
+            example: "account id is required"
+
+    InternalServerError:
+      description: Внутренняя ошибка сервера
+      content:
+        application/json:
+          schema:
+            type: string
+            example: "Internal Server Error"
+
+  schemas:
+    BitrixAccountUser:
+      type: object
+      description: Пользователь аккаунта Bitrix
+      properties:
+        id:
+          type: integer
+          format: int64
+          description: ID пользователя
+        accountID:
+          type: string
+          description: ID портала битрикса, id account company
+        bitrixUserID:
+          type: string
+          description: ID пользователя в битриксе
+        name:
+          type: string
+          description: Имя
+        lastName:
+          type: string
+          description: Фамилия
+        secondName:
+          type: string
+          description: Отчество
+        title:
+          type: string
+        email:
+          type: string
+          format: email
+          description: Почта
+        uf_department:
+          type: array
+          items:
+            type: integer
+            format: int32
+        workPosition:
+          type: string
+          description: Должность
+        deleted:
+          type: boolean
+          description: Флаг мягкого удаления
+        createdAt:
+          type: string
+          format: date-time
+          description: Таймштамп создания воронки в нашей системе
+
+    UserListBitrixResp:
+      type: object
+      description: Ответ со списком пользователей
+      properties:
+        count:
+          type: integer
+          format: int64
+          description: Общее количество пользователей
+        items:
+          type: array
+          items:
+            $ref: '#/components/schemas/BitrixAccountUser'
+
+    BitrixAccount:
+      type: object
+      description: Аккаунт Bitrix
+      properties:
+        id:
+          type: integer
+          format: int64
+          description: ID компании
+        accountID:
+          type: string
+          description: ID аккаунта нас
+        bitrixID:
+          type: string
+          description: ID портала битрикса
+        deleted:
+          type: boolean
+        createdAt:
+          type: string
+          format: date-time
+        subdomain:
+          type: string
+          description: Поддомен
+        stale:
+          type: boolean
+
+    PipelineBitrix:
+      type: object
+      description: Воронка Bitrix
+      properties:
+        ID:
+          type: integer
+          format: int64
+          description: Айдишник в нашей системе Primary Key
+        bitrixID:
+          type: integer
+          format: int32
+          description: Айдишник воронки
+        accountID:
+          type: string
+          description: ID портала битрикса, id account company
+        name:
+          type: string
+          description: Название
+        entityTypeId:
+          $ref: '#/components/schemas/IntegerEntityType'
+          description: Тип по номерам
+        deleted:
+          type: boolean
+          description: Флаг мягкого удаления
+        createdAt:
+          type: integer
+          format: int64
+          description: Таймштамп создания воронки в нашей системе
+
+    UserBitrixListPipelinesResp:
+      type: object
+      description: Ответ со списком воронок
+      properties:
+        count:
+          type: integer
+          format: int64
+          description: Общее количество воронок
+        items:
+          type: array
+          items:
+            $ref: '#/components/schemas/PipelineBitrix'
+
+    StepBitrix:
+      type: object
+      description: Этап (стадия) Bitrix
+      properties:
+        ID:
+          type: integer
+          format: int64
+          description: Айдишник в нашей системе Primary Key
+        accountID:
+          type: string
+          description: ID портала битрикса, id account company
+        bitrixID:
+          type: string
+          description: Айдишник состояния в битриксе
+        entityID:
+          type: string
+          description: Тип сущности
+        statusID:
+          type: string
+          description: Текстовый формат id статуса
+        name:
+          type: string
+          description: Название
+        nameInit:
+          type: string
+        color:
+          type: string
+          description: Цвет
+        pipelineID:
+          type: integer
+          format: int32
+          description: ID воронки
+        deleted:
+          type: boolean
+          description: Флаг мягкого удаления
+        createdAt:
+          type: integer
+          format: int64
+          description: Таймштамп создания воронки в нашей системе
+
+    UserListBitrixStepsResp:
+      type: object
+      description: Ответ со списком этапов
+      properties:
+        items:
+          type: array
+          items:
+            $ref: '#/components/schemas/StepBitrix'
+        count:
+          type: integer
+          format: int64
+          description: Общее количество этапов
+
+    BitrixField:
+      type: object
+      description: Поле Bitrix
+      properties:
+        ID:
+          type: integer
+          format: int64
+          description: Айдишник в нашей системе Primary Key
+        accountID:
+          type: string
+          description: ID портала битрикса, id account company
+        bitrixID:
+          type: string
+          description: ID поля в битриксе (int or string)
+        entityID:
+          $ref: '#/components/schemas/FieldsType'
+          description: Тип поля
+        fieldName:
+          type: string
+          description: Имя поля, которое встраивается в request
+        editFromLabel:
+          type: string
+          description: Заголовок вопроса
+        fieldType:
+          $ref: '#/components/schemas/CustomFieldsType'
+          description: Тип поля
+        deleted:
+          type: boolean
+          description: Флаг мягкого удаления
+        createdAt:
+          type: integer
+          format: int64
+          description: Таймштамп создания воронки в нашей системе
+
+    UserListBitrixFieldsResp:
+      type: object
+      description: Ответ со списком полей
+      properties:
+        count:
+          type: integer
+          format: int64
+          description: Общее количество полей
+        items:
+          type: array
+          items:
+            $ref: '#/components/schemas/BitrixField'
+
+    BitrixRulesReq:
+      type: object
+      description: Запрос на создание/изменение правил
+      required:
+        - PerformerID
+        - PipelineID
+        - TypeID
+        - StageID
+        - SourceID
+        - FieldsRule
+        - TagsToAdd
+        - LeadFlag
+        - StatusID
+      properties:
+        PerformerID:
+          type: string
+          description: Айдишник ответственного за сделку
+        PipelineID:
+          type: integer
+          format: int32
+          description: Айдишник воронки
+        TypeID:
+          type: string
+          description: Шаг сделки только с "ENTITY_ID":"DEAL_TYPE","STATUS_ID":"SALE"
+        StageID:
+          type: string
+          description: Стадия сделки, шаг "ENTITY_ID":"DEAL_STAGE","STATUS_ID":"NEW"
+        SourceID:
+          type: string
+          description: Тип источника, шаг "ENTITY_ID":"SOURCE","STATUS_ID":"CALL"
+        FieldsRule:
+          $ref: '#/components/schemas/BitrixFieldRules'
+          description: Правила заполнения полей сущностей в битриксе
+        TagsToAdd:
+          $ref: '#/components/schemas/TagsToAdd'
+          description: Теги добавляемые к сделке
+        LeadFlag:
+          type: boolean
+          description: Флаг показывающий на то что нужен лид а не дил
+        StatusID:
+          type: string
+          description: Идентификатор стадии лида
+
+    BitrixFieldRules:
+      type: object
+      description: Правила заполнения полей
+      properties:
+        lead:
+          $ref: '#/components/schemas/BitrixFieldRule'
+        deal:
+          $ref: '#/components/schemas/BitrixFieldRule'
+        company:
+          $ref: '#/components/schemas/BitrixFieldRule'
+        contact:
+          $ref: '#/components/schemas/BitrixContactRules'
+
+    BitrixFieldRule:
+      type: object
+      description: Правило для поля
+      properties:
+        QuestionID:
+          type: object
+          additionalProperties:
+            type: string
+          description: Ключ - id вопроса, значение - id кастомного поля
+
+    BitrixContactRules:
+      type: object
+      description: Правила для контакта
+      properties:
+        ContactRuleMap:
+          type: object
+          additionalProperties:
+            type: string
+          description: Ключ - имя, значение - id кастомного поля
+        QuestionID:
+          type: object
+          additionalProperties:
+            type: string
+          description: Ключ - id вопроса, значение - id кастомного поля
+
+    TagsToAdd:
+      type: object
+      description: Теги для добавления
+      additionalProperties:
+        type: array
+        items:
+          type: string
+
+    BitrixRule:
+      type: object
+      description: Правило Bitrix
+      properties:
+        ID:
+          type: integer
+          format: int64
+          description: Айдишник в нашей системе
+        accountID:
+          type: string
+          description: ID портала битрикса, id account company
+        QuizID:
+          type: integer
+          format: int32
+          description: Айдишник опроса
+        PerformerID:
+          type: string
+          description: Айдишник ответственного за сделку
+        PipelineID:
+          type: integer
+          format: int32
+          description: Айдишник воронки
+        TypeID:
+          type: string
+          description: Шаг сделки только с "ENTITY_ID":"DEAL_TYPE","STATUS_ID":"SALE"
+        StageID:
+          type: string
+          description: Стадия сделки, шаг "ENTITY_ID":"DEAL_STAGE","STATUS_ID":"NEW"
+        SourceID:
+          type: string
+          description: Тип источника, шаг "ENTITY_ID":"SOURCE","STATUS_ID":"CALL"
+        FieldsRule:
+          $ref: '#/components/schemas/BitrixFieldRules'
+          description: Правила заполнения полей сущностей в битриксе
+        TagsToAdd:
+          $ref: '#/components/schemas/TagsToAdd'
+          description: Теги добавляемые к сделке
+        Deleted:
+          type: boolean
+          description: Флаг мягкого удаления
+        CreatedAt:
+          type: integer
+          format: int64
+          description: Таймштамп создания
+        LeadFlag:
+          type: boolean
+          description: Флаг показывающий на то что нужен лид а не дил
+        StatusID:
+          type: string
+          description: Идентификатор стадии лида
+
+    IntegerEntityType:
+      type: integer
+      format: int32
+      enum: [ 1, 2, 3, 4, 5, 7, 8, 31 ]
+      description: |
+        Тип сущности по номерам:
+        - 1: LEAD (воронки не поддерживает)
+        - 2: DEAL
+        - 3: CONTACT
+        - 4: COMPANY
+        - 5: INVOICE_OLD (может вернуть 400)
+        - 7: QUOTE (воронки не поддерживает)
+        - 8: REQUISITE (может вернуть 400)
+        - 31: INVOICE_NEW
+
+    FieldsType:
+      type: string
+      enum:
+        - CRM_LEAD
+        - CRM_COMPANY
+        - CRM_CONTACT
+        - CRM_DEAL
+        - CRM_INVOICE
+        - CRM_SMART_INVOICE
+        - CRM_QUOTE
+        - CRM_REQUISITE
+      description: Тип поля по названию
+
+    CustomFieldsType:
+      type: string
+      enum:
+        - string
+        - integer
+        - double
+        - boolean
+        - datetime
+        - enumeration
+        - iblock_section
+        - iblock_element
+        - employee
+        - crm_status
+        - crm
+        - address
+        - money
+        - url
+        - file
+        - crm_pena_tag
+      description: Тип кастомного поля
+