API: передайте данные и скачайте готовый документ — Фабрика документов

Публичный API «Фабрики документов» создаёт DOCX и XLSX из данных внешней системы. Интеграция передаёт JSON, приложение подставляет его в загруженный шаблон. Затем интеграция проверяет статус и скачивает готовый файл.

Этот способ подходит для данных из 1С, ERP, сайта или собственного сервиса. Все примеры ниже используют условные значения. Адрес https://<адресAPIприложения> замените адресом API вашей установки.

Какие данные нужно передать

Способ запуска	Источник данных
Из карточки CRM, робота или действия БП	Приложение получает данные выбранной карточки и её товарные строки из Битрикс24
Через публичный API	Внешняя система передаёт весь объект `payload`, который нужен шаблону

Публичный API не загружает сделку или свойства товара по одному ID в запросе. Если шаблон использует deal.title, products и custom.contract_number, передайте эти объекты и значения в payload. Поле товара property109 в таком запросе обозначает ключ ваших данных; приложение не обращается к каталогу, чтобы заполнить его автоматически.

custom внутри полного payload можно использовать независимо от нового поля дополнительных значений в роботе БП. Для API это обычный объект входных данных. О загрузке данных из CRM читайте в разделе «Откуда берутся данные», о запуске из БП в разделе «Роботы и бизнес-процессы».

Что подготовить до первого запроса

Загрузите и проверьте шаблон в приложении. Откройте его карточку и запишите значение «Код». API использует код шаблона, например invoice_xlsx, а не его ID и не имя загруженного файла.
Подготовьте данные под маркеры шаблона. Для Word используйте инструкцию DOCX, для Excel инструкцию XLSX.
Получите API-ключ и адрес API у ответственного за интеграцию. Пункт управления ключами скрыт из основного меню приложения. Если у вас ещё нет ключа, сначала согласуйте подключение с администратором или поддержкой.
Для создания документа ключу нужно право generations:create, для чтения статуса generations:read, для скачивания файла files:download.
Передавайте ключ в заголовке Authorization: Bearer <API_ключ> во всех запросах ниже. Храните его в настройках внешней системы, без публикации в шаблоне или общедоступном коде.

Ключ привязан к установке приложения на портале. Код шаблона, генерация и файл должны относиться к этой установке. Ключи не ограничиваются одним шаблоном автоматически; учтите это при выборе того, кому вы их выдаёте.

Шаг 1. Подготовьте JSON для шаблона

Пример для таблицы с названием, количеством и артикулом:

{
  "template_code": "invoice_xlsx",
  "payload": {
    "deal": {
      "title": "Поставка оборудования"
    },
    "custom": {
      "contract_number": "00015",
      "note": "Поставка: \"основной склад\"\nДоставка до 18:00"
    },
    "products": [
      {
        "name": "Насос",
        "qty": 2,
        "properties": {
          "property109": "00109"
        }
      },
      {
        "name": "Фильтр",
        "qty": 1,
        "properties": {
          "property109": "00042"
        }
      }
    ]
  },
  "output": {
    "pdf": false
  }
}

Сохраните запрос в файл request.json в UTF-8. Замените invoice_xlsx реальным кодом своего шаблона. Для DOCX структура запроса такая же, меняется код шаблона и при необходимости состав данных.

В шаблоне можно использовать {{ deal.title }}, {{ custom.contract_number }} и {{ custom.note }}. Внутри повторяемой строки товаров используются {{ item.name }}, {{ item.qty }} и {{ item.properties.property109 }}. Как оформить сам повторяемый блок, показано в инструкциях DOCX и XLSX.

Ведущие нули сохраняются, если передать артикул строкой, например "00109". Число 109 не содержит ведущих нулей. Если шаблон выводит цены, суммы или реквизиты, добавьте нужные значения в payload: пример выше их не содержит.

Шаг 2. Создайте генерацию

Отправьте запрос:

