Как автоматически обновлять PDF-каталог на сайте через LF Drive API

Цены хранятся в учётной системе, каталог собирается из шаблона, а на сайте всё равно лежит вчерашний PDF. Проблема не в скорости генерации: последняя ручная загрузка осталась вне процесса. Её можно связать с публикацией через API LF Drive.

Отделите генерацию от публикации

LF Drive хранит и выдаёт файл, но не рассчитывает цены и не собирает PDF из вашей базы. Генератор находится в вашей системе. Сначала он создаёт готовый документ, проверяет его и только потом передаёт результат в LF Drive. Так ошибка шаблона не заменит действующий каталог пустой страницей.

Рабочая цепочка выглядит так: изменения данных → создание PDF → проверка → замена существующего файла → проверка публичной выдачи. Запускать её можно по расписанию или после утверждения нового выпуска. Для материалов с ценами полезно оставить явный этап согласования.

Один раз создайте постоянный объект

Загрузите первый каталог, сохраните его ID и публичную ссылку в конфигурации процесса. Разместите этот адрес на сайте и в QR-кодах. Последующие выпуски должны заменять тот же объект. Если при каждом запуске выполнять POST /files, вы получите новые файлы, а размещённая ссылка останется старой.

Для API нужен активный «Про» или «Студия». Выдайте токену права files:read и files:write, а право account:read добавьте, если процесс проверяет квоты. Не выдавайте доступ к продажам, формам и брендингу, если задача ограничивается каталогом.

Что проверить перед отправкой

• Файл существует и завершён. Отправлять PDF, который генератор ещё записывает, нельзя.
• Размер и структура правдоподобны. Проверяйте сигнатуру PDF, возможность открытия и ожидаемые разделы, а не только расширение.
• Внутри нужный выпуск. Номер редакции, дата и контрольные позиции помогают поймать подмену исходных данных.
• Публикация разрешена. Наличие нового файла не всегда означает, что цены уже утверждены.

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

Запрос замены

Ниже ID 123 — пример. Подставьте ID специально подготовленного файла и заранее создайте ключ одного задания. Не запускайте пример против чужого или рабочего каталога без проверки.

curl --fail-with-body --silent --show-error \
  -H "Authorization: Bearer $LFDRIVE_TOKEN" \
  -H "Idempotency-Key: catalog-release-20261019-001" \
  -F "file=@catalog.pdf" \
  https://lfdrive.ru/api/v1/files/123/replace

По умолчанию текущая версия сохраняется в историю по правилам тарифа. Не передавайте without_history=true, если рассчитываете на откат. После успеха проверьте data.id и вернувшийся URL. Для стабильного сценария сохраняйте тип PDF: смена расширения может изменить рекомендуемый суффикс адреса, хотя публичный код остаётся прежним.

Защита от повторов и гонок

Один выпуск получает один Idempotency-Key. При повторе неизменённого запроса используйте тот же ключ. Другой PDF — уже другая операция. Если исход неизвестен, сначала проверьте GET /operations/{key}; новый ключ не является способом безопасно «начать заново».

Также исключите параллельную публикацию выпусков в своей очереди. Идемпотентность защищает повтор одного действия, но не определяет, какой из двух разных выпусков новее. Без очереди медленный вчерашний процесс способен закончиться после сегодняшнего и вернуть старое содержимое.

Проверьте то, что увидит посетитель

Успешный ответ API доказывает выполнение серверной операции, но не очистку всех кэшей. Проверьте публичный адрес, номер выпуска в документе и страницу сайта с кнопкой скачивания. Отдельно используйте браузер, в котором открывали старый каталог: приватное окно не воспроизводит его кэш.

Для файлов по постоянному URL согласуйте политику проверки актуальности или допустимый TTL с разработчиком и CDN. Очистка CDN не удаляет уже сохранённую копию из браузера посетителя. Не обещайте мгновенное обновление во всех устройствах, если раньше они получили длинный срок хранения без перепроверки.

Откат и журнал публикаций

В журнале храните ID выпуска, ID файла, ключ операции, время, результат проверки и request_id. При ошибке найдите нужную запись истории через GET /files/{id}/versions и восстановите выбранную версию методом из документации. Перед восстановлением убедитесь, что это действительно предыдущий утверждённый выпуск.

История имеет лимиты количества и срока хранения. Для долгосрочного архива сохраняйте утверждённые исходники отдельно. После отката повторите проверку публичной выдачи: восстановление тоже является обновлением и сталкивается с теми же правилами кэша.