Для AI-агентов: markdown этой страницы — /docs-content/entities/documents/crm-create.md индекс документации — /llms.txt

Создать CRM-документ

POST /v1/crm-documents

Формирует документ по шаблону CRM для записи CRM — сделки, контакта, компании или элемента смарт-процесса — и прикрепляет его к этой записи. Поля передаются в корне JSON без обёртки fields.

Поля запроса (body)

Поле Тип Обяз. Описание
ПолеtemplateId Типnumber Обяз.да ОписаниеID шаблона CRM, положительное целое число. Шаблоны, доступные для записи: GET /v1/crm-document-templates/available
ПолеentityTypeId Типnumber Обяз.да ОписаниеТип записи CRM, положительное целое число: 2 — сделка, 3 — контакт, 4 — компания. Остальные типы — в списке «Типы записей CRM» на странице GET /v1/crm-documents
ПолеentityId Типnumber Обяз.да ОписаниеID записи, положительное целое число. Источник зависит от типа: сделки — GET /v1/deals, контакты — GET /v1/contacts, компании — GET /v1/companies
Полеvalues Типobject Обяз.нет ОписаниеЗначения полей шаблона. Например, DocumentNumber задаёт номер документа
ПолеstampsEnabled Типboolean Обяз.нет ОписаниеВключить печати и подписи. Если поле не передано, печати выключены. Есть ли печати в шаблоне, показывает поле changeStampsEnabled ответа

Другие поля, например title, запрос не принимает. Флаг печатей передаётся только в корне тела, не внутри values.

Примеры

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

Terminal
curl -X POST "https://vibecode.bitrix24.tech/v1/crm-documents" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "templateId": 87,
    "entityTypeId": 2,
    "entityId": 8781,
    "values": { "DocumentNumber": "VD-100" }
  }'

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

Terminal
curl -X POST "https://vibecode.bitrix24.tech/v1/crm-documents" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "templateId": 87,
    "entityTypeId": 2,
    "entityId": 8781,
    "values": { "DocumentNumber": "VD-100" }
  }'

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

javascript
const res = await fetch('https://vibecode.bitrix24.tech/v1/crm-documents', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    templateId: 87,
    entityTypeId: 2,
    entityId: 8781,
    values: { DocumentNumber: 'VD-100' },
  }),
})

const { success, data } = await res.json()
console.log('Документ:', data.id, data.number)

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

javascript
const res = await fetch('https://vibecode.bitrix24.tech/v1/crm-documents', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    templateId: 87,
    entityTypeId: 2,
    entityId: 8781,
    values: { DocumentNumber: 'VD-100' },
  }),
})

const { success, data } = await res.json()

Поля ответа

Возвращается HTTP-статус 201 Created и созданный документ. Полное описание полей документа — на странице Получить CRM-документ.

Поле Тип Описание
Полеsuccess Типboolean ОписаниеВсегда true при успехе
Полеdata.id Типnumber ОписаниеИдентификатор созданного документа. Приходит числом, в отличие от ответа GET /v1/crm-documents/:id
Полеdata.title Типstring ОписаниеНазвание документа, сформированное по шаблону
Полеdata.number Типstring ОписаниеНомер документа. Задаётся values.DocumentNumber или нумератором шаблона
Полеdata.templateId Типstring ОписаниеID шаблона
Полеdata.entityTypeId Типstring ОписаниеТип записи CRM
Полеdata.entityId Типnumber ОписаниеID записи CRM
Полеdata.values Типobject ОписаниеПереданные значения полей шаблона вместе со служебными ключами
Полеdata.stampsEnabled Типboolean ОписаниеВключены ли печати и подписи
Полеdata.changeStampsEnabled Типboolean ОписаниеМожно ли включить печати: false, если в шаблоне их нет
Полеdata.createdBy Типnumber ОписаниеID создателя. Список: GET /v1/users
Полеdata.downloadUrl Типstring ОписаниеСсылка на файл DOCX для сотрудника в браузере
Полеdata.downloadUrlMachine Типstring ОписаниеАдрес /v1/crm-documents/:id/download. Нужен X-Api-Key со скоупом crm

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

Показаны основные поля. Полный список: Получить CRM-документ.

JSON
{
  "success": true,
  "data": {
    "changeStampsEnabled": false,
    "downloadUrl": "https://example.bitrix24.ru/bitrix/services/main/ajax.php?action=crm.documentgenerator.document.download&SITE_ID=s1&id=1981",
    "publicUrl": null,
    "title": "Адреса VD-100",
    "number": "VD-100",
    "id": 1981,
    "createTime": "2026-10-08T17:55:00+03:00",
    "createdBy": 1317,
    "stampsEnabled": false,
    "isTransformationError": false,
    "values": {
      "productsTableVariant": "",
      "stampsEnabled": false,
      "_creationMethod": "rest",
      "DocumentNumber": "VD-100"
    },
    "templateId": "87",
    "entityId": 8781,
    "entityTypeId": "2",
    "downloadUrlMachine": "https://vibecode.bitrix24.tech/v1/crm-documents/1981/download"
  }
}

Пример ответа при ошибке

404 — шаблона с таким templateId нет:

JSON
{
  "success": false,
  "error": {
    "code": "ENTITY_NOT_FOUND",
    "message": "Шаблон не найден"
  }
}

Ошибки

HTTP Код Описание
HTTP400 КодMISSING_REQUIRED_FIELDS ОписаниеТело не JSON-объект, например массив. Сообщение: A document body is required
HTTP400 КодMISSING_REQUIRED_FIELDS ОписаниеНе передан templateId, entityTypeId или entityId, либо значение не положительное целое число. Сообщение: templateId, entityTypeId and entityId must be positive integers
HTTP400 КодREADONLY_FIELD ОписаниеВ теле поле, которого нет в таблице выше, например title
HTTP400 КодINVALID_PARAMS Описаниеvalues не объект, values содержит stampsEnabled или stampsEnabled не логическое значение
HTTP404 КодENTITY_NOT_FOUND ОписаниеШаблона с таким templateId нет. Сообщение: Шаблон не найден
HTTP422 КодBITRIX_ERROR ОписаниеТип entityTypeId не поддерживается для документов, например 999. Сообщение: No provider for entityTypeId
HTTP502 КодBITRIX_INVALID_RESPONSE ОписаниеБитрикс24 ответил без документа
HTTP403 КодBITRIX_ACCESS_DENIED ОписаниеНет доступа к записи CRM, в том числе к контакту, которого нет. Сообщение: Access denied
HTTP403 КодWRITE_BLOCKED_READONLY_KEY ОписаниеКлюч работает в режиме только для чтения
HTTP403 КодSCOPE_DENIED ОписаниеКлючу не хватает скоупа crm
HTTP401 КодMISSING_API_KEY ОписаниеНе передан заголовок X-Api-Key
HTTP401 КодTOKEN_MISSING ОписаниеКлючу не сопоставлены токены — ключ OAuth-приложения вызван без пользовательской сессии

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

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

Существование сделки не проверяется. С entityTypeId: 2 документ создаётся и для entityId, которого нет среди сделок: ответ 201. Для контакта с несуществующим ID приходит 403 BITRIX_ACCESS_DENIED. Проверяйте запись заранее, например через GET /v1/deals/:id.

PDF и изображение появляются позже. В ответе создания есть только ссылки на DOCX. Ссылки на PDF и изображение приходят в GET /v1/crm-documents/:id, когда файлы готовы. До этого скачивание PDF отвечает 409 DOCUMENT_NOT_READY.

ID можно передать строкой. "templateId": "87" принимается так же, как 87.

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