Для 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 Код Описание
400 MISSING_REQUIRED_FIELDS Тело не JSON-объект, например массив. Сообщение: A document body is required
400 MISSING_REQUIRED_FIELDS Не передан templateId, entityTypeId или entityId, либо значение не положительное целое число. Сообщение: templateId, entityTypeId and entityId must be positive integers
400 READONLY_FIELD В теле поле, которого нет в таблице выше, например title
400 INVALID_PARAMS values не объект, values содержит stampsEnabled или stampsEnabled не логическое значение
404 ENTITY_NOT_FOUND Шаблона с таким templateId нет. Сообщение: Шаблон не найден
422 BITRIX_ERROR Тип entityTypeId не поддерживается для документов, например 999. Сообщение: No provider for entityTypeId
502 BITRIX_INVALID_RESPONSE Битрикс24 ответил без документа
403 BITRIX_ACCESS_DENIED Нет доступа к записи CRM, в том числе к контакту, которого нет. Сообщение: Access denied
403 WRITE_BLOCKED_READONLY_KEY Ключ работает в режиме только для чтения
403 SCOPE_DENIED Ключу не хватает скоупа crm
401 MISSING_API_KEY Не передан заголовок X-Api-Key
401 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.

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