Руководство пользователя
AIVIO помогает быстро создавать документы по готовому шаблону и данным из Excel. Вместо ручного копирования текста вы загружаете файлы, запускаете обработку и получаете готовый комплект документов для скачивания.
На этой странице документация разделена на два отдельных сценария: генерация документов и конвертация КА в GGE. У каждого сценария свои правила подготовки файлов, поэтому ниже они описаны отдельно и без смешения.
Готовый документ становится основой для целой серии файлов.
Каждая строка таблицы передает сервису данные для отдельного документа.
После обработки вы скачиваете отдельный файл или архив с полным комплектом документов.
Быстрый старт
Сначала определите, что именно вам нужно сделать: сгенерировать документы по шаблону или выполнить конвертацию КА в GGE. Это два разных сценария с разными правилами подготовки Excel-файла.
Не используйте один и тот же мысленный сценарий для всего сервиса. Генерация работает с шаблоном документа и своим Excel-файлом, а конвертация КА в GGE использует другой Excel и другое правило структуры.
Возможности сервиса
Сервис рассчитан на повседневную работу с однотипными документами. Он избавляет от ручной подстановки данных и помогает быстрее получать итоговые файлы в нужном формате.
Сервис берет один подготовленный шаблон и автоматически подставляет в него значения из таблицы, сохраняя структуру и оформление документа.
Таблица Excel используется как источник данных. Каждая строка описывает отдельный комплект информации для генерации.
После обработки вы получаете готовые документы по всем строкам Excel. При большом объеме результат может быть собран в архив для удобной загрузки.
Отдельный режим для Excel-файлов конъюнктурного анализа. Сервис проверяет структуру файла, формирует результат в формате GGE и отдает его в ZIP-архиве.
Итог появляется прямо в интерфейсе: вы можете скачать отдельный файл или архив и сразу передать документы дальше по рабочему процессу.
Генерация документов
Этот блок относится только к генерации документов по шаблону. Если вам нужна конвертация КА в GGE, используйте отдельный раздел ниже: там другой Excel-файл и другие правила подготовки.
Используйте чистовую версию документа, которая уже содержит нужный текст, таблицы, подписи и оформление. Чем ближе шаблон к финальному виду, тем меньше ручных правок понадобится после генерации.
Соберите все значения в одной таблице. Первая строка содержит названия полей, а каждая следующая строка должна описывать отдельный документ или отдельный набор данных.
Выберите шаблон и Excel-файл в форме загрузки. Перед запуском еще раз проверьте названия файлов, чтобы случайно не использовать устаревшую версию шаблона или таблицы.
После нажатия кнопки сервис сначала проверит шаблон и Excel: сравнит плейсхолдеры, заголовки и покажет экран проверки, если найдет ошибки или предупреждения.
Если сервис показал только предупреждения, вы сможете посмотреть их и нажать «Продолжить несмотря на предупреждения». Если есть ошибки, сначала исправьте файлы и загрузите их заново.
После подтверждения или если предупреждений нет, задача перейдет в обработку. В зависимости от выбранного режима вы получите один итоговый документ или ZIP-архив с файлами для скачивания.
Если результат выглядит не так, как ожидалось, причина чаще всего находится в шаблоне или Excel-файле. Перед повторным запуском проверьте именно исходные данные.
Генерация документов
Этот раздел относится только к генерации документов. Шаблон — это основа будущего файла, в который сервис будет подставлять данные из Excel. Для конвертации КА в GGE шаблон документа не требуется.
Если шаблон уже настроен и в нем есть специальные места для автоматической подстановки данных, не удаляйте их и не меняйте их написание без необходимости.
Плейсхолдеры можно использовать и на латинице, и на кириллице: например, {{name}}, {{contract_number}}, {{ФИО}}, {{Город}}. В Excel в первой строке указываются те же названия, но без фигурных скобок.
Генерация документов
Морфология работает только в генерации документов. Она нужна, когда одно и то же значение из Excel должно автоматически подставляться в разных формах: с инициалами, в нужном падеже, прописью или в специальном формате для даты и числа.
В Excel достаточно одной базовой колонки, например ФИО или Дата. В шаблоне вы можете использовать не только базовый плейсхолдер, но и его производные формы, например {{ФИО.кому}} или {{Дата.прописью}}.
Названия плейсхолдеров могут быть как на латинице, так и на кириллице. Например, одинаково допустимы {{name}}, {{client_name}}, {{ФИО}} и {{Организация}}.
Для морфологии не нужно заводить отдельные колонки под каждую форму. Если в Excel есть колонка ФИО, этого достаточно, чтобы в шаблоне использовать и {{ФИО}}, и {{ФИО.кого}}, и {{ФИО.инициалы}}.
| Тип значения | Что хранить в Excel | Примеры плейсхолдеров в шаблоне |
|---|---|---|
| ФИО | ФИО → Иванов Иван Иванович |
{{ФИО}}, {{ФИО.кому}}, {{ФИО.кого}}, {{ФИО.с_кем}}, {{ФИО.о_ком}}, {{ФИО.инициалы}}, {{ФИО.инициалы_перед}}, {{ФИО.инициалы.кому}}, {{ФИО.инициалы_перед.кому}} |
| Дата | Дата → 19.03.2026 |
{{Дата}}, {{Дата.прописью}}, {{Дата.в_родительном}}, {{Дата.в_дательном}}, {{Дата.в_творительном}}, {{Дата.в_предложном}} |
| Число | Сумма → 123 |
{{Сумма}}, {{Сумма.прописью}}, {{Сумма.цифрами_и_прописью}} |
| Организация или обычный текст | Организация → ООО «Ромашка» |
{{Организация}}, {{Организация.кому}}, {{Организация.кого}}, {{Организация.с_кем}}, {{Организация.о_ком}} |
Сначала создайте и проверьте базовый плейсхолдер, например {{ФИО}} или {{Дата}}. После этого добавляйте производные формы: {{ФИО.кому}}, {{ФИО.инициалы}}, {{Дата.прописью}} и другие.
Генерация документов
Этот Excel-файл нужен именно для генерации документов по шаблону. Сервис читает таблицу с первой строки: в первой строке должны быть названия плейсхолдеров, а начиная со второй строки идут данные для подстановки в документы.
| Клиент | Номер договора | Дата | Сумма |
|---|---|---|---|
| ООО Альфа | 15-2026 | 05.04.2026 | 125 000 |
| ООО Бета | 16-2026 | 06.04.2026 | 98 500 |
Перед загрузкой проверьте два пункта: в первой строке действительно указаны названия плейсхолдеров, а каждая следующая строка содержит данные для отдельного документа. Если это так, таблица для генерации, скорее всего, подготовлена правильно.
Если вам нужна конвертация КА в GGE, не ориентируйтесь на этот пример. Для конвертации используется отдельный Excel-файл с другой структурой, и он описан в разделе «Конвертация КА в GGE» ниже.
Генерация документов
После успешной генерации сервис формирует один итоговый результат для скачивания. Его тип зависит от того, включена ли опция «Объединить документы в один файл».
Если включена опция объединения, сервис собирает один итоговый документ .docx. Если опция выключена, сервис формирует отдельные документы и упаковывает их в ZIP-архив.
После завершения обработки ссылка на скачивание появляется на странице статуса и на странице результата. Готовый результат также остается доступным в списке ваших документов.
Подождите немного дольше, особенно если таблица большая. Если итог не появился, проверьте страницу статуса, затем шаблон, Excel и раздел с частыми ошибками. После завершения результат можно скачать позже из списка документов.
Откройте хотя бы 1-2 готовых документа и убедитесь, что даты, суммы, фамилии и переносы строк выглядят именно так, как вы ожидаете получить в финальном пакете.
Отдельный сценарий
Этот раздел не относится к генерации документов по шаблону. Здесь описан отдельный сценарий, в котором сервис берет Excel-файл конъюнктурного анализа и преобразует его в формат GGE. Для этого сценария действует собственное правило структуры файла.
Сервис ориентируется на стандартный файл КА с блоком заголовков от 6-й строки. Обычно это двухстрочный заголовок на 6-й и 7-й строках. Если файл сдвинут вверх или вниз либо в нем нарушены обязательные колонки, конвертация не пройдет.
Это штатная часть сценария. Сервис показывает предупреждения, первые строки таблицы и найденные ошибки еще до запуска конвертации, чтобы вы могли исправить файл вовремя.
API и интеграции
Если вы хотите запускать обработку документов не через обычную форму сайта, а из CRM, внутреннего портала или другого сервиса, можно использовать API. Для этого нужен отдельный API-ключ, который создаётся в профиле пользователя.
Токен API-ключа показывается только один раз в момент создания. Передавайте ключ в заголовке Authorization: Api-Key ВАШ_API_КЛЮЧ и не храните его в открытом коде, GitHub, публичных репозиториях или frontend-коде. Если ключ был раскрыт, перевыпустите его и отзовите старый.
Запуски через API расходуют квоту API-вызовы, а не квоту Документы. Это относится и к генерации, и к конвертации через маршруты /api/documents/....
API-ключ передаётся в каждом запросе через заголовок Authorization.
Authorization: Api-Key ВАШ_API_КЛЮЧИспользуйте этот же заголовок для запуска задачи, опроса статуса и скачивания готового архива.
POST /api/documents/generate/ — запуск генерации.GET /api/documents/generate/<archive_id>/status/ — статус генерации.GET /api/documents/generate/<archive_id>/download/ — скачивание архива генерации.POST /api/documents/convert/ — запуск конвертации.GET /api/documents/convert/<conversion_id>/status/ — статус конвертации.GET /api/documents/convert/<conversion_id>/download/ — скачивание архива конвертации.GET /api/documents/keys/ — список ваших ключей.Если просто открыть её в браузере, архив может не скачаться, потому что браузер не передаёт API-ключ в заголовке Authorization. Для скачивания используйте Python, curl, Postman или другой API-клиент.
POST /api/documents/convert/.status_url.status_url с тем же заголовком авторизации.status == "ok", в ответе появится download_url.download_url ведёт на /api/documents/convert/<conversion_id>/download/.GET-запросом с заголовком Authorization.POST /api/documents/generate/.status_url.status_url с тем же API-ключом.status == "ok", в ответе появится download_url.download_url ведёт на /api/documents/generate/<archive_id>/download/.GET-запросом с заголовком Authorization.import os
import time
from urllib.parse import urljoin
import requests
BASE_URL = "https://aivio.ru"
API_KEY = os.environ["AIVIO_API_KEY"]
headers = {
"Authorization": f"Api-Key {API_KEY}",
}
def make_url(path_or_url: str) -> str:
return urljoin(BASE_URL, path_or_url)
with open("source.xlsx", "rb") as source_file:
start = requests.post(
make_url("/api/documents/convert/"),
headers=headers,
files={"file": source_file},
timeout=60,
)
start.raise_for_status()
status_url = make_url(start.json()["status_url"])
while True:
status_response = requests.get(status_url, headers=headers, timeout=30)
status_response.raise_for_status()
status = status_response.json()
if status["status"] == "ok":
download_url = make_url(status["download_url"])
archive_response = requests.get(
download_url,
headers=headers,
timeout=120,
stream=True,
allow_redirects=False,
)
archive_response.raise_for_status()
with open("converted_archive.zip", "wb") as archive_file:
for chunk in archive_response.iter_content(chunk_size=1024 * 1024):
if chunk:
archive_file.write(chunk)
print("Архив сохранён: converted_archive.zip")
break
if status["status"] == "error":
print("Ошибка:", status.get("message", "Неизвестная ошибка"))
break
time.sleep(2)Пример запускает конвертацию, опрашивает status_url и скачивает ZIP-архив отдельным авторизованным запросом.
AIVIO_API_KEY, а не хранится в коде.urljoin корректно работает и с относительными, и с абсолютными ссылками из API.allow_redirects=False помогает увидеть неожиданный редирект вместо скачивания файла.import os
import time
from urllib.parse import urljoin
import requests
BASE_URL = "https://aivio.ru"
API_KEY = os.environ["AIVIO_API_KEY"]
headers = {
"Authorization": f"Api-Key {API_KEY}",
}
def make_url(path_or_url: str) -> str:
return urljoin(BASE_URL, path_or_url)
with open("template.docx", "rb") as template_file, open("data.xlsx", "rb") as data_file:
start = requests.post(
make_url("/api/documents/generate/"),
headers=headers,
files={
"template_file": template_file,
"data_file": data_file,
},
timeout=60,
)
start.raise_for_status()
status_url = make_url(start.json()["status_url"])
while True:
status_response = requests.get(status_url, headers=headers, timeout=30)
status_response.raise_for_status()
status = status_response.json()
if status["status"] == "ok":
download_url = make_url(status["download_url"])
archive_response = requests.get(
download_url,
headers=headers,
timeout=120,
stream=True,
allow_redirects=False,
)
archive_response.raise_for_status()
with open("generated_archive.zip", "wb") as archive_file:
for chunk in archive_response.iter_content(chunk_size=1024 * 1024):
if chunk:
archive_file.write(chunk)
print("Архив сохранён: generated_archive.zip")
break
if status["status"] == "error":
print("Ошибка:", status.get("message", "Неизвестная ошибка"))
break
time.sleep(2)Пример запускает генерацию документов, ждёт готового статуса и скачивает архив через API-ссылку с тем же ключом.
template_file — шаблон DOCX для генерации.data_file — Excel-файл с данными.download_url ведёт на /api/documents/generate/<archive_id>/download/.curl -L \
-H "Authorization: Api-Key ВАШ_API_КЛЮЧ" \
-o result.zip \
"https://aivio.ru/api/documents/convert/4/download/"4 нужно заменить на реальный conversion_id.Authorization приходит 401 или 403, это нормально.200 и Content-Disposition: attachment, архив скачивается правильно.curl -L \
-H "Authorization: Api-Key ВАШ_API_КЛЮЧ" \
-o result.zip \
"https://aivio.ru/api/documents/generate/12/download/"12 нужно заменить на реальный archive_id.ok./api/documents/convert/<conversion_id>/download/.Типичные ошибки API
Ниже приведены самые типичные HTTP-статусы для интеграций. Они помогут быстрее настроить обработку ошибок на стороне CRM, бота или внутреннего сервиса.
| Код | Описание |
|---|---|
400 — неверный запрос |
Причина: файл не прошёл предварительную проверку, отсутствуют обязательные поля, нарушен формат загрузки или есть предупреждения без подтверждения продолжения. Решение: проверьте шаблон, Excel-файл и обязательные параметры запроса. Если API вернул списки errors или warnings, исправьте данные и повторите запрос. Если возвращены только предупреждения, отправьте запрос повторно с подтверждением force_warnings=true.
|
401 — ошибка аутентификации |
Причина: API-ключ отсутствует, передан с ошибкой, отозван или пользователь, связанный с ключом, недоступен. Решение: проверьте заголовок авторизации и убедитесь, что используете действующий API-ключ. При необходимости создайте новый ключ в личном кабинете. |
403 — доступ запрещён |
Причина: файл принадлежит другому пользователю или другому API-ключу, либо у пользователя исчерпан лимит API-вызовов по тарифу. Решение: проверьте, что скачиваете результат, созданный этим же пользователем/API-ключом. Если проблема в лимите, проверьте доступную квоту в аккаунте. |
404 — объект не найден |
Причина: указан неверный ID, файл ещё не создан, задача завершилась ошибкой или объект недоступен текущему пользователю. Решение: проверьте archive_id или conversion_id, дождитесь статуса ok и только потом скачивайте архив.
|
500 — ошибка сервера |
Причина: при запуске генерации или обработке запроса на стороне сервиса произошёл внутренний сбой. Решение: повторите запрос позже. Если проблема сохраняется, передайте в поддержку текст ошибки, пример запроса и request_id, если он был возвращён.
|
503 — сервис временно недоступен |
Причина: генерация документов временно отключена администратором или сервис находится в режиме ограничения доступа. Решение: подождите и повторите запрос позже. Если доступ не восстанавливается, уточните статус сервиса у поддержки. |
Это ожидаемо для защищённой API-ссылки. Браузер не передаёт заголовок Authorization, поэтому сервис может вернуть 401 или 403. Используйте Python, curl, Postman или другой API-клиент.
Если URL выглядит как https://aivio.ruhttps://aivio.ru/..., не склеивайте BASE_URL с download_url вручную. Используйте urllib.parse.urljoin, как в примере выше.
{
"archive_id": 12,
"status": "processing",
"request_id": "req-ab12cd34",
"task_id": "celery-task-id",
"status_url": "/api/documents/generate/12/status/"
}{
"archive_id": 12,
"status": "ok",
"download_url": "/api/documents/generate/12/download/"
}{
"detail": "Файлы не прошли предварительную проверку.",
"errors": [],
"warnings": ["Лишняя колонка extra"],
"can_force": true
}{
"detail": "Неверный API ключ."
}{
"detail": "Архив не найден."
}Сначала проверьте интеграцию на тестовом шаблоне и маленьком Excel-файле из 1-2 строк. Так проще убедиться, что внешний сервис правильно формирует запросы и обрабатывает ответы API.
Частые ошибки
Большинство проблем можно решить без помощи разработчика. Ниже собраны ошибки отдельно для генерации и для конвертации, чтобы было проще быстро найти свой сценарий.
Проверьте, что файл не поврежден, полностью сохранен и открывается на вашем компьютере. Для Excel поддерживаются .xlsx и .xls, а шаблон для генерации должен быть в формате .docx.
Скорее всего, в шаблоне не хватает нужных мест для подстановки данных, случайно удалены рабочие элементы или используется старая версия документа. Возьмите проверенный шаблон и протестируйте его на небольшой таблице.
Проверьте названия столбцов в первой строке, пустые ячейки, формат дат и отсутствие объединенных ячеек. Даже одна некорректная строка в Excel для генерации может повлиять на итоговый документ.
Для конвертации сервис ожидает стандартный блок заголовков, начинающийся с 6-й строки. Обычно заголовки находятся на 6-й и 7-й строках. Если этот блок сдвинут, обязательные колонки не будут распознаны.
Убедитесь, что оба файла загружены полностью. После отправки сервис может показать страницу проверки: если там есть ошибки, их нужно исправить; если есть только предупреждения, можно проверить их и продолжить запуск.
Проверьте, что вы загрузили Excel именно в раздел конвертации. Если сервис показывает экран проверки, посмотрите ошибки по структуре файла, обязательным колонкам и значениям статуса: в этой колонке допустимы только 1 или 2.
Чаще всего это означает, что сервису не удалось найти нужные данные в таблице или связать их с шаблоном. Проверьте соответствие шаблона и Excel, затем выполните тест на 1-2 строках.
Проверьте интернет-соединение, попробуйте скачать файл повторно и убедитесь, что браузер не блокирует загрузку. Если скачанный файл не открывается, сначала проверьте исходные файлы, а затем повторите запуск.
Не запускайте одну и ту же задачу много раз подряд без проверки файлов. Гораздо быстрее открыть шаблон и Excel, найти неточность и повторить запуск уже на исправленной версии.
FAQ
Если вам нужен быстрый ответ без длинной инструкции, начните с этого раздела. Здесь собраны вопросы, которые чаще всего возникают у пользователей при первой работе с сервисом.
Для генерации документов нет: обычно один Excel-файл содержит сразу много строк, и каждая строка соответствует отдельному документу. Для конвертации КА используется другой, отдельный Excel-сценарий.
Да, но для первой проверки лучше использовать небольшой тестовый набор. Так легче убедиться, что шаблон и таблица подготовлены правильно.
Да, сервис принимает .xls и .xlsx. Для стабильной работы лучше заранее пересохранить таблицу в .xlsx.
Нет. Шаблон документа нужен для генерации. Для конвертации КА в GGE используется только корректно подготовленный Excel-файл.
Сервис ожидает блок заголовков, начинающийся с 6-й строки. Обычно заголовки занимают 6-ю и 7-ю строки, а данные идут ниже. Если найден только один уровень заголовков на 6-й строке, сервис покажет предупреждение.
Обычно причина в формате данных в Excel. Проверьте, одинаково ли записаны даты и числа во всей таблице.
Это штатный шаг. Сервис показывает ошибки и предупреждения до запуска обработки. Ошибки нужно исправить, а при предупреждениях можно проверить их и при необходимости продолжить.
Да. Если шаблон уже проверен и дает правильный результат, лучше сохранить его как рабочий образец и использовать повторно.
Если опция включена, сервис собирает один итоговый документ. Если выключена, он формирует отдельные документы и упаковывает их в ZIP-архив.
Да, это даже желательно. Оставьте в Excel 1-2 строки, выполните тестовую генерацию и только потом запускайте полный пакет.
Не обязательно. Готовый результат сохраняется в сервисе и после завершения его можно скачать повторно со страницы результата или из списка документов. Для первого запуска просто удобнее дождаться завершения в текущей вкладке.
Возьмите шаблон, Excel-файл, скриншот ошибки и короткое описание шага, на котором возникла проблема. Это значительно ускорит разбор ситуации.
Полезные советы
Эти рекомендации особенно полезны, если вы регулярно запускаете генерацию документов и хотите тратить меньше времени на перепроверку исходных файлов.
Первые запуски лучше делать на нескольких строках Excel. Так вы быстрее поймете, все ли работает правильно, и не потратите время на повторную сборку большого пакета документов.
Если шаблон уже был успешно использован, сохраните его как рабочую версию. Это снижает риск случайно загрузить старый или неполный документ.
Когда в одной колонке все значения оформлены одинаково, сервису проще корректно собрать итоговый документ. Особенно это важно для дат, номеров и сумм.
Фамилии, адреса, названия компаний и большие суммы могут вести себя иначе, чем короткие примеры. Лучше заметить это в тесте, чем после полной генерации.
Ясные названия помогают не перепутать шаблон, Excel и итоговый архив. Особенно удобно, если в названии есть дата или версия.
Не откладывайте проверку до конца дня. После скачивания откройте несколько документов сразу, пока исходные файлы и контекст задачи еще под рукой.
Помощь
Если вы уже проверили шаблон, Excel и рекомендации выше, но задача все равно не выполняется корректно, лучше сразу обратиться в поддержку с подготовленной информацией.
Обращайтесь, если загрузка проходит, но результат не формируется; если ошибка повторяется даже после исправления файлов; или если итоговый документ системно отличается от ожидаемого результата.
Чем точнее вы опишете ситуацию, тем быстрее специалисты смогут воспроизвести проблему и подсказать решение. В большинстве случаев достаточно короткого описания и исходных файлов, с которыми возникла сложность.