Martynov Labs Написать

Шаблоны и плейсхолдеры

Шаблон — обычный файл Word или Excel, в котором вместо данных стоят метки в двойных фигурных скобках: {{fio}}. AppCloud подставляет значения, склоняет ФИО, раскладывает даты и суммы и при необходимости собирает PDF.

Как это работает

  1. Сделайте документ в Word или Excel и поставьте плейсхолдеры туда, где должны быть данные.
  2. Загрузите шаблон через /uploadfile и сохраните его file_id.
  3. Для каждого документа вызывайте /generatefile с нужными значениями и форматом: docx, xlsx или pdf.
  4. Если документ будут подписывать, зафиксируйте его через /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, плейсхолдер просто исчезает.
Совет. Набирайте плейсхолдер целиком за один раз, а не исправляйте по буквам: так Word не разобьёт его на части с разным оформлением.

Склонение ФИО

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.

Склонения в XLSX нет. Плейсхолдер {{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 плейсхолдер остаётся в ячейке как есть: так легче заметить пропущенное поле.

Подготовка шаблона

  1. Откройте бланк в Excel или LibreOffice Calc.
  2. Выделите группу клеток для одного значения и задайте им границы со всех четырёх сторон. Толщина и стиль линии не важны.
  3. В первую (левую) клетку группы впишите плейсхолдер, например {{inn}}. Остальные клетки оставьте пустыми.
  4. Сохраните файл и загрузите его в 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.