# documentgenerator.document.add

URL: https://chugunov.pro/api-bitrix24/document-generator/document-generator-document-add/
Проверено на Битрикс24 REST API, обновлено 11.09.2026 (ревизия источника fb39d6c).
Источник: официальная документация Битрикс24 (bitrix-tools/b24-rest-docs, лицензия MIT, © Bitrix). Справочник независимый, официальной документацией не является.

Создать новый документ на основании шаблона
Scope: `documentgenerator`
Кто может выполнять метод: пользователь с правом на создание документов

## Описание

Метод `documentgenerator.document.add` создает новый документ на основании шаблона.

## Параметры

- `templateId` `integer` — обязательный. Идентификатор шаблона.
  Получить идентификатор шаблона можно после [создания шаблона](https://chugunov.pro/api-bitrix24/document-generator/templates/document-generator-template-add/) или методом [получения списка шаблонов](https://chugunov.pro/api-bitrix24/document-generator/templates/document-generator-template-list/)
- `providerClassName` `string` — необязательный. Класс провайдера данных.
  При вызове через REST всегда используется `Bitrix\DocumentGenerator\DataProvider\Rest`: переданное значение игнорируется, поэтому параметр можно не указывать
- `value` `string` — обязательный. Внешний идентификатор объекта, для которого формируется документ.
  Формат `value` задается интеграцией. Используйте единый формат в рамках вашего приложения, чтобы искать и фильтровать документы.
  Рекомендуемый формат: `<ТИП_ОБЪЕКТА>_<ID>`, где:
  - `<ТИП_ОБЪЕКТА>` — строковый код типа объекта в верхнем регистре
  - `<ID>` — числовой или строковый идентификатор объекта во внешней системе
  Примеры значений `value` для CRM-объектов:
  - лид — `LEAD_123`
  - контакт — `CONTACT_45`
  - компания — `COMPANY_78`
  - сделка — `DEAL_901`
  - коммерческое предложение — `QUOTE_55`
  - счет — `INVOICE_12`
  Примеры значений `value` для другие объектов:
  - заказ — `ORDER_1024`
  - договор поставки — `SUPPLY_CONTRACT_2026_015`
  - запись внешней системы — `ERP_DOC_A-7741`
- `values` `object` — необязательный. Значения полей документа вида `{"КодПоля":"Значение"}`
- `stampsEnabled` `integer` — необязательный. Режим печатей и подписей:
  - `1` — включить
  - `0` — выключить
  По умолчанию берется значение из шаблона
- `fields` `object` — необязательный. Описание того, как интерпретировать и форматировать значения из `values` [(подробное описание)](#fields).
  Ключ объекта `fields` должен совпадать с кодом поля из шаблона.
  Если передаете только обычный текст, параметр можно не указывать.
  Пример структуры `fields`:
  ```json
  {
      "CurrentDate": {
          "TYPE": "DATE",
          "FORMAT": {
              "format": "d.m.Y"
          },
          "TITLE": "Дата договора"
      }
  }
  ```

### Параметр fields

- `TYPE` `string` — необязательный. Тип поля.
  Типы, для которых можно указать форматирование:
  - `DATE` — дата или дата-время
  - `NAME` — ФИО
- `FORMAT` `object` — необязательный. Параметры формата для типа поля.
  `FORMAT` не фиксирован одним значением, его нужно выбирать под ваш шаблон и требования к выводу.
  Для `DATE` значение `format` задается в формате модификаторов даты генератора документов. Пример: `{"format":"d.m.Y"}`
  Для `NAME`:
  - `format` задает шаблон вывода частей имени, например `#NAME# #LAST_NAME#`
  - `case` задает падеж
  **Пользовательская документация**
  - [Что такое модификаторы в шаблонах документов](https://helpdesk.bitrix24.ru/open/18175702/)
- `PROVIDER` `string` — необязательный. Класс провайдера
- `TITLE` `string` — необязательный. Название поля

## Ответ

HTTP-статус: 200

```json
{
    "result": {
        "document": {
            "downloadUrl": "/bitrix/services/main/ajax.php?action=documentgenerator.api.document.getfile&SITE_ID=s1&id=51&ts=1773844068",
            "publicUrl": null,
            "title": "SUPPLY_CONTRACT Template 1773843147554 ДГ-2026-001",
            "number": "ДГ-2026-001",
            "id": 51,
            "createTime": "2026-03-18T17:27:48+03:00",
            "createdBy": 503,
            "updateTime": "2026-03-18T17:27:48+03:00",
            "updatedBy": null,
            "stampsEnabled": true,
            "isTransformationError": false,
            "value": "SUPPLY_CONTRACT_2026_015",
            "values": {
                "productsTableVariant": "",
                "_creationMethod": "rest",
                "stampsEnabled": true,
                "DocumentNumber": "ДГ-2026-001",
                "CurrentDate": "2026-03-18T00:00:00+03:00",
                "ClientName": "ООО Ромашка",
                "ClientPhone": "+7 999 123-45-67",
                "Total": "125000",
                "Comment": "Оплата в течение 5 рабочих дней после подписания",
                "UserName": "Иван Петров"
            },
            "templateId": "53",
            "provider": "Bitrix\\DocumentGenerator\\DataProvider\\Rest",
            "pullTag": "TRANSFORMDOCUMENT51",
            "emailDiskFile": 5569,
            "downloadUrlMachine": "https://**put_your_bitrix24_address**/rest/documentgenerator.api.document.getfile.json?auth=a0bfba690000071b00000844000001f7f0f1075f240da39bb5ea0e42c08c5fa182f3ed&token=documentgenerator%7CYWN0aW9uPWRvY3VtZW50Z2VuZXJhdG9yLmFwaS5kb2N1bWVudC5nZXRmaWxlJlNJVEVfSUQ9czEmaWQ9NTEmdHM9MTc3Mzg0NDA2OCZfPXZMVUFDSGMwQkY1QVpRbGQzTlNhV2ZIemNzMW5IZ1lM%7CImRvY3VtZW50Z2VuZXJhdG9yLmFwaS5kb2N1bWVudC5nZXRmaWxlfGRvY3VtZW50Z2VuZXJhdG9yfFlXTjBhVzl1UFdSdlkzVnRaVzUwWjJWdVpYSmhkRzl5TG1Gd2FTNWtiMk4xYldWdWRDNW5aWFJtYVd4bEpsTkpWRVZmU1VROWN6RW1hV1E5TlRFbWRITTlNVGMzTXpnME5EQTJPQ1pmUFhaTVZVRkRTR013UWtZMVFWcFJiR1F6VGxOaFYyWkllbU56TVc1SVoxbE18YTBiZmJhNjkwMDAwMDcxYjAwMDAwODQ0MDAwMDAxZjdmMGYxMDc1ZjI0MGRhMzliYjVlYTBlNDJjMDhjNWZhMTgyZjNlZCI%3D.6lsKyiThwQT0n4UyMQfXdyS%2BnBVTG08%2FpGguggYNGLE%3D"
        }
    },
    "time": {
        "start": 1773844068,
        "finish": 1773844068.572038,
        "duration": 0.572037935256958,
        "processing": 0,
        "date_start": "2026-03-18T17:27:48+03:00",
        "date_finish": "2026-03-18T17:27:48+03:00",
        "operating_reset_at": 1773844668,
        "operating": 0.9536302089691162
    }
}
```

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

- `result` `object`. Корневой элемент ответа [(подробное описание)](#result)
- `time` `time`. Информация о времени выполнения запроса

## Ошибки

HTTP-статус: 400

```json
{
    "error": "0",
    "error_description": "Cannot create document on deleted template"
}
```

- `400` — `100`. Bitrix\DocumentGenerator\Template constructor must be is public
- `400` — `0`. Empty required parameter "value"
- `400` — `0`. Cannot create document on deleted template
- `400` — `0`. Шаблон не найден
- `400` — `0`. Cannot create document
- `400` — `0`. You do not have permissions to view documents
- `400` — `0`. Maximum count of documents has been reached
- `403` — `DOCGEN_ACCESS_ERROR`. Access denied

## Примеры запроса

### cURL (Webhook)

```bash
curl -X POST \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{"templateId":53,"value":"SUPPLY_CONTRACT_2026_015","values":{"DocumentNumber":"ДГ-2026-001","CurrentDate":"2026-03-18T00:00:00+03:00","ClientName":"ООО Ромашка","ClientPhone":"+7 999 123-45-67","Total":"125000","Comment":"Оплата в течение 5 рабочих дней после подписания","UserName":"Иван Петров"},"fields":{"CurrentDate":{"TYPE":"DATE","FORMAT":{"format":"d.m.Y"},"TITLE":"Дата договора"}},"stampsEnabled":1}' \
  https://**put_your_bitrix24_address**/rest/**put_your_user_id_here**/**put_your_webhook_here**/documentgenerator.document.add
```

### cURL (OAuth)

```bash
curl -X POST \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{"templateId":53,"value":"SUPPLY_CONTRACT_2026_015","values":{"DocumentNumber":"ДГ-2026-001","CurrentDate":"2026-03-18T00:00:00+03:00","ClientName":"ООО Ромашка","ClientPhone":"+7 999 123-45-67","Total":"125000","Comment":"Оплата в течение 5 рабочих дней после подписания","UserName":"Иван Петров"},"fields":{"CurrentDate":{"TYPE":"DATE","FORMAT":{"format":"d.m.Y"},"TITLE":"Дата договора"}},"stampsEnabled":1,"auth":"**put_access_token_here**"}' \
  https://**put_your_bitrix24_address**/rest/documentgenerator.document.add
```

### JS (TS)

```ts
// This snippet is an ES module: top-level await requires type="module" or a bundler.
// $b24 is an already-initialized SDK instance (see the SDK "Get started" guide).
import { Text } from '@bitrix24/b24jssdk'
import type { B24Frame, ISODate } from '@bitrix24/b24jssdk'

declare const $b24: B24Frame

// Shape of the payload returned in result (match the "response handling" section of the page)
type DocumentAddResult = {
  document: {
    id: number
    title: string
    number: string
    templateId: string
    provider: string
    value: string
    values: Record<string, unknown>
    stampsEnabled: boolean
    downloadUrl: string
    downloadUrlMachine: string
    publicUrl: string | null
    isTransformationError: boolean
    pullTag: string
    emailDiskFile: number
    createTime: ISODate
    updateTime: ISODate
    createdBy: number
    updatedBy: number | null
  }
}

try {
  const response = await $b24.actions.v2.call.make<DocumentAddResult>({
    method: 'documentgenerator.document.add',
    params: {
      templateId: 53,
      value: 'SUPPLY_CONTRACT_2026_015',
      values: {
        DocumentNumber: 'DG-2026-001',
        CurrentDate: '2026-03-18T00:00:00+03:00',
        ClientName: 'Romashka LLC',
        ClientPhone: '+7 999 123-45-67',
        Total: '125000',
        Comment: 'Payment within 5 business days after signing',
        UserName: 'Ivan Petrov',
      },
      fields: {
        CurrentDate: {
          TYPE: 'DATE',
          FORMAT: {
            format: 'd.m.Y',
          },
          TITLE: 'Contract date',
        },
      },
      stampsEnabled: 1,
    },
    requestId: Text.getUuidRfc4122()
  })

  // The payload is available only on a successful response
  if (!response.isSuccess) {
    console.error(response.getErrorMessages().join('; '))
  } else {
    const result = response.getData()!.result
    console.info('Created document id:', result.document.id, 'title:', result.document.title)
  }
} catch (error) {
  // Thrown on transport or SDK failures (AjaxError, SdkError, etc.)
  console.error(error)
}
```

### JS (UMD)

```html
<!-- Load the SDK (UMD build); it is exposed as the global B24Js -->
<script src="https://unpkg.com/@bitrix24/b24jssdk@1/dist/umd/index.min.js"></script>
<script>
  async function addDocument() {
    try {
      // Initialize the SDK inside a Bitrix24 frame
      const $b24 = await B24Js.initializeB24Frame()

      const response = await $b24.actions.v2.call.make({
        method: 'documentgenerator.document.add',
        params: {
          templateId: 53,
          value: 'SUPPLY_CONTRACT_2026_015',
          values: {
            DocumentNumber: 'DG-2026-001',
            CurrentDate: '2026-03-18T00:00:00+03:00',
            ClientName: 'Romashka LLC',
            ClientPhone: '+7 999 123-45-67',
            Total: '125000',
            Comment: 'Payment within 5 business days after signing',
            UserName: 'Ivan Petrov',
          },
          fields: {
            CurrentDate: {
              TYPE: 'DATE',
              FORMAT: {
                format: 'd.m.Y',
              },
              TITLE: 'Contract date',
            },
          },
          stampsEnabled: 1,
        },
        requestId: B24Js.Text.getUuidRfc4122()
      })

      // The payload is available only on a successful response
      if (!response.isSuccess) {
        console.error(response.getErrorMessages().join('; '))
        return
      }

      const result = response.getData().result
      console.info('Created document id:', result.document.id, 'title:', result.document.title)
    } catch (error) {
      // Thrown on transport or SDK failures (AjaxError, SdkError, etc.)
      console.error(error)
    }
  }

  document.addEventListener('DOMContentLoaded', addDocument)
</script>
```

### Python

```python
from b24pysdk.errors import BitrixAPIError, BitrixSDKException

try:
    bitrix_response = client.documentgenerator.document.add(
        template_id=53,
        value="SUPPLY_CONTRACT_2026_015",
        values={
            "DocumentNumber": "ДГ-2026-001",
            "CurrentDate": "2026-03-18T00:00:00+03:00",
            "ClientName": "ООО Ромашка",
            "ClientPhone": "+7 999 123-45-67",
            "Total": "125000",
            "Comment": "Оплата в течение 5 рабочих дней после подписания",
            "UserName": "Иван Петров",
        },
        fields={
            "CurrentDate": {
                "TYPE": "DATE",
                "FORMAT": {
                    "format": "d.m.Y",
                },
                "TITLE": "Дата договора",
            },
        },
        stamps_enabled=1,
    ).response
    result = bitrix_response.result
    print(result)
except BitrixAPIError as error:
    print(
        "Ошибка Bitrix API",
        f"error: {error.error}",
        f"error_description: {error.error_description}",
        sep="\n",
    )
except BitrixSDKException as error:
    print(f"Ошибка Bitrix SDK: {error.message}")
except Exception as error:
    print(f"Непредвиденная ошибка: {error}")
```

### PHP

```php
try {
    $response = $b24Service->core->call(
        'documentgenerator.document.add',
        [
            'templateId' => 53,
            'value' => 'SUPPLY_CONTRACT_2026_015',
            'values' => [
                'DocumentNumber' => 'ДГ-2026-001',
                'CurrentDate' => '2026-03-18T00:00:00+03:00',
                'ClientName' => 'ООО Ромашка',
                'ClientPhone' => '+7 999 123-45-67',
                'Total' => '125000',
                'Comment' => 'Оплата в течение 5 рабочих дней после подписания',
                'UserName' => 'Иван Петров',
            ],
            'fields' => [
                'CurrentDate' => [
                    'TYPE' => 'DATE',
                    'FORMAT' => [
                        'format' => 'd.m.Y',
                    ],
                    'TITLE' => 'Дата договора',
                ]
            ],
            'stampsEnabled' => 1,
        ]
    );

    $result = $response->getResponseData()->getResult();
    print_r($result);
} catch (Throwable $e) {
    echo $e->getMessage();
}
```

### BX24.js

```js
BX24.callMethod(
    'documentgenerator.document.add',
    {
        templateId: 53,
        value: 'SUPPLY_CONTRACT_2026_015',
        values: {
            DocumentNumber: 'ДГ-2026-001',
            CurrentDate: '2026-03-18T00:00:00+03:00',
            ClientName: 'ООО Ромашка',
            ClientPhone: '+7 999 123-45-67',
            Total: '125000',
            Comment: 'Оплата в течение 5 рабочих дней после подписания',
            UserName: 'Иван Петров'
        },
        fields: {
            CurrentDate: {
                TYPE: 'DATE',
                FORMAT: {
                    format: 'd.m.Y'
                },
                TITLE: 'Дата договора'
            }
        },
        stampsEnabled: 1
    },
    function(result)
    {
        if (result.error())
        {
            console.error(result.error());
        }
        else
        {
            console.log(result.data());
        }
    }
);
```

### PHP CRest

```php
require_once('crest.php');

$result = CRest::call(
    'documentgenerator.document.add',
    [
        'templateId' => 53,
        'value' => 'SUPPLY_CONTRACT_2026_015',
        'values' => [
            'DocumentNumber' => 'ДГ-2026-001',
            'CurrentDate' => '2026-03-18T00:00:00+03:00',
            'ClientName' => 'ООО Ромашка',
            'ClientPhone' => '+7 999 123-45-67',
            'Total' => '125000',
            'Comment' => 'Оплата в течение 5 рабочих дней после подписания',
            'UserName' => 'Иван Петров',
        ],
        'fields' => [
            'CurrentDate' => [
                'TYPE' => 'DATE',
                'FORMAT' => [
                    'format' => 'd.m.Y',
                ],
                'TITLE' => 'Дата договора',
            ]
        ],
        'stampsEnabled' => 1,
    ]
);

print_r($result);
```

### Go

```go
// client и ctx уже созданы — см. раздел «SDK для Go»
res, err := client.Core().Call(ctx, "documentgenerator.document.add", b24.Params{
	"templateId": 53,
	"value":      "SUPPLY_CONTRACT_2026_015",
	"values": b24.Params{
		"DocumentNumber": "ДГ-2026-001",
		"CurrentDate":    "2026-03-18T00:00:00+03:00",
		"ClientName":     "ООО Ромашка",
		"ClientPhone":    "+7 999 123-45-67",
		"Total":          "125000",
		"Comment":        "Оплата в течение 5 рабочих дней после подписания",
		"UserName":       "Иван Петров",
	},
	"fields": b24.Params{
		"CurrentDate": b24.Params{
			"TYPE": "DATE",
			"FORMAT": b24.Params{
				"format": "d.m.Y",
			},
			"TITLE": "Дата договора",
		},
	},
	"stampsEnabled": 1,
})
if err != nil {
	return fmt.Errorf("documentgenerator.document.add: %w", err)
}

// Метод заворачивает ответ в объект с ключом "document".
raw, ok := b24.Unwrap(res.Result, "document")
if !ok {
	return fmt.Errorf("в ответе нет ключа document")
}

var item struct {
	DownloadUrl string `json:"downloadUrl"`
	Title       string `json:"title"`
	Number      string `json:"number"`
	ID          b24.ID `json:"id"`
	CreateTime  string `json:"createTime"`
	CreatedBy   int    `json:"createdBy"`
}
if err := json.Unmarshal(raw, &item); err != nil {
	return fmt.Errorf("разбор ответа: %w", err)
}
fmt.Println(item.DownloadUrl, item.Title)
```

Оригинал в официальной документации: https://apidocs.bitrix24.ru/api-reference/document-generator/document-generator-document-add.html