From 2e2ce4aa607da06da7cdd8092792ea58675b4ffe Mon Sep 17 00:00:00 2001 From: Pasha Date: Fri, 21 Nov 2025 21:13:14 +0300 Subject: [PATCH] added openapi doc with cursor --- openapi.yaml | 917 +++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 917 insertions(+) create mode 100644 openapi.yaml diff --git a/openapi.yaml b/openapi.yaml new file mode 100644 index 0000000..4ff4f45 --- /dev/null +++ b/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: Тип кастомного поля +