bitrix/openapi.yaml
Pasha 2e2ce4aa60
All checks were successful
Deploy / CreateImage (push) Successful in 3m0s
Deploy / DeployService (push) Successful in 28s
added openapi doc with cursor
2025-11-21 21:13:14 +03:00

918 lines
29 KiB
YAML
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

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