POST https://<адресAPIприложения>/public-api/v1/generate
Authorization: Bearer <API_ключ>
Content-Type: application/json

Тело запроса берётся из request.json. Пример команды для интегратора:

curl --request POST \
  "https://<адресAPIприложения>/public-api/v1/generate" \
  --header "Authorization: Bearer <API_ключ>" \
  --header "Content-Type: application/json" \
  --data-binary "@request.json"

Пример ответа:

{
  "generation_id": "<ID_генерации>",
  "status": "queued"
}

Сохраните generation_id. Ответ о создании генерации ещё не означает, что файл готов.

Чтобы дополнительно получить PDF, передайте "output": {"pdf": true}. Исходный результат остаётся DOCX или XLSX по типу шаблона; PDF создаётся дополнительно при доступной конвертации.

Шаг 3. Дождитесь результата

Проверяйте состояние по полученному ID:

GET https://<адресAPIприложения>/public-api/v1/generations/<ID_генерации>
Authorization: Bearer <API_ключ>

Значение статуса находится внутри generation:

Статус	Что делать
`queued`	Задание ожидает обработки. Повторите чтение статуса позже
`processing`	Документ формируется. Продолжайте проверять состояние с паузой
`done`	Заберите `result_file_id` и скачайте файл
`error`	Прочитайте `error_message`, исправьте причину и затем создайте новую генерацию

Фрагмент ответа при успехе:

{
  "generation": {
    "id": "<ID_генерации>",
    "status": "done",
    "result_file_id": "<ID_файла>",
    "result_pdf_file_id": null,
    "error_message": null
  }
}

В полном ответе есть и другие сведения о генерации. Если был запрошен PDF и он создан, его ID находится в result_pdf_file_id.

Повторное чтение статуса не создаёт новый документ. Повторный POST /generate создаёт новое задание. Если исходный запрос завершился сетевым тайм-аутом, сначала проверьте, появилась ли генерация в приложении: повторная отправка может создать дубликат.

Шаг 4. Скачайте DOCX, XLSX или PDF

Используйте ID файла из успешной генерации:

GET https://<адресAPIприложения>/api/files/<ID_файла>/download
Authorization: Bearer <API_ключ>

Для PDF используйте значение result_pdf_file_id вместо result_file_id. Метод возвращает содержимое файла, которое интеграция должна сохранить с нужным расширением.

У маршрутов создания и проверки статуса нет префикса /api: они начинаются с /public-api/v1/. У скачивания файла префикс есть: /api/files/. Это три разных адреса.

Как проверить готовую интеграцию

Отправьте запрос с двумя товарами и артикулами 00109 и 00042.
Дождитесь done, скачайте файл и откройте его в Word или Excel.
Сверьте названия, порядок строк, количества, артикулы, номер договора и примечание.
Проверьте тот же набор с DOCX-шаблоном и XLSX-шаблоном, если интеграция использует оба формата.
Убедитесь, что внешняя система обрабатывает error и сохраняет ID созданной генерации для разбора ошибок.

Частые ошибки

Ответ или симптом	Возможная причина
HTTP 401	Ключ отсутствует, неверен, истёк или удалён; проверьте заголовок `Authorization`
HTTP 403	У ключа нет права, необходимого для этого запроса
HTTP 404 при создании	В установке, к которой относится ключ, не найден шаблон с указанным кодом
HTTP 422	Проверьте JSON и обязательные поля `template_code` и `payload`
В файле нет данных сделки	Они не переданы в `payload`; публичный API не получает их по ID сделки
Пустые артикулы	Не совпали ключи в `payload` и маркеры шаблона либо значения не переданы
Excel вместо `00109` показывает другое значение	Проверьте, что артикул передан JSON-строкой, и формат ячейки шаблона
Документ долго не готов	Читайте статус существующей генерации; не отправляйте повторные задания без проверки

Для обращения в поддержку подготовьте код шаблона, ID генерации, HTTP-статус и текст ошибки. Уберите ключ авторизации из передаваемого примера запроса.