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: Тип кастомного поля