Для 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 — личный ключ
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-приложение
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 — личный ключ
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-приложение
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-документ.
{
"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 нет:
{
"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.