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

Загрузить CRM-документ

POST /v1/crm-documents/upload

Прикрепляет к записи CRM готовый файл документа, сформированный вне Битрикс24, без шаблона. Файл передаётся строкой base64, поля — внутри объекта fields.

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

Поле Тип Обяз. Описание
fields.entityTypeId number да Тип записи CRM, положительное целое число: 2 — сделка, 3 — контакт, 4 — компания. Остальные типы — в списке «Типы записей CRM» на странице GET /v1/crm-documents
fields.entityId number да ID записи, положительное целое число. Источник зависит от типа: сделки — GET /v1/deals, контакты — GET /v1/contacts, компании — GET /v1/companies
fields.title string да Название документа
fields.number string да Номер документа. Число вместо строки отклоняется
fields.region string да Регион документа, например ru
fields.fileContent string да Содержимое файла DOCX строкой base64, не больше 2 МиБ после декодирования
fields.pdfContent string нет PDF-версия документа строкой base64, не больше 2 МиБ после декодирования
fields.imageContent string нет Изображение документа строкой base64, не больше 2 МиБ после декодирования

Тело запроса целиком — не больше 3 МиБ. Поля id, fileId, pdfId, imageId, moduleId, providerClassName и value заполняет Битрикс24: запрос с любым из них отклоняется с 400 READONLY_FIELD.

Примеры

В примерах contract.docx — ваш файл документа. Тело запроса собирается в файл document.json, затем отправляется.

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

Terminal 
printf '{"fields":{"entityTypeId":2,"entityId":8781,"title":"Договор поставки","number":"VD-1","region":"ru","fileContent":"%s"}}' \
  "$(base64 < contract.docx | tr -d '\n')" > document.json

curl -X POST "https://vibecode.bitrix24.tech/v1/crm-documents/upload" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @document.json

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

Terminal 
printf '{"fields":{"entityTypeId":2,"entityId":8781,"title":"Договор поставки","number":"VD-1","region":"ru","fileContent":"%s"}}' \
  "$(base64 < contract.docx | tr -d '\n')" > document.json

curl -X POST "https://vibecode.bitrix24.tech/v1/crm-documents/upload" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  --data-binary @document.json

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

javascript 
import { readFile } from 'node:fs/promises'

const fileContent = (await readFile('contract.docx')).toString('base64')

const res = await fetch('https://vibecode.bitrix24.tech/v1/crm-documents/upload', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    fields: {
      entityTypeId: 2,
      entityId: 8781,
      title: 'Договор поставки',
      number: 'VD-1',
      region: 'ru',
      fileContent,
    },
  }),
})

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

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

javascript 
import { readFile } from 'node:fs/promises'

const fileContent = (await readFile('contract.docx')).toString('base64')

const res = await fetch('https://vibecode.bitrix24.tech/v1/crm-documents/upload', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    fields: {
      entityTypeId: 2,
      entityId: 8781,
      title: 'Договор поставки',
      number: 'VD-1',
      region: 'ru',
      fileContent,
    },
  }),
})

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

Поля ответа

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

Поле Тип Описание
success boolean Всегда true при успехе
data.id string Идентификатор документа
data.title string Название из fields.title
data.number string Номер из fields.number
data.entityTypeId string Тип записи CRM
data.entityId string ID записи CRM
data.templateId string Служебный шаблон загруженных документов. В списках шаблонов его нет
data.createdBy string ID сотрудника, загрузившего документ. Список: GET /v1/users
data.downloadUrlMachine string Адрес /v1/crm-documents/:id/download. Нужен X-Api-Key со скоупом crm
data.pdfUrlMachine string Адрес /v1/crm-documents/:id/pdf. Сразу в ответе, если передан fields.pdfContent

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

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

JSON 
{
  "success": true,
  "data": {
    "downloadUrl": "https://example.bitrix24.ru/bitrix/services/main/ajax.php?action=crm.documentgenerator.document.download&SITE_ID=s1&id=1985",
    "publicUrl": null,
    "title": "Договор поставки",
    "number": "VD-1",
    "id": "1985",
    "createTime": "2026-10-08T17:59:45+03:00",
    "createdBy": "1317",
    "stampsEnabled": false,
    "isTransformationError": false,
    "templateId": "275",
    "entityId": "8781",
    "entityTypeId": "2",
    "downloadUrlMachine": "https://vibecode.bitrix24.tech/v1/crm-documents/1985/download"
  }
}

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

400 — fileContent не строка base64:

JSON 
{
  "success": false,
  "error": {
    "code": "INVALID_PARAMS",
    "message": "fileContent must be base64"
  }
}

Ошибки

HTTP Код Описание
400 MISSING_REQUIRED_FIELDS Нет объекта fields. Сообщение: fields is required
400 MISSING_REQUIRED_FIELDS Обязательное поле не передано или пустое. Сообщение называет поля: Empty required fields: number
400 READONLY_FIELD В fields передано поле, которое заполняет Битрикс24, например id
400 INVALID_PARAMS entityTypeId или entityId не положительное целое число
400 INVALID_PARAMS title, number или region не строка
400 INVALID_PARAMS fileContent, pdfContent или imageContent не строка base64. Сообщение называет поле
400 INVALID_PARAMS Тип entityTypeId не поддерживается для документов, например 999. Сообщение: Wrong "entityTypeId" field value
413 PAYLOAD_TOO_LARGE Файл больше 2 МиБ после декодирования. Сообщение называет поле: fileContent must not exceed 2 MiB
413 PAYLOAD_TOO_LARGE Тело запроса больше 3 МиБ. Сообщение: Request body too large
429 LARGE_BODY_BACKEND_BUSY Тело больше 1 МиБ, а платформа уже обрабатывает предельный объём крупных тел. Повторите запрос через Retry-After секунд
502 BITRIX_INVALID_RESPONSE Битрикс24 ответил без документа
403 WRITE_BLOCKED_READONLY_KEY Ключ работает в режиме только для чтения
403 SCOPE_DENIED Ключу не хватает скоупа crm
401 MISSING_API_KEY Не передан заголовок X-Api-Key
401 TOKEN_MISSING Ключу не сопоставлены токены — ключ OAuth-приложения вызван без пользовательской сессии

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

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

Формат файла не проверяется. Проверяется только то, что fileContent — корректная строка base64. Файл сохраняется как передан, даже если это не DOCX, и скачивание DOCX вернёт те же байты.

Существование записи не проверяется. Документ создаётся и для entityId, которого нет среди записей этого типа: ответ 201, в том числе для контакта — в отличие от создания по шаблону. Документ, прикреплённый к несуществующему контакту, потом не читается и не удаляется: все методы отвечают 403 BITRIX_ACCESS_DENIED. Проверяйте запись заранее, например через GET /v1/contacts/:id.

PDF без pdfContent формируется позже. Если PDF-версия не передана, PDF формируется из DOCX после загрузки, и до этого скачивание PDF отвечает 409 DOCUMENT_NOT_READY.

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