LF Drive API: как подключить свой сервис и выполнить первые запросы

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

Когда нужен API, а когда достаточно плагина

Для выбора изображения в WordPress удобнее готовый плагин. Для экспорта фрейма — интеграция Figma. API нужен, когда действие запускает ваша программа: генератор каталога, сервер CRM, внутренний кабинет или сценарий автоматизации. Это интерфейс для разработки интеграции, а не готовая кнопка подключения любой системы.

API доступен на действующих тарифах «Про» и «Студия» при подтверждённой почте. Отдельные операции сохраняют ограничения тарифа: наличие API на «Про» не открывает оформление и собственные домены «Студии». Точный перечень методов, параметров и ответов опубликован в документации и OpenAPI.

Создайте токен под конкретную задачу

Откройте страницу разработчика. Дайте токену понятное имя: например, «Обновление каталога — production». Выберите только необходимые права. Для чтения аккаунта нужно account:read, для списка файлов — files:read, для загрузки и замены — files:write. Изменение доступа к ссылкам требует отдельного права links:write.

Храните секрет на сервере или в хранилище учётных данных вашей платформы. Не помещайте его в HTML, браузерный JavaScript, макет, публичный репозиторий или URL. Для тестов и рабочего процесса лучше использовать разные токены. Если токен утёк, отзовите его и переподключите только затронутую интеграцию.

Первый запрос: проверить аккаунт

В примерах переменная LFDRIVE_TOKEN уже задана безопасным способом в серверном окружении. Не вставляйте реальный токен в опубликованный код статьи.

curl --fail-with-body --silent --show-error \
  -H "Authorization: Bearer $LFDRIVE_TOKEN" \
  https://lfdrive.ru/api/v1/account

В успешном JSON-ответе проверьте ok и объект data. Там находятся аккаунт, тариф, права, лимиты и возможности. Не считайте любое тело ответа успехом: HTTP-код, ok и ожидаемые поля нужно проверять вместе.

Загрузка файла без случайных дублей

Запросы изменения требуют заголовок Idempotency-Key. Это идентификатор одного логического действия. Создайте его один раз и сохраните вместе с заданием до отправки. Если соединение оборвётся, повторите ту же операцию с тем же ключом и содержимым. Для другой операции нужен новый ключ.

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

Пример загружает реальный локальный catalog.pdf; запускайте его только для подготовленного тестового файла. При успехе сохраните data.id и data.url. Первый нужен для будущих операций, второй — для размещения. При желании передайте project_id существующего проекта в multipart-поле.

Что можно связать через API

• Файлы и версии. Загружать, искать, перемещать в проекты, заменять и восстанавливать предыдущие версии.
• Ссылки. Менять доступные настройки доступа с проверкой совместимости режимов.
• Формы и заявки. Создавать и настраивать формы, получать отправленные материалы в вашу систему.
• Продажи. Читать заказы и настраивать продажу; банковские карты API не принимает и статус оплаты вручную не подтверждает.
• Статистика. Получать доступные показатели аккаунта и отдельных файлов.
• Возможности «Студии». Управлять доступными настройками брендинга и доменов в рамках тарифа.

Обработайте ошибки до запуска

401 означает проблему авторизации; 403 — отсутствие нужного доступа, права или подходящего тарифа. 413 указывает на слишком большой запрос, 422 — на ошибку данных, 429 — на ограничение частоты. При 409 разберите конфликт или неопределённость операции по документации. Не повторяйте все ошибки одинаково.

Для временных сбоев применяйте ограниченное число повторов с паузой и тем же ключом действия. Записывайте HTTP-код и request_id, но не секреты и полные документы. Если интеграция упёрлась в квоту, бесконечные повторы не помогут: нужно освободить место или изменить условия работы.

Минимальный приёмочный тест

1. Получить аккаунт и список файлов токеном с нужными правами.
2. Загрузить небольшой тестовый документ и сохранить ID.
3. Повторить тот же запрос с тем же ключом и убедиться, что второго файла нет.
4. Проверить, что токен только для чтения не может выполнить изменение.
5. Удалить исключительно созданный для теста объект и проверить результат.