Для AI-агентов: markdown этой страницы — /docs-content/entities/statuses/list.md индекс документации — /llms.txt
Список справочников
GET /v1/statuses
Возвращает записи справочников CRM. Используйте filter[entityId] для выбора конкретного типа.
Параметры
| Параметр | Тип | По умолч. | Описание |
|---|---|---|---|
Параметрlimit |
Типnumber | По умолч.50 |
ОписаниеКоличество записей (до 5000). При limit > 50 авто-пагинация |
Параметрoffset |
Типnumber | По умолч.0 |
ОписаниеПропустить N записей |
Параметрselect |
Типstring | По умолч.— | ОписаниеВыборка полей: ?select=id,name,entityId |
Параметрsort |
Типstring | По умолч.— | ОписаниеСортировка кратким синтаксисом: ?sort=-sort, минус означает убывание |
Параметрorder |
Типobject | По умолч.— | ОписаниеСортировка: ?order[sort]=asc |
Параметрfilter |
Типobject | По умолч.— | ОписаниеТолько точное равенство по одному значению — по полям id, entityId, statusId, name, sort, semantics, categoryId. Список значений ($in или массив) не поддерживается ни по одному полю: метод справочника его не принимает, поэтому такой фильтр отклоняется сразу с 400 UNSUPPORTED_FILTER — передавайте одно значение, а несколько значений запрашивайте отдельными вызовами или через POST /v1/batch. Операторы (>, >=, <, <=, !, %, $ne, $contains, $nin) и другие поля (например color) не поддерживаются — тоже 400 UNSUPPORTED_FILTER.Синтаксис фильтрации. Пример: ?filter[entityId]=DEAL_STAGE — стадии общей воронки, ?filter[entityId]=DEAL_STAGE_3 — стадии воронки с ID 3. ID воронок: GET /v1/deal-categories |
ПараметрwithTotal |
Типstring | По умолч.— | ОписаниеПринимается, но на ответ не влияет: meta.total приходит при любом значении и при любом offset |
Примеры
curl — личный ключ
curl -g "https://vibecode.bitrix24.tech/v1/statuses?filter[entityId]=DEAL_STAGE&order[sort]=asc" \
-H "X-Api-Key: YOUR_API_KEY"
curl — OAuth-приложение
curl -g "https://vibecode.bitrix24.tech/v1/statuses?filter[entityId]=DEAL_STAGE&order[sort]=asc" \
-H "X-Api-Key: YOUR_APP_KEY" \
-H "Authorization: Bearer USER_SESSION_TOKEN"
JavaScript — личный ключ
const res = await fetch('https://vibecode.bitrix24.tech/v1/statuses?filter[entityId]=DEAL_STAGE&order[sort]=asc', {
headers: { 'X-Api-Key': 'YOUR_API_KEY' },
})
const { success, data, meta } = await res.json()
JavaScript — OAuth-приложение
const res = await fetch('https://vibecode.bitrix24.tech/v1/statuses?filter[entityId]=DEAL_STAGE&order[sort]=asc', {
headers: {
'X-Api-Key': 'YOUR_APP_KEY',
'Authorization': 'Bearer USER_SESSION_TOKEN',
},
})
const { success, data, meta } = await res.json()
Поля ответа
| Поле | Тип | Описание |
|---|---|---|
Полеsuccess |
Типboolean | ОписаниеВсегда true при успехе |
Полеdata |
Типarray | ОписаниеМассив записей справочника (все поля — см. Поля справочника) |
Полеmeta.total |
Типnumber | ОписаниеКоличество записей, подходящих под фильтр |
Полеmeta.hasMore |
Типboolean | ОписаниеЕсть ли ещё записи за пределами limit |
Пример ответа
Показаны две записи из восьми.
{
"success": true,
"data": [
{
"id": 101,
"entityId": "DEAL_STAGE",
"statusId": "NEW",
"name": "Новая",
"nameInit": "Новая",
"sort": 10,
"system": true,
"categoryId": null,
"color": "#39A8EF",
"semantics": null,
"description": null,
"extra": { "SEMANTICS": "process", "COLOR": "#39A8EF" }
},
{
"id": 103,
"entityId": "DEAL_STAGE",
"statusId": "PREPARATION",
"name": "Подготовка документов",
"nameInit": null,
"sort": 20,
"system": false,
"categoryId": null,
"color": "#2FC6F6",
"semantics": null,
"description": null,
"extra": { "SEMANTICS": "process", "COLOR": "#2FC6F6" }
}
],
"meta": { "total": 8, "hasMore": false }
}
Пример ответа при ошибке
400 — оператор или неподдерживаемое поле в фильтре:
{
"success": false,
"error": {
"code": "UNSUPPORTED_FILTER",
"message": "UNSUPPORTED_FILTER: 'color' is not filterable on 'statuses'. Its Bitrix24 method (crm.status.list) filters by exact match only. Filterable: id, entityId, statusId, name, sort, semantics, categoryId."
}
}
Ошибки
| HTTP | Код | Описание |
|---|---|---|
| HTTP400 | КодUNSUPPORTED_FILTER |
ОписаниеОператор, неподдерживаемое поле или список значений. Фильтруйте точным равенством по одному значению — по полям id, entityId, statusId, name, sort, semantics, categoryId |
| HTTP403 | КодSCOPE_DENIED |
ОписаниеAPI-ключ не имеет скоупа crm |
| HTTP401 | КодMISSING_API_KEY |
ОписаниеНе передан заголовок X-Api-Key |
| HTTP429 | КодRATE_LIMITED |
ОписаниеПревышен лимит запросов: 300 в минуту на портал, все API-ключи портала делят один лимит. Действующее значение — в заголовке x-ratelimit-limit. Повторите после срока из заголовка Retry-After |
Полный список ошибок — Ошибки.