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