Создать новый документ crm.documentgenerator.document.add

Scope: crm

Кто может выполнять метод: пользователь с правом "изменения" документов генератора документов

Метод crm.documentgenerator.document.add создает документ по шаблону для CRM-объекта.

Параметры метода

Обязательные параметры отмечены *

Название
тип

Описание

templateId*
integer

Идентификатор шаблона документа

entityTypeId*
integer

Идентификатор типа CRM-объекта, для которого создается документ.

Типичные значения:

  • 1 — лид
  • 2 — сделка
  • 3 — контакт
  • 4 — компания
  • 5 — счет (старая версия)
  • 7 — коммерческое предложение
  • 31 — счет

Для смарт-процессов передается их entityTypeId, например 177

entityId*
integer

Идентификатор CRM-объекта, по данным которого создается документ

values
object

Объект со значениями полей документа.

Формат:

{
            "field_1": "value_1",
            "field_2": "value_2"
        }

где:

  • field_n — код поля документа
  • value_n — значение поля

Набор ключей зависит от конкретного шаблона и провайдера данных. Посмотреть доступные поля можно методом crm.documentgenerator.document.getfields

stampsEnabled
integer

Подставлять печать и подпись:

  • 1 — подставлять
  • 0 — не подставлять

По умолчанию 0

fields
object

Дополнительные описания полей документа для генерации.

Параметр fields используется для более точечной настройки полей. В большинстве сценариев достаточно параметра values.

В fields передается объект-описание поля (descriptor). Пример:

{
            "DocumentTitle": {
                "title": "Название документа",
                "value": "Демонстрационная реализация товара 1",
                "required": "Y",
                "default": "Демонстрационная реализация товара 1",
                "chain": [
                    {},
                    "getTitle"
                ],
                "VALUE": "Тест через fields"
            }
        }

Список ключей fields не фиксированный и зависит от шаблона.

Как получить доступные параметры:

Служебные поля SOURCE и DOCUMENT игнорируются.

Некоторые вычисляемые поля могут не переопределяться через fields

Особенность метода

pdfUrl и imageUrl могут отсутствовать сразу после создания, так как конвертация выполняется асинхронно. Для проверки результата используйте crm.documentgenerator.document.get

Примеры кода

Как использовать примеры в документации

Пример создания документа, где:

  • templateId — 39
  • entityTypeId — 2 (сделка)
  • entityId — 101
  • номер документа подставляется через values.DocumentNumber
  • для fields.DocumentTitle передается descriptor-объект поля
curl -X POST \
        -H "Content-Type: application/json" \
        -H "Accept: application/json" \
        -d '{"templateId":39,"entityTypeId":2,"entityId":101,"values":{"DocumentNumber":"2026-001"},"fields":{"DocumentTitle":{"title":"Название документа","value":"Демонстрационная реализация товара 1","required":"Y","default":"Демонстрационная реализация товара 1","chain":[{},"getTitle"],"VALUE":"Тест через fields"}},"stampsEnabled":1}' \
        https://**put_your_bitrix24_address**/rest/**put_your_user_id_here**/**put_your_webhook_here**/crm.documentgenerator.document.add
        
curl -X POST \
        -H "Content-Type: application/json" \
        -H "Accept: application/json" \
        -d '{"templateId":39,"entityTypeId":2,"entityId":101,"values":{"DocumentNumber":"2026-001"},"fields":{"DocumentTitle":{"title":"Название документа","value":"Демонстрационная реализация товара 1","required":"Y","default":"Демонстрационная реализация товара 1","chain":[{},"getTitle"],"VALUE":"Тест через fields"}},"stampsEnabled":1,"auth":"**put_access_token_here**"}' \
        https://**put_your_bitrix24_address**/rest/crm.documentgenerator.document.add
        
try
        {
        		const response = await $b24.callMethod(
        			'crm.documentgenerator.document.add',
        			{
        				templateId: 39,
        				entityTypeId: 2,
        				entityId: 101,
        				values: {
        					DocumentNumber: '2026-001',
        				},
        				fields: {
        					DocumentTitle: {
        						title: 'Название документа',
        						value: 'Демонстрационная реализация товара 1',
        						required: 'Y',
        						default: 'Демонстрационная реализация товара 1',
        						chain: [{}, 'getTitle'],
        						VALUE: 'Тест через fields',
        					},
        				},
        				stampsEnabled: 1,
        			}
        		);
        
        	const result = response.getData().result;
        	console.info(result);
        }
        catch (error)
        {
        	console.error('Error:', error);
        }
        
try {
            $response = $b24Service
                ->core
                ->call(
                    'crm.documentgenerator.document.add',
                    [
                        'templateId' => 39,
                        'entityTypeId' => 2,
                        'entityId' => 101,
                        'values' => [
                            'DocumentNumber' => '2026-001',
                        ],
                        'fields' => [
                            'DocumentTitle' => [
                                'title' => 'Название документа',
                                'value' => 'Демонстрационная реализация товара 1',
                                'required' => 'Y',
                                'default' => 'Демонстрационная реализация товара 1',
                                'chain' => [
                                    [],
                                    'getTitle',
                                ],
                                'VALUE' => 'Тест через fields',
                            ],
                        ],
                        'stampsEnabled' => 1,
                    ]
                );
        
            $result = $response
                ->getResponseData()
                ->getResult();
        
            echo '<pre>';
            print_r($result);
            echo '</pre>';
        
        } catch (Throwable $e) {
            error_log($e->getMessage());
            echo 'Error adding document: ' . $e->getMessage();
        }
        
