## Создать шаблон документа CRM `POST /v1/crm-document-templates` Создаёт шаблон документа CRM из файла .docx, переданного строкой base64, и привязывает его к типам записей CRM. Поля передаются в корне JSON без обёртки. ## Поля запроса (body) | Поле | Тип | Обяз. | Описание | |------|-----|:-----:|---------| | `name` | string | да | Название шаблона | | `file` | string | да | Содержимое вашего файла `.docx` строкой base64, не больше 2 МиБ после декодирования. Как получить строку — в «Известных особенностях» | | `numeratorId` | number | да | ID нумератора, который присваивает номера документам. Положительное целое число. Список нумераторов через `/v1/...` не выставлен | | `region` | string | да | Регион шаблона, например `ru` | | `entityTypeId` | array | да | Непустой массив типов записей CRM, числа или строки: `2` — сделка, `3` — контакт, `4` — компания. Типы смарт-процессов — [`GET /v1/smart-processes`](/docs/entities/smart-processes) | | `users` | array | нет | Массив кодов доступа строками: `UA` — все сотрудники, `U` — сотрудник с этим ID из [`GET /v1/users`](/docs/entities/users). При вызове личным ключом без этого поля шаблон доступен только владельцу ключа: в ответе придёт `U` этого сотрудника | | `active` | string | нет | Активность шаблона: `Y` или `N`. Без поля — `Y` | | `withStamps` | string | нет | Печати и подписи в документах: `Y` или `N`. Без поля — `N` | | `sort` | number | нет | Индекс сортировки. Без поля — `500` | | `code` | string | нет | Символьный код шаблона | Поля `id`, `fileId`, `moduleId`, `download`, `downloadMachine`, `isDeleted`, `isDefault`, `createTime`, `updateTime`, `createdBy`, `updatedBy`, `providers` только для чтения. Запрос с любым из них отклоняется с `400 READONLY_FIELD`. Имя сравнивается без учёта регистра и подчёркиваний: `module_id` и `ModuleId` тоже отклоняются. ## Примеры В примерах `contract.docx` — ваш файл шаблона. Тело запроса собирается в файл `template.json`, затем отправляется. ### curl — личный ключ ```bash printf '{"name":"Договор поставки","numeratorId":1,"region":"ru","entityTypeId":[2],"users":["UA"],"file":"%s"}' \ "$(base64 < contract.docx | tr -d '\n')" > template.json curl -X POST "https://vibecode.bitrix24.tech/v1/crm-document-templates" \ -H "X-Api-Key: YOUR_API_KEY" \ -H "Content-Type: application/json" \ --data-binary @template.json ``` ### curl — OAuth-приложение ```bash printf '{"name":"Договор поставки","numeratorId":1,"region":"ru","entityTypeId":[2],"users":["UA"],"file":"%s"}' \ "$(base64 < contract.docx | tr -d '\n')" > template.json curl -X POST "https://vibecode.bitrix24.tech/v1/crm-document-templates" \ -H "X-Api-Key: YOUR_APP_KEY" \ -H "Authorization: Bearer USER_SESSION_TOKEN" \ -H "Content-Type: application/json" \ --data-binary @template.json ``` ### JavaScript — личный ключ ```javascript import { readFile } from 'node:fs/promises' const file = (await readFile('contract.docx')).toString('base64') const res = await fetch('https://vibecode.bitrix24.tech/v1/crm-document-templates', { method: 'POST', headers: { 'X-Api-Key': 'YOUR_API_KEY', 'Content-Type': 'application/json', }, body: JSON.stringify({ name: 'Договор поставки', numeratorId: 1, region: 'ru', entityTypeId: [2], users: ['UA'], file, }), }) const { success, data } = await res.json() console.log('ID шаблона:', data.id) ``` ### JavaScript — OAuth-приложение ```javascript import { readFile } from 'node:fs/promises' const file = (await readFile('contract.docx')).toString('base64') const res = await fetch('https://vibecode.bitrix24.tech/v1/crm-document-templates', { method: 'POST', headers: { 'X-Api-Key': 'YOUR_APP_KEY', 'Authorization': 'Bearer USER_SESSION_TOKEN', 'Content-Type': 'application/json', }, body: JSON.stringify({ name: 'Договор поставки', numeratorId: 1, region: 'ru', entityTypeId: [2], users: ['UA'], file, }), }) const { success, data } = await res.json() ``` ## Поля ответа | Поле | Тип | Описание | |------|-----|---------| | `success` | boolean | Всегда `true` при успехе | | `data` | object | Созданный шаблон | | `data.id` | string | ID шаблона, строкой | | `data.name` | string | Название шаблона | | `data.region` | string | Регион шаблона | | `data.code` | string \| null | Символьный код шаблона, `null` — код не задан | | `data.download` | string | Адрес скачивания файла шаблона в веб-интерфейсе Битрикс24. Для скачивания через API используйте `downloadMachine` | | `data.active` | string | Активность: `Y` или `N` | | `data.moduleId` | string | Модуль-владелец, всегда `crm` | | `data.numeratorId` | string | ID нумератора, строкой | | `data.withStamps` | string | Печати и подписи: `Y` или `N` | | `data.users` | object | Коды доступа объектом, код служит и ключом, и значением: `{"UA": "UA"}` | | `data.isDeleted` | string | Признак удаления: `N` у действующего шаблона | | `data.sort` | string | Индекс сортировки, строкой | | `data.createTime` | string | Дата создания в ISO 8601 со смещением часового пояса | | `data.updateTime` | string | Дата последнего изменения в ISO 8601 со смещением часового пояса | | `data.entityTypeId` | array | Типы записей CRM строками, в том виде, в каком их передали в запросе. При чтении шаблона сделка раскрывается по воронкам — см. [Что нужно знать перед работой](/docs/entities/crm-document-templates#что-нужно-знать-перед-работой) | | `data.downloadMachine` | string | Адрес скачивания `.docx` через API Вайбкод — [`GET /v1/crm-document-templates/:id/download`](/docs/entities/crm-document-templates/download) | ## Пример ответа HTTP `201`: ```json { "success": true, "data": { "id": "263", "name": "Договор поставки", "region": "ru", "code": null, "download": "https://example.bitrix24.ru/bitrix/services/main/ajax.php?action=crm.documentgenerator.template.download&SITE_ID=s1&id=263", "active": "Y", "moduleId": "crm", "numeratorId": "1", "withStamps": "N", "users": { "UA": "UA" }, "isDeleted": "N", "sort": "500", "createTime": "2026-10-08T13:20:29+03:00", "updateTime": "2026-10-08T13:20:29+03:00", "entityTypeId": ["2"], "downloadMachine": "https://vibecode.bitrix24.tech/v1/crm-document-templates/263/download" } } ``` ## Пример ответа при ошибке 400 — не передано обязательное поле: ```json { "success": false, "error": { "code": "MISSING_REQUIRED_FIELDS", "message": "Required field 'numeratorId' is missing." } } ``` ## Ошибки | HTTP | Код | Описание | |------|-----|---------| | 400 | `MISSING_REQUIRED_FIELDS` | Не передано одно из обязательных полей, его значение `null`, пустая строка или пустой массив. Пустое тело `{}` получает тот же код | | 400 | `INVALID_PARAMS` | `file` не является строкой base64. Плейсхолдер вместо содержимого файла отклоняется этим кодом до обращения к Битрикс24 | | 400 | `INVALID_PARAMS` | `users` не массив непустых строк, например передан объект `{"UA": "UA"}` в форме из ответа | | 400 | `INVALID_PARAMS` | `entityTypeId` не массив либо в нём есть значение, которое не является положительным числом или непустой строкой | | 400 | `INVALID_PARAMS` | `name` или `region` не строка, `numeratorId` не положительное целое число | | 400 | `INVALID_PARAMS` | Тело запроса не JSON-объект | | 400 | `READONLY_FIELD` | В теле передано поле только для чтения, например `moduleId` или `fileId` | | 413 | `PAYLOAD_TOO_LARGE` | Файл больше 2 МиБ после декодирования `file` либо JSON-тело больше 3 МиБ | | 429 | `LARGE_BODY_BACKEND_BUSY` | Тело больше 1 МиБ, а платформа уже обрабатывает предельный объём крупных тел. Повторите запрос через `Retry-After` секунд | | 422 | `BITRIX_WRITE_NOT_APPLIED` | Шаблон создан, но Битрикс24 сохранил не все переданные `entityTypeId` или `users`. ID созданного шаблона — в `error.details.createdTemplateId`. Проверьте шаблон через [`GET /v1/crm-document-templates/:id`](/docs/entities/crm-document-templates/get) до повтора: повторный запрос создаст ещё один шаблон | | 422 | `BITRIX_ERROR` | Битрикс24 отклонил создание. Текст причины — в `error.message` | | 403 | `WRITE_BLOCKED_READONLY_KEY` | Ключ работает в режиме только для чтения | | 403 | `SCOPE_DENIED` | Ключу не хватает скоупа `crm` | | 401 | `TOKEN_MISSING` | У ключа нет настроенных токенов | | 429 | `RATE_LIMITED` | Битрикс24 ограничил частоту запросов к порталу. Повторите после срока из заголовка `Retry-After` | Полный список общих ошибок API — [Ошибки](/docs/errors). ## Известные особенности **Как получить значение `file`.** Строка base64 собирается из вашего файла командой `base64 < contract.docx | tr -d '\n'`, на macOS — `base64 -i contract.docx | tr -d '\n'`. Перевод строки из вывода убирается обязательно: строка с переводами строк не проходит проверку base64. ## Смотрите также - [Список шаблонов документов CRM](/docs/entities/crm-document-templates/list) - [Получить шаблон документа CRM](/docs/entities/crm-document-templates/get) - [Обновить шаблон документа CRM](/docs/entities/crm-document-templates/update) - [Удалить шаблон документа CRM](/docs/entities/crm-document-templates/delete) - [Скачать шаблон](/docs/entities/crm-document-templates/download) - [Создать документ CRM](/docs/entities/documents/crm-create) - [Шаблоны документов](/docs/entities/doc-templates)