Для AI-агентов: markdown этой страницы — /docs-content/entities/documents/crm-list.md индекс документации — /llms.txt
Документы по CRM-сущности
GET /v1/crm-documents
Возвращает документы, прикреплённые к конкретной записи CRM — сделке, контакту, компании, лиду, предложению, счёту или элементу смарт-процесса. В отличие от списка всех документов портала, отбор идёт по типу записи и её идентификатору.
Параметры
| Параметр | Тип | Обяз. | По умолч. | Описание |
|---|---|---|---|---|
ПараметрentityTypeId (query) |
Типnumber | Обяз.да | По умолч.— | ОписаниеТип записи CRM — одно положительное целое, переданное один раз. Допустимые значения — в списке «Типы записей CRM» ниже. Принимается и написание entityTypeID, но только одно из двух |
ПараметрentityId (query) |
Типnumber | Обяз.нет | По умолч.— | ОписаниеID записи — одно положительное целое, переданное не более одного раза. Принимается и написание entityID, но только одно из двух. Без параметра, а также с одним пустым значением entityId=, возвращаются документы всех записей указанного типа. Где взять ID по типу — в списке «Типы записей CRM» ниже |
Параметрselect (query) |
Типstring | Обяз.нет | По умолч.— | ОписаниеВыборка полей: ?select=id,title,number |
Параметрorder (query) |
Типobject | Обяз.нет | По умолч.— | ОписаниеСортировка: ?order[updateTime]=desc. Направление — asc или desc. Скобка одноуровневая: значение записи — это направление, а второй уровень под именем поля даёт 400 INVALID_ORDER |
Параметрstart (query) |
Типnumber | Обяз.нет | По умолч.0 |
ОписаниеСмещение для постраничного чтения — одно целое число 0 или больше, переданное не более одного раза. Пустое значение start= равносильно 0. Написаний-синонимов у параметра нет |
За один вызов возвращается до 50 документов. Для следующей страницы передайте значение meta.next в параметр start. Когда документов больше нет, meta.next равно null.
Типы записей CRM
Значение entityTypeId и эндпоинт, откуда взять entityId:
1— лид. ID записи:GET /v1/leads2— сделка. ID записи:GET /v1/deals3— контакт. ID записи:GET /v1/contacts4— компания. ID записи:GET /v1/companies7— предложение. ID записи:GET /v1/quotes31— счёт. ID записи:GET /v1/invoices128и выше — элемент смарт-процесса. ЗначениеentityTypeId— изGET /v1/smart-processes, ID записи — изGET /v1/items/:entityTypeId
Общий параметр filter этим эндпоинтом не применяется. По умолчанию API сохраняет прежний ответ HTTP 200 и прежние данные, добавляет заголовок Warning: 299 - "filter is not supported on this endpoint and was ignored", а сервер фиксирует использование неподдерживаемого фильтра в журнале.
Примеры
curl — личный ключ
curl -g "https://vibecode.bitrix24.tech/v1/crm-documents?entityTypeId=2&entityId=15&order[updateTime]=desc" \
-H "X-Api-Key: YOUR_API_KEY"
curl — OAuth-приложение
curl -g "https://vibecode.bitrix24.tech/v1/crm-documents?entityTypeId=2&entityId=15&order[updateTime]=desc" \
-H "X-Api-Key: YOUR_APP_KEY" \
-H "Authorization: Bearer USER_SESSION_TOKEN"
JavaScript — личный ключ
const res = await fetch('https://vibecode.bitrix24.tech/v1/crm-documents?entityTypeId=2&entityId=15&order[updateTime]=desc', {
headers: {
'X-Api-Key': 'YOUR_API_KEY',
},
})
const { success, data, meta } = await res.json()
console.log(`У записи ${meta.total} документов`)
JavaScript — OAuth-приложение
const res = await fetch('https://vibecode.bitrix24.tech/v1/crm-documents?entityTypeId=2&entityId=15&order[updateTime]=desc', {
headers: {
'X-Api-Key': 'YOUR_APP_KEY',
'Authorization': 'Bearer USER_SESSION_TOKEN',
},
})
const { success, data, meta } = await res.json()
Поля ответа
Идентификаторы возвращаются строками.
| Поле | Тип | Описание |
|---|---|---|
Полеsuccess |
Типboolean | ОписаниеВсегда true при успехе |
Полеdata |
Типarray | ОписаниеМассив документов |
Полеdata[].id |
Типstring | ОписаниеИдентификатор документа |
Полеdata[].title |
Типstring | ОписаниеНазвание документа |
Полеdata[].number |
Типstring | ОписаниеНомер документа |
Полеdata[].templateId |
Типstring | ОписаниеИдентификатор шаблона. Источник — GET /v1/doc-templates |
Полеdata[].entityTypeId |
Типstring | ОписаниеТип записи CRM, к которой прикреплён документ |
Полеdata[].entityId |
Типstring | ОписаниеID записи CRM, к которой прикреплён документ |
Полеdata[].fileId |
Типstring | ОписаниеИдентификатор готового файла |
Полеdata[].pdfId |
Типstring | ОписаниеИдентификатор PDF-версии |
Полеdata[].imageId |
Типstring | ОписаниеИдентификатор изображения-превью |
Полеdata[].downloadUrl |
Типstring | ОписаниеСсылка на скачивание файла для пользователя |
Полеdata[].pdfUrl |
Типstring | ОписаниеСсылка на PDF для пользователя |
Полеdata[].imageUrl |
Типstring | ОписаниеСсылка на изображение-превью для пользователя |
Полеdata[].downloadUrlMachine |
Типstring | ОписаниеАдрес Vibe API; нужен X-Api-Key со скоупом crm |
Полеdata[].pdfUrlMachine |
Типstring | ОписаниеАдрес Vibe API; нужен X-Api-Key со скоупом crm |
Полеdata[].imageUrlMachine |
Типstring | ОписаниеАдрес Vibe API; нужен X-Api-Key со скоупом crm |
Полеdata[].stampsEnabled |
Типboolean | ОписаниеВключены ли подпись и печать |
Полеdata[].values |
Типobject | ОписаниеЗначения полей-меток шаблона |
Полеdata[].createTime |
Типstring | ОписаниеДата создания в формате ISO 8601 |
Полеdata[].updateTime |
Типstring | ОписаниеДата изменения в формате ISO 8601 |
Полеdata[].createdBy |
Типstring | ОписаниеID создателя. Источник — GET /v1/users |
Полеdata[].updatedBy |
Типstring | null | ОписаниеID последнего редактора. Источник — GET /v1/users |
Полеmeta.total |
Типnumber | ОписаниеКоличество документов у записи |
Полеmeta.start |
Типnumber | ОписаниеСмещение текущей страницы |
Полеmeta.next |
Типnumber | null | ОписаниеСмещение следующей страницы. null, если документов больше нет |
Пример ответа
{
"success": true,
"data": [
{
"id": "405",
"title": "Счёт А161",
"number": "А161",
"templateId": "1",
"entityTypeId": "2",
"entityId": "15",
"fileId": "1369",
"pdfId": "1373",
"imageId": "1371",
"downloadUrl": "https://example.bitrix24.ru/bitrix/services/main/ajax.php?action=crm.documentgenerator.document.download&id=405",
"pdfUrl": "https://example.bitrix24.ru/bitrix/services/main/ajax.php?action=crm.documentgenerator.document.getPdf&id=405",
"imageUrl": "https://example.bitrix24.ru/bitrix/services/main/ajax.php?action=crm.documentgenerator.document.getImage&id=405",
"downloadUrlMachine": "https://vibecode.bitrix24.tech/v1/crm-documents/405/download",
"pdfUrlMachine": "https://vibecode.bitrix24.tech/v1/crm-documents/405/pdf",
"imageUrlMachine": "https://vibecode.bitrix24.tech/v1/crm-documents/405/image",
"stampsEnabled": false,
"values": { "_creationMethod": "public" },
"createTime": "2026-01-18T11:10:00+03:00",
"updateTime": "2026-01-18T11:10:00+03:00",
"createdBy": "29",
"updatedBy": null
},
{
"id": "406",
"title": "Акт А162",
"number": "А162",
"templateId": "4",
"entityTypeId": "2",
"entityId": "15",
"fileId": "1402",
"pdfId": "1404",
"imageId": "1403",
"downloadUrl": "https://example.bitrix24.ru/bitrix/services/main/ajax.php?action=crm.documentgenerator.document.download&id=406",
"pdfUrl": "https://example.bitrix24.ru/bitrix/services/main/ajax.php?action=crm.documentgenerator.document.getPdf&id=406",
"imageUrl": "https://example.bitrix24.ru/bitrix/services/main/ajax.php?action=crm.documentgenerator.document.getImage&id=406",
"downloadUrlMachine": "https://vibecode.bitrix24.tech/v1/crm-documents/406/download",
"pdfUrlMachine": "https://vibecode.bitrix24.tech/v1/crm-documents/406/pdf",
"imageUrlMachine": "https://vibecode.bitrix24.tech/v1/crm-documents/406/image",
"stampsEnabled": false,
"values": { "_creationMethod": "public" },
"createTime": "2026-01-19T09:30:00+03:00",
"updateTime": "2026-01-19T09:30:00+03:00",
"createdBy": "29",
"updatedBy": null
}
],
"meta": { "total": 2, "start": 0, "next": null }
}
Пример ответа при ошибке
400 — entityTypeId не передан или некорректен. Значение 0, дробное или нечисловое возвращает тот же код:
{
"success": false,
"error": {
"code": "MISSING_PARAMS",
"message": "Query parameter `entityTypeId` (positive integer) is required. Common values: 1=LEAD, 2=DEAL, 3=CONTACT, 4=COMPANY, 7=QUOTE, 31=INVOICE, 128+ for smart processes."
}
}
Ошибки
| HTTP | Код | Описание |
|---|---|---|
| HTTP200 | КодWarning: 299 |
ОписаниеФильтр игнорируется по умолчанию; прежние данные сохраняются, предупреждение передаётся заголовком Warning. |
| HTTP400 только при включённом строгом режиме | КодUNSUPPORTED_FILTER |
ОписаниеСерверный режим выключен по умолчанию; до его включения эндпоинт сохраняет HTTP 200 и прежние данные. |
| HTTP400 | КодMISSING_PARAMS |
ОписаниеНе передан entityTypeId или его значение не является положительным целым числом |
| HTTP400 | КодINVALID_ENTITY_TYPE |
ОписаниеТип записи передан не одним значением: параметр повторён, переданы оба написания entityTypeId и entityTypeID сразу либо использована скобочная форма — entityTypeId[]=2, entityTypeId[0]=2. Отказ приходит и при одинаковых значениях |
| HTTP400 | КодINVALID_ENTITY_ID |
ОписаниеentityId передан, но не является положительным целым числом |
| HTTP400 | КодINVALID_ENTITY_ID |
ОписаниеID записи передан не одним значением: параметр повторён, переданы оба написания entityId и entityID сразу либо использована скобочная форма — entityId[]=7, entityId[0]=7. Отказ приходит и при одинаковых значениях |
| HTTP400 | КодINVALID_START |
Описаниеstart передан, но не является целым числом 0 или больше |
| HTTP400 | КодINVALID_START |
ОписаниеСмещение передано не одним значением: параметр повторён либо использована скобочная форма — start[]=1, start[0]=1. Отказ приходит и при одинаковых значениях |
| HTTP400 | КодINVALID_ORDER |
ОписаниеЗапись сортировки несёт не направление, а вложенную структуру: под именем поля стоит второй уровень скобок — order[updateTime][x]=desc, order[updateTime][]=desc, order[updateTime][0]=desc. Написание, которое разбору не поддаётся вовсе — order=desc, order[]=desc, третий уровень скобок, — по-прежнему оставляет выдачу без сортировки, а не отказом |
| HTTP403 | КодSCOPE_DENIED |
ОписаниеКлючу не хватает скоупа crm |
| HTTP401 | КодMISSING_API_KEY |
ОписаниеНе передан заголовок X-Api-Key |
| HTTP401 | КодTOKEN_MISSING |
ОписаниеКлючу авторизации не сопоставлены токены — ключ OAuth-приложения вызван без пользовательской сессии |
| HTTP422 | КодBITRIX_ERROR |
ОписаниеМодуль генератора документов не установлен на портале |
Полный список общих ошибок API — Ошибки.
Известные особенности
Параметр select ограничивает набор полей, но ссылки на файлы downloadUrl, pdfUrl, imageUrl вместе с машинными вариантами, а также stampsEnabled и values возвращаются всегда, даже если их нет в выборке.
Проверка однократности entityId и start считает вхождения параметра, а не значения, и не защищает от подмешивания параметров: незакодированное значение может внести в строку запроса любой дополнительный параметр, включая те, что проверку проходят. Кодируйте пользовательский ввод при построении строки запроса.