BX24.callMethod(
            'crm.documentgenerator.document.add',
            {
                templateId: 39,
                entityTypeId: 2,
                entityId: 101,
                values: {
                    DocumentNumber: '2026-001',
                },
                fields: {
                    DocumentTitle: {
                        title: 'Название документа',
                        value: 'Демонстрационная реализация товара 1',
                        required: 'Y',
                        default: 'Демонстрационная реализация товара 1',
                        chain: [{}, 'getTitle'],
                        VALUE: 'Тест через fields',
                    }
                },
                stampsEnabled: 1,
            },
            (result) => {
                result.error()
                    ? console.error(result.error())
                    : console.info(result.data())
                ;
            },
        );
        
require_once('crest.php');
        
        $result = CRest::call(
            'crm.documentgenerator.document.add',
            [
                'templateId' => 39,
                'entityTypeId' => 2,
                'entityId' => 101,
                'values' => [
                    'DocumentNumber' => '2026-001',
                ],
                'fields' => [
                    'DocumentTitle' => [
                        'title' => 'Название документа',
                        'value' => 'Демонстрационная реализация товара 1',
                        'required' => 'Y',
                        'default' => 'Демонстрационная реализация товара 1',
                        'chain' => [
                            [],
                            'getTitle',
                        ],
                        'VALUE' => 'Тест через fields',
                    ],
                ],
                'stampsEnabled' => 1,
            ]
        );
        
        echo '<PRE>';
        print_r($result);
        echo '</PRE>';

Обработка ответа

HTTP-статус: 200

{
            "result": {
                "document": {
                    "changeStampsEnabled": false,
                    "changeStampsDisabledReason": "В шаблоне нет печатей и подписей",
                    "changeQrCodeEnabled": false,
                    "qrCodeEnabled": false,
                    "changeQrCodeDisabledReason": "В шаблоне нет QR-кода",
                    "products": {
                        "currencyId": "UAH",
                        "totalSum": "0.00",
                        "totalRows": 0
                    },
                    "downloadUrl": "https://bitrix.bitrix24.ru/bitrix/services/main/ajax.php?action=crm.documentgenerator.document.download&SITE_ID=s1&id=61",
                    "downloadUrlMachine": "https://bitrix.bitrix24.ru/rest/crm.documentgenerator.document.download.json?...",
                    "publicUrl": null,
                    "id": 61,
                    "title": "Демонстрационная реализация товара 2026-001",
                    "number": "2026-001",
                    "createTime": "2026-03-20T13:51:45+03:00",
                    "createdBy": 577,
                    "updateTime": "2026-03-20T13:51:45+03:00",
                    "updatedBy": null,
                    "stampsEnabled": true,
                    "isTransformationError": false,
                    "values": {
                        "productsTableVariant": "",
                        "_creationMethod": "rest",
                        "stampsEnabled": true,
                        "DocumentNumber": "2026-001"
                    },
                    "templateId": "39",
                    "pullTag": "TRANSFORMDOCUMENT61",
                    "imageUrl": "https://bitrix.bitrix24.ru/bitrix/services/main/ajax.php?action=crm.documentgenerator.document.getImage&SITE_ID=s1&id=61",
                    "pdfUrl": "https://bitrix.bitrix24.ru/bitrix/services/main/ajax.php?action=crm.documentgenerator.document.getPdf&SITE_ID=s1&id=61",
                    "emailDiskFile": 5605,
                    "entityId": "101",
                    "entityTypeId": "2"
                }
            },
            "time": {
                "start": 1774003904,
                "finish": 1774003905.448804,
                "duration": 1.4488039016723633,
                "processing": 1,
                "date_start": "2026-03-20T13:51:44+03:00",
                "date_finish": "2026-03-20T13:51:45+03:00",
                "operating_reset_at": 1774004504,
                "operating": 0.9240179061889648
            }
        }

Возвращаемые данные

Название
тип

Описание

result
object

Корневой элемент ответа. Возвращает объект result

time
time

Информация о времени выполнения запроса

Тип result

Название
тип

Описание

document
object

Данные созданного документа. Структура описана в типе document

Тип document

Название
тип

Описание

id
integer

Идентификатор документа

title
string

Название документа

number
string

Номер документа

createTime
datetime

Дата создания

updateTime
datetime

Дата обновления

createdBy
integer

Идентификатор пользователя, создавшего документ

updatedBy
integer | null

Идентификатор пользователя, обновившего документ

changeStampsEnabled
boolean

Можно ли изменить признак подстановки печати и подписи

changeStampsDisabledReason
string

Причина, почему нельзя изменить признак подстановки печати и подписи

changeQrCodeEnabled
boolean

Можно ли включить или выключить QR-код

