> ## Documentation Index
> Fetch the complete documentation index at: https://docs.yume.cloud/llms.txt
> Use this file to discover all available pages before exploring further.
# Плейсхолдеры шаблонов
> Каталог плейсхолдеров для подстановки данных клиента, точки проката, инвентаря, товара, услуги, штрафа и доставки в шаблон документа.
Полный перечень плейсхолдеров по группам — в [глоссарии плейсхолдеров](/ru/logic/documents/placeholders-glossary).
## Логика
Когда документ генерируется из шаблона, система собирает один общий словарь «плейсхолдер → значение» и подставляет его в HTML-содержимое. Плейсхолдер — это текст в двойных фигурных скобках, который менеджер компании вставляет в шаблон при его оформлении.
**Одиночные плейсхолдеры** (клиент, точка проката, общие данные заявки/менеджера/сумм) заменяются один раз во всём тексте документа.
**Табличные (построчные) плейсхолдеры** (инвентарь, товар, группа инвентаря, услуга, штраф, доставка) устроены иначе: система ищет в шаблоне строку таблицы с плейсхолдером нужного домена и размножает её — по одной копии на каждый объект, подставляя в каждую копию данные конкретной записи.
Если данные для плейсхолдера отсутствуют, подставляется заглушка — строка из двенадцати подчёркиваний, играющая роль «пустой линии для заполнения от руки» (с отдельными исключениями, отмеченными в глоссарии).
### Денежные суммы прописью
Любая денежная сумма доступна в двух вариантах: числом с символом валюты и «прописью» — словами на русском. Оба варианта берут валюту из одной и той же настройки компании, поэтому сумма прописью печатается в валюте компании, а не всегда в тенге.
* Валюта распознаётся и по коду (тенге, доллар, рубль, евро, сум, сом, дирхам, риал), и по символу валюты, и по распространённым сокращениям, которые компании реально вписывают в эту настройку («KZ», «сом», «сум», «Dhs» и т.п.). Незаполненная настройка означает тенге.
* Для тенге сумма печатается в казахском написании — «теңге».
* Для валют, у которых нет словесной формы (например, дирхам или киргизский сом), прописью выводится целая часть суммы плюс символ валюты, а копейки — цифрами. Раньше такая валюта прерывала формирование документа ошибкой.
* Пустая (незаполненная) сумма читается как ноль — например, у инвентаря без закупочной цены. Раньше это тоже приводило к ошибке формирования документа.
### Клиент и точка проката
Плейсхолдеры клиента строятся по объекту клиента заявки и делятся на базовые контактные данные и данные документа физического/юридического лица (заполняются только если у клиента есть соответствующие привязанные реквизиты).
Словарь плейсхолдеров клиента умеет строиться с префиксом к именам плейсхолдеров — используется, когда в заявке есть дополнительное настраиваемое поле типа «клиент» (например, «поручитель»): для указанного там клиента строится второй набор тех же плейсхолдеров, но с именем этого поля перед каждым плейсхолдером, без разделителя.
Плейсхолдеры точки проката — это отдельный небольшой словарь (ID, название, адрес) точки проката заявки. Механизм с префиксом предусмотрен, но на практике точка проката всегда подставляется без префикса — повторно подставить данные второй, дополнительной точки проката так, как это делается для клиента, сейчас нельзя.
### Построчные таблицы: инвентарь, товар и группа инвентаря
Арендуемый инвентарь и проданные товары строятся почти одинаково: по одной строке на позицию, с идентификацией, сроками аренды и денежными показателями (цена, скидка, штраф, закупочная и балансовая стоимость — в цифрах и прописью). У инвентаря дополнительно есть блок данных автомобиля (заполняется только для инвентаря типа «автомобиль» и только для непустых полей); у товаров этого блока нет.
Формула цены со скидкой за день (только у инвентаря): цена со скидкой по позиции делится на общее число дней аренды всей заявки, но не менее чем на один день — при нулевой длительности аренды плейсхолдер выводит цену как за один день, а не завершает формирование документа ошибкой.
Компания может добавлять собственные настраиваемые поля инвентаря и группы инвентаря — они автоматически становятся дополнительными плейсхолдерами построчных таблиц. Для инвентаря к ним всегда добавляются три встроенных поля (VIN, цвет, общий пробег), даже если компания их не настраивала. Для таблицы проданных товаров такая поддержка не реализована.
Отдельная построчная таблица группирует арендуемый инвентарь не по единицам, а по модели/группе (например, «все велосипеды модели X» одной строкой). Она строится только если в шаблоне действительно есть строка с плейсхолдером группы. Цена за единицу в этой таблице — среднее арифметическое цены со скидкой по единицам группы, округлённое до целого.
### Штраф и доставка
Штрафы заявки подставляются построчно: номер строки, ID, причина, сумма (в цифрах и прописью), дата создания.
В таблицу штрафов попадают только штрафы, добавленные вручную сотрудником. Штрафы, начисленные системой автоматически (просрочка, повреждение и т.п.), в эту построчную таблицу не включаются — они видны только через общие суммы штрафа по заявке и по позиции.
Доставки/вывозы инвентаря заявки подставляются построчно: идентификация, даты и статус (забор, доставка, выдача, отмена), контакты и места, цена доставки (в цифрах и прописью). Тип доставки принимает значение «Доставка» или «Вывоз»; для прочих технически возможных значений выводится заглушка.
Итоговая сумма «цена доставки» на уровне всей заявки считается не по этой построчной таблице, а отдельно — как сумма стоимости типизированных дополнительных услуг заявки. Это разные механизмы: построчная таблица отражает логистические записи, а итоговая сумма — сумму выставленных клиенту услуг.
### Услуга
Дополнительные услуги заявки подставляются построчно: номер, ID, название, доп. информация, исполнитель, цена и цена со скидкой (в цифрах и прописью), цена по тарифу, длительность тарифа, адрес доставки (из произвольных дополнительных данных услуги, если указан).
Плейсхолдер исполнителя услуги выводит сотрудника, назначенного на услугу, а если исполнитель не назначен — обычную заглушку. Ранее этот плейсхолдер завершал формирование документа ошибкой.
### Общий порядок сборки
1. Строится плоский словарь одиночных плейсхолдеров (клиент, точка проката, данные заявки/менеджера) и подставляется в текст шаблона за один проход.
2. Для каждого построчного домена (инвентарь, товар, группа, услуга, штраф, доставка) строится словарь функций «номер строки + объект → строка»; система находит в шаблоне соответствующие строки таблиц и подставляет данные, размножая строку.
3. Компания может расширять словари клиента, заявки, точки проката, инвентаря и группы инвентаря собственными настраиваемыми полями — они автоматически добавляются при сборке документа.
## Особенности поведения
* Для проданных товаров название и адрес точки проката инвентаря вычисляются без защитной проверки — если у позиции точка проката не задана, подстановка завершится ошибкой вместо вывода заглушки.
* Плейсхолдер состояния инвентаря (и товара) при отсутствии состояния выводит дефис, а не стандартную заглушку из подчёркиваний, используемую во всех остальных полях этих таблиц.
* У части денежных плейсхолдеров таблиц инвентаря и товара нет варианта «прописью»: цена по тарифу, долг и оплаченная сумма — только числом с валютой.
* Плейсхолдер органа выдачи документа физического лица подставляется только если он заполнен вручную в карточке паспорта клиента — при остальных заполненных паспортных данных, но пустом поле органа выдачи, плейсхолдер всё равно станет заглушкой.
* Опечатка в названии построчного плейсхолдера теперь безопасна во всех шести таблицах (инвентарь, товар, группа, услуга, штраф, доставка): неизвестный плейсхолдер остаётся в документе текстом «как есть», формирование документа не прерывается, а сам факт записывается в журнал для разбора.
* Механизм префикса словаря плейсхолдеров точки проката реализован, но при генерации документа заявки вызывается всегда без префикса — второй набор плейсхолдеров для дополнительной точки проката так, как это сделано для клиента, сейчас получить нельзя.