## Обновить CRM-документ `PATCH /v1/crm-documents/:id` Меняет значения полей шаблона или признак печатей у документа записи CRM и формирует файл документа заново. Поля передаются в корне JSON без обёртки fields. ## Параметры | Параметр | Тип | Обяз. | Описание | |----------|-----|:-----:|---------| | `id` (path) | number | да | Идентификатор документа, положительное целое число. Список документов записи: [`GET /v1/crm-documents`](/docs/entities/documents/crm-list) | ## Поля запроса (body) Передайте хотя бы одно из полей. | Поле | Тип | Обяз. | Описание | |------|-----|:-----:|---------| | `values` | object | нет | Значения полей шаблона. Ключи дополняют сохранённые: ключи, которых нет в запросе, остаются. Например, `DocumentNumber` задаёт номер документа | | `stampsEnabled` | boolean | нет | Включить или выключить печати и подписи. Если поле не передано, печати включаются. Чтобы оставить их выключенными, передайте `stampsEnabled: false` в каждом запросе | Другие поля, например `title` или `templateId`, запрос не принимает. Флаг печатей передаётся только в корне тела, не внутри `values`. ## Примеры ### curl — личный ключ ```bash curl -X PATCH "https://vibecode.bitrix24.tech/v1/crm-documents/1961" \ -H "X-Api-Key: YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "values": { "DocumentNumber": "VIBE-1" }, "stampsEnabled": false }' ``` ### curl — OAuth-приложение ```bash curl -X PATCH "https://vibecode.bitrix24.tech/v1/crm-documents/1961" \ -H "X-Api-Key: YOUR_APP_KEY" \ -H "Authorization: Bearer USER_SESSION_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "values": { "DocumentNumber": "VIBE-1" }, "stampsEnabled": false }' ``` ### JavaScript — личный ключ ```javascript const res = await fetch('https://vibecode.bitrix24.tech/v1/crm-documents/1961', { method: 'PATCH', headers: { 'X-Api-Key': 'YOUR_API_KEY', 'Content-Type': 'application/json', }, body: JSON.stringify({ values: { DocumentNumber: 'VIBE-1' }, stampsEnabled: false, }), }) const { success, data } = await res.json() console.log('Новый номер:', data.number) ``` ### JavaScript — OAuth-приложение ```javascript const res = await fetch('https://vibecode.bitrix24.tech/v1/crm-documents/1961', { method: 'PATCH', headers: { 'X-Api-Key': 'YOUR_APP_KEY', 'Authorization': 'Bearer USER_SESSION_TOKEN', 'Content-Type': 'application/json', }, body: JSON.stringify({ values: { DocumentNumber: 'VIBE-1' }, stampsEnabled: false, }), }) const { success, data } = await res.json() ``` ## Поля ответа Возвращается обновлённый документ. Полное описание полей документа — на странице [Получить CRM-документ](/docs/entities/documents/crm-get). | Поле | Тип | Описание | |------|-----|---------| | `success` | boolean | Всегда `true` при успехе | | `data.id` | string | Идентификатор документа | | `data.number` | string | Номер документа после обновления | | `data.values` | object | Значения полей шаблона после обновления вместе со служебными ключами | | `data.stampsEnabled` | boolean | Признак печатей, с которым сформирован документ | | `data.updateTime` | string | Время обновления в формате ISO 8601 | | `data.updatedBy` | number | ID сотрудника, обновившего документ. Список: [`GET /v1/users`](/docs/entities/users) | | `data.createTime` | string | В ответе этого метода — время, когда файл сформирован заново. Дату создания документа отдаёт [`GET /v1/crm-documents/:id`](/docs/entities/documents/crm-get) | | `data.createdBy` | null | В ответе этого метода приходит `null`. Создателя отдаёт [`GET /v1/crm-documents/:id`](/docs/entities/documents/crm-get) | | `data.downloadUrlMachine` | string | Адрес [`/v1/crm-documents/:id/download`](/docs/entities/documents/download) для скачивания нового DOCX. Нужен `X-Api-Key` со скоупом `crm` | ## Пример ответа Показаны основные поля. Полный список: [Получить CRM-документ](/docs/entities/documents/crm-get). ```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=1961", "publicUrl": null, "title": "Адреса А463//10/2026", "number": "VIBE-1", "id": "1961", "createTime": "2026-10-08T17:57:43+03:00", "createdBy": null, "updateTime": "2026-10-08T17:57:42+03:00", "updatedBy": 1317, "stampsEnabled": false, "values": { "productsTableVariant": "", "stampsEnabled": false, "_creationMethod": "rest", "DocumentNumber": "VIBE-1" }, "templateId": "87", "entityId": "8781", "entityTypeId": "2", "downloadUrlMachine": "https://vibecode.bitrix24.tech/v1/crm-documents/1961/download" } } ``` ## Пример ответа при ошибке 400 — в теле нет ни `values`, ни `stampsEnabled`: ```json { "success": false, "error": { "code": "MISSING_REQUIRED_FIELDS", "message": "values or stampsEnabled is required" } } ``` ## Ошибки | HTTP | Код | Описание | |------|-----|---------| | 400 | `INVALID_PARAMS` | `id` не положительное целое число. Сообщение: `id must be a positive integer` | | 400 | `MISSING_REQUIRED_FIELDS` | Тело `{}` или не JSON-объект, например массив. Сообщение: `values or stampsEnabled is required` | | 400 | `READONLY_FIELD` | В теле поле, кроме `values` и `stampsEnabled`, например `title` | | 400 | `INVALID_PARAMS` | `values` не объект, `values` содержит `stampsEnabled` или `stampsEnabled` не логическое значение | | 404 | `ENTITY_NOT_FOUND` | Документа с таким `id` нет или он удалён | | 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 — [Ошибки](/docs/errors). ## Известные особенности **PDF и изображение формируются снова.** После обновления DOCX, PDF и изображение формируются заново. Пока они не готовы, скачивание [PDF](/docs/entities/documents/pdf) отвечает `409 DOCUMENT_NOT_READY`. **Прежнее значение печатей не сохраняется.** Запрос только с `values` формирует файл с печатями, даже если документ создан или прошлым запросом обновлён с `stampsEnabled: false`. Признак в [`GET /v1/crm-documents/:id`](/docs/entities/documents/crm-get) для проверки не годится, подробнее — в «Известных особенностях» страницы [Получить CRM-документ](/docs/entities/documents/crm-get). ## Смотрите также - [Получить CRM-документ](/docs/entities/documents/crm-get) - [Создать CRM-документ](/docs/entities/documents/crm-create) - [Удалить CRM-документ](/docs/entities/documents/crm-delete) - [Документы по CRM-сущности](/docs/entities/documents/crm-list) - [Документы](/docs/entities/documents)