qrCodeEnabled
boolean

Текущее состояние QR-кода

changeQrCodeDisabledReason
string

Причина, почему нельзя изменить QR-код

products
object

Сводная информация по товарам документа (currencyId, totalSum, totalRows)

stampsEnabled
boolean

Признак подстановки печати и подписи

downloadUrl
string

Ссылка на скачивание документа

downloadUrlMachine
string

Ссылка на скачивание документа для машинного доступа

publicUrl
string | null

Публичная ссылка на документ

isTransformationError
boolean

Признак ошибки конвертации документа

transformationErrorMessage
string

Текст ошибки конвертации, если isTransformationError = true

transformationErrorCode
string

Код ошибки конвертации, если isTransformationError = true

templateId
integer

Идентификатор шаблона

pullTag
string

Тег события трансформации документа

emailDiskFile
integer

Идентификатор файла в Диске для отправки по email

entityTypeId
integer

Идентификатор типа CRM-объекта

entityId
integer

Идентификатор CRM-объекта

values
object

Значения полей документа, переданные при создании

imageUrl
string

Ссылка на изображение документа, если уже создано

pdfUrl
string

Ссылка на PDF-файл документа, если уже создан

Обработка ошибок

HTTP-статус: 400

{
            "error": "0",
            "error_description": "No provider for entityTypeId"
        }

Название
тип

Описание

error
string

Строковый код ошибки. Может состоять из цифр, латинских букв и знака подчеркивания

error_description
error_description

Текстовое описание ошибки. Описание не предназначено для показа конечному пользователю в необработанном виде

Возможные коды ошибок

Код

Описание

Значение

0

No provider for entityTypeId

Не найден провайдер данных для переданного entityTypeId

0

Empty required parameter "value"

Не передан или передан пустой entityId

0

Cannot create document on deleted template

Нельзя создать документ по удаленному шаблону

0

Cannot create document

Ошибка при создании документа по шаблону

DOCGEN_ACCESS_ERROR

Access denied

Нет доступа к созданию документа

DOCGEN_LIMIT_ERROR

Maximum count of documents has been reached

Превышен лимит количества документов в тарифе

0

Error getting next number

Не удалось получить следующий номер документа из нумератора

100

Bitrix\DocumentGenerator\Template constructor must be is public

Низкоуровневая ошибка при вызове без корректного templateId

0

Module documentgenerator is not installed

Модуль documentgenerator недоступен

0

Шаблон не найден

Шаблон с указанным templateId не найден или недоступен

Статусы и коды системных ошибок

HTTP-статус: 20x, 40x, 50x

Описанные ниже ошибки могут возникнуть при вызове любого метода

Статус

Код
Текст ошибки

Описание

500

INTERNAL_SERVER_ERROR
Internal server error

Возникла внутренняя ошибка сервера, обратитесь к администратору сервера или в техническую поддержку Битрикс24

500

ERROR_UNEXPECTED_ANSWER
Server returned an unexpected response

Возникла внутренняя ошибка сервера, обратитесь к администратору сервера или в техническую поддержку Битрикс24

503

QUERY_LIMIT_EXCEEDED
Too many requests

Превышен лимит на интенсивность запросов

405

ERROR_BATCH_METHOD_NOT_ALLOWED
Method is not allowed for batch usage

Текущий метод не разрешен для вызова с помощью batch

400

ERROR_BATCH_LENGTH_EXCEEDED
Max batch length exceeded

Превышена максимальная длина параметров, переданных в метод batch

401

NO_AUTH_FOUND
Wrong authorization data

Неверный access-токен или код вебхука

400

INVALID_REQUEST
Https required

Для вызовов методов требуется использовать протокол HTTPS

503

OVERLOAD_LIMIT
REST API is blocked due to overload

REST API заблокирован из-за перегрузки. Это ручная индивидуальная блокировка, для снятия необходимо обращаться в техническую поддержку Битрикс24

403

ACCESS_DENIED
REST API is available only on commercial plans

REST API доступен только на коммерческих планах

403

INVALID_CREDENTIALS
Invalid request credentials

У пользователя, с чьим access-токеном или вебхуком был вызван метод, не хватает прав

404

ERROR_MANIFEST_IS_NOT_AVAILABLE
Manifest is not available

Манифест недоступен

403

insufficient_scope
The request requires higher privileges than provided by the webhook token

Запрос требует более высоких привилегий, чем предоставляет токен вебхука

401

expired_token
The access token provided has expired

Предоставленный access-токен доступа истек

403

user_access_error
The user does not have access to the application

Пользователь не имеет доступа к приложению. Это означает, что приложение установлено, но администратор портала разрешил доступ к этому приложению только конкретным пользователям

500

PORTAL_DELETED
Portal was deleted

Публичная часть сайта закрыта. Чтобы открыть публичную часть сайта на коробочной установке отключите опцию «Временное закрытие публичной части сайта». Путь к настройке: Рабочий стол > Настройки > Настройки продукта > Настройки модулей > Главный модуль > Временное закрытие публичной части сайта

Продолжите изучение

Предыдущая
Обзор методов
Следующая
Изменить документ