[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"docs-keys-auth\u002Fguide":3,"docs-tabs-keys-auth\u002Fguide":6},{"content":4,"lastmod":5},"\n## Справочник API для модели\n\n`GET \u002Fv1\u002Fguide`\n\nВозвращает контракт полей всех сущностей портала и правила работы с API одним ответом. Модель обращается к нему за статической схемой полей до появления токена сессии — например, когда приложению нужно узнать типы и ограничения полей ещё до авторизации пользователя.\n\n## Примеры\n\n### curl — личный ключ\n\n```bash\ncurl -H \"X-Api-Key: YOUR_API_KEY\" \\\n  https:\u002F\u002Fvibecode.bitrix24.tech\u002Fv1\u002Fguide\n```\n\n### curl — OAuth-приложение\n\n```bash\ncurl \\\n  -H \"X-Api-Key: YOUR_APP_KEY\" \\\n  https:\u002F\u002Fvibecode.bitrix24.tech\u002Fv1\u002Fguide\n```\n\n### JavaScript — личный ключ\n\n```javascript\nconst res = await fetch('https:\u002F\u002Fvibecode.bitrix24.tech\u002Fv1\u002Fguide', {\n  headers: { 'X-Api-Key': 'YOUR_API_KEY' },\n})\n\nconst { data } = await res.json()\ndata.entities.forEach((e) => {\n  console.log(`${e.name} (${e.scope}) — ${Object.keys(e.operations).join(', ')}`)\n})\n```\n\n### JavaScript — OAuth-приложение\n\n```javascript\nconst res = await fetch('https:\u002F\u002Fvibecode.bitrix24.tech\u002Fv1\u002Fguide', {\n  headers: { 'X-Api-Key': 'YOUR_APP_KEY' },\n})\n\nconst { data } = await res.json()\n```\n\n## Поля ответа\n\nОтвет разбит на несущие блоки: `data.overview` — обзор, `data.entities` — контракты сущностей, `data.importantNotes` и `data.knownIssues` — тонкости и ограничения, плюс указатели на разделы документации. Ниже — конверт ответа, структура элемента `data.entities[]` и вложенный контракт поля `fieldsDetailed`.\n\n| Поле | Тип | Описание |\n|------|-----|---------|\n| `success` | boolean | Всегда `true` при успехе |\n| `data` | object | Справочник: обзор, контракты сущностей, правила работы с API |\n| `data.overview` | string | Обзорное описание доступной поверхности API |\n| `data.entities` | array | Контракты сущностей, доступных ключу |\n| `data.entities[].name` | string | Идентификатор сущности для путей `\u002Fv1\u002F\u003Cname>` |\n| `data.entities[].basePath` | string | Базовый путь сущности. Для динамических сущностей содержит сегмент параметра, например `\u002Fv1\u002Fitems\u002F:entityTypeId` |\n| `data.entities[].scope` | string | Скоуп, необходимый для доступа к сущности |\n| `data.entities[].bitrixEntity` | string | Имя сущности на стороне Битрикс24 |\n| `data.entities[].operations` | object | Доступные операции. Ключи — `list`, `getById`, `create`, `update`, `delete`, `search`, `aggregate`, `batch`. Присутствуют только поддерживаемые операции |\n| `data.entities[].operations.\u003Cop>.method` | string | HTTP-метод операции |\n| `data.entities[].operations.\u003Cop>.path` | string | Путь операции. У части операций рядом приходят `params`, `example`, `note`, `requiredParams` |\n| `data.entities[].fields` | object | Компактная карта полей: имя поля соответствует строке `тип` или `тип, readonly` |\n| `data.entities[].fieldsDetailed` | object | Подробный контракт полей: имя поля соответствует объекту с типом и ограничениями |\n| `data.entities[].fieldsDetailed.\u003Cfield>.type` | string | Тип поля |\n| `data.entities[].fieldsDetailed.\u003Cfield>.readonly` | boolean | Поле только для чтения. Приходит, когда `true` |\n| `data.entities[].fieldsDetailed.\u003Cfield>.required` | boolean | Поле обязательно при создании. Приходит, когда `true` |\n| `data.entities[].fieldsDetailed.\u003Cfield>.createOnly` | boolean | Поле задаётся только при создании и не принимается при обновлении. Приходит, когда `true` |\n| `data.entities[].fieldsDetailed.\u003Cfield>.nullable` | boolean | Поле может прийти со значением `null`. Приходит, когда `true` |\n| `data.entities[].fieldsDetailed.\u003Cfield>.enum` | array | Допустимые значения поля-перечисления |\n| `data.entities[].fieldsDetailed.\u003Cfield>.enum[].value` | number или string | Значение, которое принимает поле |\n| `data.entities[].fieldsDetailed.\u003Cfield>.enum[].label` | string | Английское название значения |\n| `data.entities[].fieldsDetailed.\u003Cfield>.enum[].labelRu` | string | Русское название значения |\n| `data.entities[].fieldsDetailed.\u003Cfield>.enum[].description` | string | Пояснение значения. Приходит не для всех значений |\n| `data.entities[].responseFormats` | object | Примеры формы ответа для операций `list`, `get`, `create` |\n| `data.entities[].docs` | string | Ссылка на страницу документации сущности. Приходит, если страница существует |\n| `data.entities[].requiredListParams` | array | Обязательные query-параметры операции `list`. Приходит для сущностей, которые их требуют |\n| `data.entities[].requiredFilterFields` | array | Обязательные поля фильтра. Приходит для сущностей, которые их требуют |\n| `data.importantNotes` | object | Тонкости работы с полями, общие для нескольких сущностей — формат `stageId`, денежные поля сделки и другие |\n| `data.knownIssues` | array | Известные ограничения методов, отфильтрованные по скоупам ключа |\n| `data.knownIssues[].method` | string | Метод Битрикс24, к которому относится ограничение |\n| `data.knownIssues[].scope` | string | Скоуп метода |\n| `data.knownIssues[].issue` | string | Описание ограничения |\n| `data.knownIssues[].workaround` | string | Обходной путь |\n| `data.accessModeNote` | string | Напоминание о режиме «только чтение» и коде `WRITE_BLOCKED_READONLY_KEY` |\n| `data.changelog`, `data.errors`, `data.feedback`, `data.entityApi`, `data.entitiesIndex` | string | Указатели на разделы документации — URL и краткое описание раздела |\n| `data.workflows`, `data.notifications`, `data.calls`, `data.keysAuth` и другие разделы | object | Разделы за пределами entity-API. Каждый содержит `description`, массив `endpoints` с методами и путями и `docs` со ссылками на документацию |\n\n## Пример ответа\n\nПоказаны один элемент `data.entities` и часть несущих блоков. Полный ответ содержит контракты всех сущностей, доступных ключу.\n\n```json\n{\n  \"success\": true,\n  \"data\": {\n    \"overview\": \"VibeCode API proxies Bitrix24 REST API. 48 entities across CRM, tasks, users, calendar, disk, chat, and more.\",\n    \"entities\": [\n      {\n        \"name\": \"deals\",\n        \"basePath\": \"\u002Fv1\u002Fdeals\",\n        \"scope\": \"crm\",\n        \"bitrixEntity\": \"deal\",\n        \"operations\": {\n          \"list\": { \"method\": \"GET\", \"path\": \"\u002Fv1\u002Fdeals\", \"params\": [\"limit\", \"offset\"] },\n          \"getById\": { \"method\": \"GET\", \"path\": \"\u002Fv1\u002Fdeals\u002F:id\" },\n          \"create\": { \"method\": \"POST\", \"path\": \"\u002Fv1\u002Fdeals\" }\n        },\n        \"fields\": {\n          \"id\": \"number, readonly\",\n          \"title\": \"string\",\n          \"amount\": \"number\",\n          \"currency\": \"string\"\n        },\n        \"fieldsDetailed\": {\n          \"id\": { \"type\": \"number\", \"readonly\": true },\n          \"title\": { \"type\": \"string\" },\n          \"amount\": { \"type\": \"number\" },\n          \"currency\": { \"type\": \"string\" }\n        },\n        \"responseFormats\": {\n          \"list\": \"GET \u002Fv1\u002Fdeals → { success: true, data: [{ id, xmlId, lastActivityTime, title, ... }], meta: { total, hasMore } }\"\n        },\n        \"docs\": \"https:\u002F\u002Fvibecode.bitrix24.tech\u002Fdocs-content\u002Fentities\u002Fdeals.md\"\n      }\n    ],\n    \"importantNotes\": {\n      \"stageIdFormat\": {\n        \"description\": \"Deal stageId values use Bitrix24 category prefix format: C{categoryId}:{STAGE_CODE}.\"\n      }\n    },\n    \"knownIssues\": [\n      {\n        \"method\": \"crm.timeline.comment.list\",\n        \"scope\": \"crm\",\n        \"issue\": \"Ignores >=CREATED filter (date filtering does not work)\",\n        \"workaround\": \"Fetch all comments and filter by date on client side\"\n      }\n    ],\n    \"accessModeNote\": \"See \u002Fv1\u002Fme for current accessMode. Write methods return 403 WRITE_BLOCKED_READONLY_KEY when key is READONLY.\",\n    \"changelog\": \"https:\u002F\u002Fvibecode.bitrix24.tech\u002Fdocs-content\u002Fchangelog.md — API changelog: new features (NEW), fixes (FIX), breaking changes (BC), newest first.\"\n  }\n}\n```\n\n## Пример ответа при ошибке\n\n401 — не передан ключ:\n\n```json\n{\n  \"success\": false,\n  \"error\": {\n    \"code\": \"MISSING_API_KEY\",\n    \"message\": \"API key required. Pass via X-Api-Key header.\"\n  }\n}\n```\n\n## Ошибки\n\n| HTTP | Код | Описание |\n|------|-----|---------|\n| 401 | `MISSING_API_KEY` | Отсутствует заголовок `X-Api-Key` |\n| 401 | `INVALID_API_KEY` | Ключ не найден |\n| 401 | `KEY_INACTIVE` | Ключ отозван |\n| 401 | `KEY_EXPIRED` | Срок действия ключа прошёл |\n| 403 | `IP_NOT_ALLOWED` | Запрос с адреса вне списка разрешённых IP |\n\nПолный список общих ошибок API — [Ошибки](\u002Fdocs\u002Ferrors).\n\n## Известные особенности\n\n**Токен сессии не нужен.** Ключ авторизации `vibe_app_` читает контракт `data.entities[].fieldsDetailed` по одному заголовку `X-Api-Key`, без `Authorization: Bearer`. Это отличает эндпоинт от `GET \u002Fv1\u002F\u003Centity>\u002Ffields`, которому нужен пользовательский контекст. См. [Передача ключа](\u002Fdocs\u002Fkeys-auth#передача-ключа).\n\n**Состав `data.entities` зависит от ключа.** Ключ видит только сущности своих скоупов. Ключ авторизации дополнительно получает сущности бизнес-процессов, доступные приложению. Менеджмент-ключ получает справочник по всем скоупам и дополнительный блок `data.managementKeyNote`.\n\n**Ответ отдаётся целиком.** Эндпоинт не принимает параметров запроса: получить одну сущность или один раздел справочника нельзя, неизвестный параметр запроса игнорируется и ответ не меняется. Чтобы не читать ответ целиком при каждом запуске, опирайтесь на `ETag` и условные запросы.\n\n**Условные запросы и кэш.** Ответ несёт заголовок `ETag`. Повторный запрос с `If-None-Match` и тем же значением возвращает `304 Not Modified` без тела. Ответ кэшируется на стороне сервера около 5 минут, заголовок ответа — `Cache-Control: private, max-age=300`.\n\n**`fieldsDetailed` — статический контракт.** Он не содержит отображаемых названий полей и пользовательских полей портала `UF_CRM_*`. За отображаемыми названиями и пользовательскими полями обращайтесь к `GET \u002Fv1\u002F\u003Centity>\u002Ffields` с пользовательским контекстом.\n\n## Смотрите также\n\n- [Создание и использование ключа](\u002Fdocs\u002Fkeys-auth)\n- [Самоописание ключа](\u002Fdocs\u002Fkeys-auth\u002Fme)\n- [Режим доступа](\u002Fdocs\u002Fkeys-auth\u002Faccess-mode)\n- [Справочник эндпоинтов CRUD](\u002Fdocs\u002Fentity-api)\n- [Ошибки](\u002Fdocs\u002Ferrors)\n","2026-07-21",{}]