Документы по CRM-сущности

GET /v1/crm-documents

Возвращает документы, прикреплённые к конкретной записи CRM — сделке, контакту, компании, лиду, предложению, счёту или элементу смарт-процесса. В отличие от списка всех документов портала, отбор идёт по типу записи и её идентификатору.

Параметры

Параметр Тип Обяз. По умолч. Описание
entityTypeId (query) number да — Тип записи CRM. Допустимые значения — в списке «Типы записей CRM» ниже
entityId (query) number нет — ID записи. Без него возвращаются документы всех записей указанного типа. Где взять ID по типу — в списке «Типы записей CRM» ниже
select (query) string нет — Выборка полей: ?select=id,title,number
order (query) object нет — Сортировка: ?order[updateTime]=desc. Направление — asc или desc
start (query) number нет 0 Смещение для постраничного чтения

За один вызов возвращается до 50 документов. Для следующей страницы передайте значение meta.next в параметр start. Когда документов больше нет, meta.next равно null.

Типы записей CRM

Значение entityTypeId и эндпоинт, откуда взять entityId:

  • 1 — лид. ID записи: GET /v1/leads
  • 2 — сделка. ID записи: GET /v1/deals
  • 3 — контакт. ID записи: GET /v1/contacts
  • 4 — компания. ID записи: GET /v1/companies
  • 7 — предложение. ID записи: GET /v1/quotes
  • 31 — счёт. ID записи: GET /v1/invoices
  • 128 и выше — элемент смарт-процесса. Значение entityTypeId — из GET /v1/smart-processes, ID записи — из GET /v1/items/:entityTypeId

Примеры

curl — личный ключ

Terminal 
curl "https://vibecode.bitrix24.tech/v1/crm-documents?entityTypeId=2&entityId=15&order[updateTime]=desc" \
  -H "X-Api-Key: YOUR_API_KEY"

curl — OAuth-приложение

Terminal 
curl "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 — личный ключ

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-приложение

javascript 
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 Ссылка на скачивание для приложения
data[].pdfUrlMachine string Ссылка на PDF для приложения
data[].imageUrlMachine string Ссылка на изображение для приложения
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, если документов больше нет

Пример ответа

JSON 
{
  "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://example.bitrix24.ru/rest/1/APP_TOKEN/crm.documentgenerator.document.download/?id=405",
      "pdfUrlMachine": "https://example.bitrix24.ru/rest/1/APP_TOKEN/crm.documentgenerator.document.getPdf/?id=405",
      "imageUrlMachine": "https://example.bitrix24.ru/rest/1/APP_TOKEN/crm.documentgenerator.document.getImage/?id=405",
      "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://example.bitrix24.ru/rest/1/APP_TOKEN/crm.documentgenerator.document.download/?id=406",
      "pdfUrlMachine": "https://example.bitrix24.ru/rest/1/APP_TOKEN/crm.documentgenerator.document.getPdf/?id=406",
      "imageUrlMachine": "https://example.bitrix24.ru/rest/1/APP_TOKEN/crm.documentgenerator.document.getImage/?id=406",
      "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, дробное или нечисловое возвращает тот же код:

JSON 
{
  "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 Код Описание
400 MISSING_PARAMS Не передан entityTypeId или его значение не является положительным целым числом
400 INVALID_ENTITY_ID entityId передан, но не является положительным целым числом
400 INVALID_START start передан, но не является целым числом 0 или больше
403 SCOPE_DENIED Ключу не хватает скоупа crm
401 MISSING_API_KEY Не передан заголовок X-Api-Key
401 TOKEN_MISSING Ключу авторизации не сопоставлены токены — ключ OAuth-приложения вызван без пользовательской сессии
422 BITRIX_ERROR Модуль генератора документов не установлен на портале

Полный список общих ошибок API — Ошибки.

Известные особенности

Параметр select ограничивает набор полей, но ссылки на файлы downloadUrl, pdfUrl, imageUrl вместе с машинными вариантами, а также stampsEnabled и values возвращаются всегда, даже если их нет в выборке.

Смотрите также