[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"docs-includes":3,"docs-tabs-includes":6},{"content":4,"lastmod":5},"# Связанные данные (include)\n\nЗагрузка связанных сущностей вместе с основными записями в одном запросе. Вместо отдельных вызовов для получения контакта, компании или ответственного — передайте параметр `include`, и Вайбкод вернёт всё в поле `_included`.\n\n> Параметр `include` опциональный и работает в трёх местах:\n> - `GET \u002Fv1\u002F{entity}\u002F{id}?include=...` — получение одной записи\n> - `GET \u002Fv1\u002F{entity}?include=...` — получение списка\n> - `POST \u002Fv1\u002F{entity}\u002Fsearch` — поиск (`include` в теле запроса как массив строк)\n\n## Как использовать\n\nПеречислите имена связей через запятую:\n\n### curl\n\n```bash\ncurl \"https:\u002F\u002Fvibecode.bitrix24.tech\u002Fv1\u002Fdeals\u002F741?include=contact,company\" \\\n  -H \"X-Api-Key: YOUR_API_KEY\"\n```\n\n### JavaScript\n\n```javascript\nconst res = await fetch('https:\u002F\u002Fvibecode.bitrix24.tech\u002Fv1\u002Fdeals\u002F741?include=contact,company', {\n  headers: { 'X-Api-Key': 'YOUR_API_KEY' },\n})\nconst { data } = await res.json()\n\n\u002F\u002F data._included.contacts — массив контактов сделки\n\u002F\u002F data._included.company  — компания (объект или null)\n```\n\nСвязанные данные появятся в поле `_included` каждой записи:\n\n```json\n{\n  \"success\": true,\n  \"data\": {\n    \"id\": 741,\n    \"title\": \"Поставка оборудования\",\n    \"contactId\": 71,\n    \"companyId\": 15,\n    \"_included\": {\n      \"contacts\": [\n        {\n          \"id\": 71,\n          \"name\": \"Иван\",\n          \"lastName\": \"Петров\",\n          \"phone\": [{ \"VALUE\": \"+79161234567\" }],\n          \"isPrimary\": true,\n          \"sort\": 10\n        }\n      ],\n      \"company\": {\n        \"id\": 15,\n        \"title\": \"ООО Ромашка\",\n        \"industry\": \"IT\"\n      }\n    }\n  }\n}\n```\n\n## Два типа связей\n\n### Один-к-одному\n\nСущность содержит поле-ссылку на связанный объект (например, `companyId` у контакта). Результат — один объект или `null`.\n\n```\nGET \u002Fv1\u002Fleads\u002F50?include=contact\n```\n\n```json\n{\n  \"data\": {\n    \"id\": 50,\n    \"title\": \"Заявка с сайта\",\n    \"contactId\": 71,\n    \"_included\": {\n      \"contact\": {\n        \"id\": 71,\n        \"name\": \"Иван\",\n        \"lastName\": \"Петров\"\n      }\n    }\n  }\n}\n```\n\nЕсли поле-ссылка пустое или равно 0, возвращается `null`:\n\n```json\n{\n  \"_included\": {\n    \"contact\": null\n  }\n}\n```\n\n### Много-ко-многим\n\nСвязь через промежуточную таблицу. Результат — массив объектов с дополнительными полями связи.\n\n```\nGET \u002Fv1\u002Fdeals\u002F741?include=contact\n```\n\n```json\n{\n  \"_included\": {\n    \"contacts\": [\n      {\n        \"id\": 71,\n        \"name\": \"Иван\",\n        \"lastName\": \"Петров\",\n        \"isPrimary\": true,\n        \"sort\": 10,\n        \"roleId\": 0\n      },\n      {\n        \"id\": 85,\n        \"name\": \"Мария\",\n        \"lastName\": \"Сидорова\",\n        \"isPrimary\": false,\n        \"sort\": 20,\n        \"roleId\": 0\n      }\n    ]\n  }\n}\n```\n\nОбратите внимание: имя связи в запросе — `contact` (ед. число), а в ответе — `contacts` (мн. число). Вайбкод автоматически плюрализует имя для массивов.\n\nДополнительные поля связи (`isPrimary`, `sort`, `roleId`) добавляются к каждому объекту — их значения приходят из промежуточной таблицы, а не из самой сущности.\n\n## Использование в списках и поиске\n\n### curl — список\n\n```bash\ncurl \"https:\u002F\u002Fvibecode.bitrix24.tech\u002Fv1\u002Fdeals?limit=10&include=company\" \\\n  -H \"X-Api-Key: YOUR_API_KEY\"\n```\n\n### JavaScript — список\n\n```javascript\nconst res = await fetch('https:\u002F\u002Fvibecode.bitrix24.tech\u002Fv1\u002Fdeals?limit=10&include=company', {\n  headers: { 'X-Api-Key': 'YOUR_API_KEY' },\n})\nconst { data, meta } = await res.json()\n\nfor (const deal of data) {\n  console.log(deal.title, '—', deal._included.company?.title ?? 'без компании')\n}\n\u002F\u002F meta.includeSkipped === true, если записей > 200\n```\n\nОтвет:\n\n```json\n{\n  \"success\": true,\n  \"data\": [\n    {\n      \"id\": 741,\n      \"title\": \"Поставка оборудования\",\n      \"companyId\": 15,\n      \"_included\": {\n        \"company\": { \"id\": 15, \"title\": \"ООО Ромашка\" }\n      }\n    },\n    {\n      \"id\": 742,\n      \"title\": \"Техподдержка\",\n      \"companyId\": 15,\n      \"_included\": {\n        \"company\": { \"id\": 15, \"title\": \"ООО Ромашка\" }\n      }\n    }\n  ],\n  \"total\": 150,\n  \"meta\": { \"hasMore\": true }\n}\n```\n\nВайбкод дедуплицирует запросы: если несколько записей ссылаются на одну компанию, она загружается один раз.\n\n### curl — поиск\n\nВ поиске `include` передаётся в теле запроса как массив.\n\n```bash\ncurl -X POST \"https:\u002F\u002Fvibecode.bitrix24.tech\u002Fv1\u002Fdeals\u002Fsearch\" \\\n  -H \"X-Api-Key: YOUR_API_KEY\" \\\n  -H \"Content-Type: application\u002Fjson\" \\\n  -d '{\n    \"filter\": { \"stageId\": \"NEW\", \"amount\": { \"$gte\": 100000 } },\n    \"include\": [\"contact\", \"company\"],\n    \"limit\": 50\n  }'\n```\n\n### JavaScript — поиск\n\n```javascript\nconst res = await fetch('https:\u002F\u002Fvibecode.bitrix24.tech\u002Fv1\u002Fdeals\u002Fsearch', {\n  method: 'POST',\n  headers: {\n    'X-Api-Key': 'YOUR_API_KEY',\n    'Content-Type': 'application\u002Fjson',\n  },\n  body: JSON.stringify({\n    filter: { stageId: 'NEW', amount: { $gte: 100000 } },\n    include: ['contact', 'company'],\n    limit: 50,\n  }),\n})\nconst { data } = await res.json()\n```\n\n## Несколько связей в одном запросе\n\nМожно запросить до 3 связей одновременно:\n\n```\nGET \u002Fv1\u002Fquotes\u002F18?include=deal,contact,company\n```\n\n```json\n{\n  \"_included\": {\n    \"deal\": { \"id\": 741, \"title\": \"Поставка оборудования\" },\n    \"contact\": { \"id\": 71, \"name\": \"Иван\", \"lastName\": \"Петров\" },\n    \"company\": { \"id\": 15, \"title\": \"ООО Ромашка\" }\n  }\n}\n```\n\n## Лимиты\n\n| Параметр | Значение |\n|----------|---------|\n| Максимум связей в запросе | 3 |\n| Максимум записей для include | 200 |\n\nЕсли в списке или поиске больше 200 записей, include **пропускается** и в `meta` добавляется флаг:\n\n```json\n{\n  \"data\": [ ... ],\n  \"meta\": {\n    \"hasMore\": true,\n    \"includeSkipped\": true\n  }\n}\n```\n\nЧтобы получить связанные данные для больших выборок — уменьшите `limit` до 200 или меньше.\n\n## Доступные связи по сущностям\n\nУзнать доступные include для конкретной сущности можно через эндпоинт полей:\n\n```bash\ncurl \"https:\u002F\u002Fvibecode.bitrix24.tech\u002Fv1\u002Fdeals\u002Ffields\" \\\n  -H \"X-Api-Key: YOUR_API_KEY\"\n```\n\nВ ответе будет поле `include` со списком доступных связей:\n\n```json\n{\n  \"success\": true,\n  \"data\": {\n    \"fields\": { ... },\n    \"include\": [\"contact\", \"company\"]\n  }\n}\n```\n\nДоступные связи зависят от сущности. Какие именно include поддерживает конкретная сущность — указано в документации каждого метода и в ответе `GET \u002Fv1\u002F{entity}\u002Ffields` (поле `include`).\n\n## Ошибки\n\n| HTTP | Код | Описание |\n|------|-----|---------|\n| 400 | `INCLUDE_LIMIT_EXCEEDED` | Запрошено более 3 связей |\n| 400 | `INVALID_INCLUDE` | Связь не найдена. Ответ содержит список доступных связей |\n\nЕсли у сущности вообще нет связей (например, `departments`), любой `include` вернёт `INVALID_INCLUDE` с пустым списком `Available:`.\n\nПример ошибки:\n\n```json\n{\n  \"success\": false,\n  \"error\": {\n    \"code\": \"INVALID_INCLUDE\",\n    \"message\": \"Unknown include 'manager'. Available: contact, company, quote\"\n  }\n}\n```\n\n## Связанные разделы\n\n- [Entity API](.\u002Fentity-api.md) — CRUD-операции, пагинация, агрегация\n- [Фильтрация](.\u002Ffiltering.md) — три синтаксиса фильтров\n- [Batch API](.\u002Fbatch.md) — объединение вызовов\n- [Все сущности](.\u002Fentities-index.md) — полный список сущностей\n- [Коды ошибок](.\u002Ferrors.md) — справочник ошибок платформы\n","2026-06-24",{}]