Шаблоны и плейсхолдеры
Шаблон — обычный файл Word или Excel, в котором вместо данных стоят метки в двойных фигурных скобках: {{fio}}. AppCloud подставляет значения, склоняет ФИО, раскладывает даты и суммы и при необходимости собирает PDF.
Как это работает
- Сделайте документ в Word или Excel и поставьте плейсхолдеры туда, где должны быть данные.
- Загрузите шаблон через
/uploadfileи сохраните егоfile_id. - Для каждого документа вызывайте
/generatefileс нужными значениями и форматом:docx,xlsxилиpdf. - Если документ будут подписывать, зафиксируйте его через
/topdf.
{
"id": "ab0a356a…",
"format": "pdf",
"values": {
"fio": "Иванов Иван Иванович",
"date": "15.03.2026",
"amount": "150000.50"
}
}
Имена плейсхолдеров — буквы, цифры и подчёркивание, без пробелов: {{fio}}, {{contract_no}}, {{inn2}}. Регистр в имени важен: {{Fio}} и {{fio}} — разные ключи.
Синтаксис плейсхолдеров
| Плейсхолдер | Что подставится | Пример |
|---|---|---|
{{key}} | Значение как есть | {{fio}} → Иванов Иван Иванович |
{{key['dat']}} | Значение в нужном падеже (только DOCX) | {{fio['dat']}} → Иванову Ивану Ивановичу |
{{key.suffix}} | Часть даты или суммы | {{date.month_name}} → марта |
{{key[0]}} | Элемент списка или символ строки по номеру с нуля | {{items[0]}} → первый пункт списка |
Кавычки в падеже можно ставить любые или не ставить вовсе: {{fio['gen']}}, {{fio["gen"]}} и {{fio[gen]}} работают одинаково.
Шаблоны DOCX
- Плейсхолдеры работают в тексте, в таблицах (в том числе вложенных), в надписях и в колонтитулах.
- Подставленный текст получает оформление плейсхолдера: шрифт, размер, жирность. Если Word разбил плейсхолдер на куски с разным оформлением, берётся оформление первого куска, соседний текст не меняется.
- Разрывы страниц и строк, табуляции, поля и картинки в шаблоне остаются на месте.
- Перевод строки в значении (
\n) становится переносом строки в документе, табуляция (\t) — табуляцией. - Если ключа нет в
valuesили его значениеnull, плейсхолдер просто исчезает.
Склонение ФИО
AppCloud склоняет фамилии, имена и отчества, а также должности и другие слова. Каждое слово склоняется отдельно, слова через пробел и через дефис — тоже. Род определяется по самому слову, регистр сохраняется: ИВАНОВ станет ИВАНОВУ.
{{fio['dat']}} → Иванову Ивану Ивановичу
{{fio_f['dat']}} → Петровой Анне Сергеевне (fio_f = "Петрова Анна Сергеевна")
{{position['dat']}} → Министру образования (position = "Министр образования")
Зависимое слово в родительном падеже не склоняется: «Министр образования» в дательном — «Министру образования», а не «Министру образованию».
Падежи
| Код | Падеж | Вопрос | Иванов Иван Иванович |
|---|---|---|---|
nom | Именительный | кто? | Иванов Иван Иванович |
gen | Родительный | кого? | Иванова Ивана Ивановича |
dat | Дательный | кому? | Иванову Ивану Ивановичу |
acc | Винительный | кого? | Иванова Ивана Ивановича |
ins | Творительный | кем? | Ивановым Иваном Ивановичем |
pre | Предложный | о ком? | Иванове Иване Ивановиче |
В склонённых словах буква «ё» пишется как «е».
Исключения
Некоторые фамилии не склоняются или склоняются не по правилам: Куликовских, Каджая, Кравец. Для них есть общий список исключений, его AppCloud подтягивает с этого сайта раз в 15 минут, без перезапуска: inflection_exceptions.json.
{
"куликовских": {"declinable": false},
"фамилия": {"forms": {"dat": "Форма в дательном", "gen": "Форма в родительном"}},
"другая": {"forms": {"masc": {"dat": "…"}, "femn": {"dat": "…"}}}
}
Ключ — фамилия строчными буквами. "declinable": false — не склонять. forms — готовые формы для падежей, можно отдельно для мужчин (masc) и женщин (femn). Если фамилия в ваших документах склоняется неверно, напишите нам: добавим её в список.
Даты
Дату можно передать как 15.03.1990, 15/03/1990, 15-03-1990 или 1990-03-15 (в том числе со временем: 1990-03-15T00:00:00). Год из двух цифр считается годом XXI века: 1.3.26 — это 01.03.2026.
| Суффикс | Что подставится | Для 15.03.1990 |
|---|---|---|
.dd, .d, .day | День, две цифры | 15 |
.mm, .m, .month | Месяц, две цифры | 03 |
.yyyy, .y, .year | Год, четыре цифры | 1990 |
.yy | Год, две цифры | 90 |
.month_name | Месяц словом, для даты | марта |
.month_name_nom | Месяц словом, именительный падеж | Март |
«{{date.dd}}» {{date.month_name}} {{date.yyyy}} г. → «15» марта 1990 г.
Суффиксы можно писать в любом регистре: {{date.DD}} тоже сработает.
Суммы
Сумма делится на рубли и копейки. Разделитель — точка или запятая, пробелы в числе не мешают. Если копеек нет, подставится 00.
| Суффикс | Что подставится | Для 150000.50 |
|---|---|---|
.rub, .r | Рубли | 150000 |
.kop, .k | Копейки, две цифры | 50 |
{{amount.rub}} руб. {{amount.kop}} коп. → 150000 руб. 50 коп.
Списки и части значения
Если значение — список, {{items[0]}}, {{items[1]}} берут его элементы по номеру с нуля. Если значение — строка, тот же синтаксис берёт символ: {{inn[0]}} — первая цифра ИНН. Номер за пределами списка даёт пустую строку.
Суффикс-число делит значение по точкам: для "12.34.56" плейсхолдер {{code.0}} даст 12, {{code.2}} — 56. В бланках XLSX с клеточками суффиксы-числа работают иначе, см. многострочные поля.
Шаблоны XLSX
Шаблоны принимаются в форматах .xlsx, .xlsm и .xls. Старый .xls автоматически переводится в XLSX с сохранением оформления. Формат результата — xlsx, xls или pdf.
{{fio['dat']}} в таблице подставит значение без изменений. Если нужна форма в падеже, передайте её отдельным ключом.Бланки с клеточками
Так устроены налоговые и банковские бланки: каждая буква или цифра в своей клетке. В шаблоне такая группа клеток обведена границами со всех четырёх сторон, а плейсхолдер стоит в первой клетке. AppCloud раскладывает значение по одному символу в клетку. Если плейсхолдер встречается на нескольких листах, все места заполняются одним значением.
Типы плейсхолдеров
| Тип | В шаблоне | Значение | Как заполнится |
|---|---|---|---|
| Простой | {{inn}} | "7707083893" | По цифре в клетку |
| Дата | {{birthdate.dd}} {{birthdate.mm}} {{birthdate.yyyy}} | "15.03.1990" | День, месяц и год по своим группам клеток |
| Сумма | {{amount.rub}} {{amount.kop}} | "150000.50" | Рубли и копейки по своим группам |
| Многострочный | {{org.1}} {{org.2}} {{org.3}} | "ОБЩЕСТВО С ОГРАНИЧЕННОЙ…" | Текст переносится на следующую строку бланка, когда клетки кончаются |
Длину каждой строки многострочного поля AppCloud считает сам по числу клеток. Если текст короткий, остальные строки остаются пустыми. Если текст не помещается во все строки, он обрезается.
Текст в ячейке
Плейсхолдер можно поставить и внутри обычного текста ячейки. Тогда он просто заменяется, как в DOCX, и работают те же суффиксы дат и сумм:
«{{birthdate.dd}}» {{birthdate.month_name}} {{birthdate.yyyy}} г. → «01» марта 2026 г.
Если ключа нет в values, в XLSX плейсхолдер остаётся в ячейке как есть: так легче заметить пропущенное поле.
Подготовка шаблона
- Откройте бланк в Excel или LibreOffice Calc.
- Выделите группу клеток для одного значения и задайте им границы со всех четырёх сторон. Толщина и стиль линии не важны.
- В первую (левую) клетку группы впишите плейсхолдер, например
{{inn}}. Остальные клетки оставьте пустыми. - Сохраните файл и загрузите его в AppCloud.
При заполнении сохраняются границы (стиль и цвет), шрифты, выравнивание, перенос по словам, объединённые ячейки, ширина столбцов и высота строк. Заполненные клетки выравниваются по центру.
Преобразование в PDF
PDF собирает собственный конвертер AppCloud, без Word и LibreOffice. Одинаковый документ всегда даёт побайтно одинаковый PDF. Получить PDF можно двумя способами:
/generatefileс"format": "pdf"— PDF собирается заново при каждом открытии;/topdf— PDF собирается один раз и больше не меняется. Выбирайте его для документов на подпись и в архив.
Из DOCX
- Текст: цвета, жирный и курсив (в том числе заданные стилем), списки, ручные переносы строк.
- Страницы: разрывы страниц, в том числе «с новой страницы», разделы со своим размером, ориентацией и полями.
- Колонтитулы на каждой странице, особый колонтитул первой страницы, поля с номером страницы и числом страниц.
- Таблицы: ширины столбцов и поля ячеек из документа, границы каждой ячейки, объединённые ячейки, заливка, вертикальное выравнивание, повтор строк-заголовков на новой странице.
- Картинки в тексте.
Шрифты. Шрифт ищется так же, как в Word: у текста, потом у стиля абзаца, у стиля «Обычный» и в настройках документа. Если нужного начертания на сервере нет, берётся метрически совместимая замена: Times New Roman → Liberation Serif, Arial → Liberation Sans. Строки переносятся там же, где в Word. Шрифты без настоящей кириллицы пропускаются, а если подходящего шрифта нет совсем, используется Arial.
Из XLSX
Каждый видимый лист — страница A4, длинный лист продолжается на следующих страницах. Ширина подгоняется под лист. Переносятся ширины столбцов, высоты строк, объединённые ячейки, заливка, границы, шрифты, выравнивание, перенос слов, а длинный текст заходит в пустые соседние ячейки, как в Excel. Так печатаются, например, справки по КНД 1151158.
Не печатаются картинки, диаграммы и повёрнутый текст, а также скрытые листы, строки и столбцы.
Запросы, ответы и коды ошибок — в руководстве по API.