Как получить список стадий c семантикой для объектов CRM
Scope:
crm, user_briefКто может выполнять метод: любой пользователь с доступом к CRM
Выберите инструмент для разработки с AI-агентом:
- используйте Битрикс24 Вайбкод, чтобы создать приложение для Битрикс24 по описанию задачи без знания языков программирования. Агент напишет код и разместит приложение на сервере без ручной настройки хостинга
- используйте MCP-сервер, чтобы разрабатывать интеграцию через REST API в своем проекте. Агент будет обращаться к официальной REST-документации
Семантика стадии отражает текущее состояние элемента CRM: в работе, успешно завершен или неуспешно. Система использует значение семантики в автоматизации и в построении отчетов.
Чтобы сформировать таблицу стадий объекта CRM с семантикой, используем метод crm.status.list.
Получить список стадий с семантикой
Метод crm.status.list возвращает описание стадий по коду стадий ENTITY_ID для объекта CRM.
-
Сделки —
DEAL_STAGEдля основного направления сделок иDEAL_STAGE_xxдля дополнительного, где xx — это идентификатор направления. -
Лиды —
STATUS. -
Счета —
SMART_INVOICE_STAGE_xx, гдеxx— значение идентификатора направления счетов. -
Предложения —
QUOTE_STATUS. -
Документы —
SMART_DOCUMENT_STAGE_xx, гдеxx— значениеIDнаправления документов. -
Смарт-процессы —
DYNAMIC_xx_STAGE_xx, где первыйxx— этоIDсмарт-процесса, второйxx— этоIDнаправления.
Получим описание стадий с семантикой для лидов. Для этого укажем в фильтре filter поле ENTITY_ID со значением STATUS.
Как использовать примеры в документации
BX24.callMethod(
"crm.status.list",
{
order: { SORT: "ASC" }, // сортируем по возрастанию значения в поле SORT
filter: { ENTITY_ID: "STATUS" }, // получим стадии для лидов
},
function(result) {
if(result.error())
console.error(result.error());
else
console.dir(result.data());
}
);
require_once('crest.php');
$result = CRest::call(
'crm.status.list',
[
'order' => [ 'SORT' => 'ASC' ],
'filter' => [ 'ENTITY_ID' => 'STATUS' ]
]
);
from b24pysdk import BitrixWebhook, Client
client = Client(
BitrixWebhook(
domain="your-domain.bitrix24.com",
webhook_token="user_id/webhook_key",
)
)
result = client.crm.status.list(
order={"SORT": "ASC"},
filter={"ENTITY_ID": "STATUS"},
).response.result
В результате получим массив с объектами, где каждый объект — это описание стадии.
{
"result": [
{
"ID": "1",
"ENTITY_ID": "STATUS",
"STATUS_ID": "NEW",
"NAME": "Не обработан",
"NAME_INIT": "Не обработан",
"SORT": "10",
"SYSTEM": "Y",
"CATEGORY_ID": null,
"COLOR": "#00FFFF",
"SEMANTICS": null,
"EXTRA": {
"SEMANTICS": "process",
"COLOR": "#00FFFF"
}
},
{
"ID": "3",
"ENTITY_ID": "STATUS",
"STATUS_ID": "ASSIGNED",
"NAME": "Назначен ответственный",
"NAME_INIT": "",
"SORT": "20",
"SYSTEM": "N",
"CATEGORY_ID": null,
"COLOR": "#FFF100",
"SEMANTICS": null,
"EXTRA": {
"SEMANTICS": "process",
"COLOR": "#FFF100"
}
},
...,
{
"ID": "15",
"ENTITY_ID": "STATUS",
"STATUS_ID": "CONVERTED",
"NAME": "Сконвертирован",
"NAME_INIT": "Сконвертирован",
"SORT": "50",
"SYSTEM": "Y",
"CATEGORY_ID": null,
"COLOR": "#37B44A",
"SEMANTICS": "S",
"EXTRA": {
"SEMANTICS": "success",
"COLOR": "#37B44A"
}
},
{
"ID": "17",
"ENTITY_ID": "STATUS",
"STATUS_ID": "JUNK",
"NAME": "Некачественный лид",
"NAME_INIT": "Некачественный лид",
"SORT": "60",
"SYSTEM": "Y",
"CATEGORY_ID": null,
"COLOR": "#F54819",
"SEMANTICS": "F",
"EXTRA": {
"SEMANTICS": "failure",
"COLOR": "#F54819"
}
}
],
"total": 6
}
Объект EXTRA.SEMANTICS содержит семантику стадий. Возможные значения:
-
process— элемент CRM находится в работе, -
success— работа с элементом CRM завершилась успешно, -
failure— работа с элементом CRM завершилась неуспешно.
Пример кода
Код выводит таблицы со списком стадий для лидов и коммерческих предложений.
/**
* Загружает все статусы для заданного ENTITY_ID
* @param {string} entityId — код сущности, например, 'STATUS' или 'QUOTE_STATUS'
* @returns {Promise<Array>} — массив всех статусов
*/
function loadStatuses(entityId) {
return new Promise((resolve, reject) => {
BX24.callMethod('crm.status.list', {
filter: { ENTITY_ID: entityId },
select: ['STATUS_ID', 'NAME', 'EXTRA'],
order: { SORT: 'ASC' }
}, (result) => {
if (result.error()) {
reject(result.error());
return;
}
resolve(result.data());
});
});
}
/**
* Группирует статусы по семантике
*/
function groupStatusesBySemantics(statuses) {
const groups = { success: [], process: [], failure: [] };
statuses.forEach(item => {
const semantics = item.EXTRA?.SEMANTICS || '';
const name = item.NAME || item.STATUS_ID;
if (semantics === 'success') {
groups.success.push(name);
} else if (semantics === 'failure') {
groups.failure.push(name);
} else {
groups.process.push(name);
}
});
return groups;
}
/**
* Форматирует группы для console.table
*/
function formatForConsoleTable(groups) {
const { success, process, failure } = groups;
const maxLen = Math.max(success.length, process.length, failure.length);
const pad = (arr, len) => [...arr, ...Array(len - arr.length).fill('')];
return Array(maxLen).fill().map((_, i) => ({
'✅ Успех': pad(success, maxLen)[i],
'⚠️ В работе': pad(process, maxLen)[i],
'❌ Неуспех': pad(failure, maxLen)[i]
}));
}
// Запрашиваем статусы
Promise.all([
loadStatuses('STATUS').then(data => ({ type: 'Лиды', data })),
loadStatuses('QUOTE_STATUS').then(data => ({ type: 'Коммерческие предложения', data }))
]).then(results => {
results.forEach(({ type, data }) => {
console.group(`📊 ${type}`);
const groups = groupStatusesBySemantics(data);
console.table(formatForConsoleTable(groups));
console.groupEnd();
});
}).catch(err => {
console.error('Ошибка загрузки:', err);
});
<?php
require_once 'crest.php';
/**
* Получает все статусы для заданного ENTITY_ID
* @param string $entityId
* @return array
*/
function loadStatuses($entityId) {
$result = CRest::call('crm.status.list', [
'filter' => ['ENTITY_ID' => $entityId],
'select' => ['STATUS_ID', 'NAME', 'EXTRA'],
'order' => ['SORT' => 'ASC']
]);
if (!empty($result['error'])) {
throw new Exception("Ошибка при загрузке статусов $entityId: " . $result['error_description']);
}
return $result['result'];
}
/**
* Группирует статусы по семантике
*/
function groupStatusesBySemantics($statuses) {
$groups = ['success' => [], 'process' => [], 'failure' => []];
foreach ($statuses as $item) {
$semantics = $item['EXTRA']['SEMANTICS'] ?? '';
$name = $item['NAME'] ?? $item['STATUS_ID'];
if ($semantics === 'success') {
$groups['success'][] = $name;
} elseif ($semantics === 'failure') {
$groups['failure'][] = $name;
} else {
$groups['process'][] = $name;
}
}
return $groups;
}
/**
* Форматирует строки таблицы
*/
function buildTableRows($groups) {
$success = $groups['success'];
$process = $groups['process'];
$failure = $groups['failure'];
$max = max(count($success), count($process), count($failure));
$success = array_pad($success, $max, '');
$process = array_pad($process, $max, '');
$failure = array_pad($failure, $max, '');
$rows = [];
for ($i = 0; $i < $max; $i++) {
$rows[] = [
htmlspecialchars($success[$i]),
htmlspecialchars($process[$i]),
htmlspecialchars($failure[$i])
];
}
return $rows;
}
$entities = [
['title' => 'Статусы лидов', 'entityId' => 'STATUS'],
['title' => 'Статусы коммерческих предложений', 'entityId' => 'QUOTE_STATUS']
];
foreach ($entities as $entity) {
try {
$statuses = loadStatuses($entity['entityId']);
if (empty($statuses)) {
echo "<p>Нет статусов для " . htmlspecialchars($entity['title']) . "</p>\n";
continue;
}
$groups = groupStatusesBySemantics($statuses);
$rows = buildTableRows($groups);
echo "<h2>" . htmlspecialchars($entity['title']) . "</h2>\n";
echo "<table border=\"1\" style=\"border-collapse: collapse; width: 100%;\">\n";
echo "<thead><tr>
<th style=\"padding: 8px; background: #d4edda;\">✅ Успех</th>
<th style=\"padding: 8px; background: #fff3cd;\">⚠️ В работе</th>
<th style=\"padding: 8px; background: #f8d7da;\">❌ Неуспех</th>
</tr></thead>\n<tbody>";
foreach ($rows as $row) {
echo "<tr>
<td style=\"padding: 6px;\">{$row[0]}</td>
<td style=\"padding: 6px;\">{$row[1]}</td>
<td style=\"padding: 6px;\">{$row[2]}</td>
</tr>\n";
}
echo "</tbody></table><br>\n";
} catch (Exception $e) {
echo "<p style=\"color: red;\">Ошибка: " . htmlspecialchars($e->getMessage()) . "</p>\n";
}
}
from b24pysdk import BitrixWebhook, Client
from b24pysdk.errors import BitrixAPIError
def load_statuses(client, entity_id: str) -> list:
return client.crm.status.list(
filter={"ENTITY_ID": entity_id},
order={"SORT": "ASC"},
).response.result
def group_statuses_by_semantics(statuses: list) -> dict:
groups = {"success": [], "process": [], "failure": []}
for item in statuses:
semantics = (item.get("EXTRA") or {}).get("SEMANTICS", "")
name = item.get("NAME") or item.get("STATUS_ID")
if semantics == "success":
groups["success"].append(name)
elif semantics == "failure":
groups["failure"].append(name)
else:
groups["process"].append(name)
return groups
def build_table_rows(groups: dict) -> list:
success = groups["success"]
process = groups["process"]
failure = groups["failure"]
max_len = max(len(success), len(process), len(failure))
success = success + [""] * (max_len - len(success))
process = process + [""] * (max_len - len(process))
failure = failure + [""] * (max_len - len(failure))
rows = []
for i in range(max_len):
rows.append([success[i], process[i], failure[i]])
return rows
client = Client(
BitrixWebhook(
domain="your-domain.bitrix24.com",
webhook_token="user_id/webhook_key",
)
)
entities = [
{"title": "Статусы лидов", "entity_id": "STATUS"},
{"title": "Статусы коммерческих предложений", "entity_id": "QUOTE_STATUS"},
]
try:
tables = {}
for entity in entities:
statuses = load_statuses(client, entity["entity_id"])
if not statuses:
continue
groups = group_statuses_by_semantics(statuses)
tables[entity["title"]] = build_table_rows(groups)
for title, rows in tables.items():
print(title)
print("✅ Успех\t⚠️ В работе\t❌ Неуспех")
for row in rows:
print("\t".join(row))
except BitrixAPIError as error:
print(f"Ошибка загрузки: {error}")