Admin API: лендинги

Через эти методы интеграция делает то же, что раздел Лендинги и редактор файлов в панели: заводит лендинги, загружает архивы, правит файлы и сохраняет версии. Как лендинги устроены в панели — на странице Лендинги.

Общие правила

• Все методы страницы требуют токен с доступом Полный доступ (full). Подключение и заголовок Api-Key описаны на странице Admin API: обзор и авторизация, формат запросов и ошибок — на странице Формат запросов, ответов и ошибок.
• {id} в адресе — идентификатор лендинга в формате UUID, поле id из ответа.
• На неизвестный или удалённый лендинг сервер отвечает 404 с кодом not_found. На идентификатор не в формате UUID — 400 с кодом bad_request и сообщением некорректный идентификатор или значение.
• Пути файлов — относительные, от корня папки лендинга, со слэшами: index.html, css/style.css.
• Файлы и папки, имя которых начинается с точки, не читаются и не записываются. Ответ — 400, bad_request, скрытые файлы (начинающиеся с точки) не поддерживаются.
• Путь за пределы папки лендинга даёт 400, bad_request, недопустимый путь.

Объект лендинга

{
  "id": "5b0c3f0e-7c1a-4a55-9d0e-2f6b8c1d4e7a",
  "name": "Прелендинг DE",
  "url": "https://example.com/lp?cid={click_id}",
  "files_path": null,
  "type": "prelander",
  "storage": "external",
  "owner_id": "9a1d2c3b-4e5f-4a6b-8c7d-0e1f2a3b4c5d",
  "seq": 12
}

Список и чтение

Список лендингов

GET /api/v1/landers

Возвращает все лендинги команды, кроме удалённых. Новые идут первыми.

Ответ — 200 и массив объектов лендинга. Если лендингов нет, массив пустой.

Получить лендинг

GET /api/v1/landers/{id}

Возвращает один лендинг.

Ответ — 200 и объект лендинга.

Создание, изменение и удаление

Создать лендинг

POST /api/v1/landers

Создаёт лендинг. Владельцем становится пользователь, создавший токен.

Ответ — 201 и объект лендинга.

Ошибки:

• 400, bad_request, invalid json — тело не разобрано;
• 422, validation, name is required — нет названия.

curl -X POST https://panel.example.com/api/v1/landers \
  -H "Api-Key: <токен>" \
  -H "Content-Type: application/json" \
  -d '{"name":"Прелендинг DE","url":"https://example.com/lp?cid={click_id}"}'

Изменить лендинг

PUT /api/v1/landers/{id}

Меняет название, адрес, тип и вид хранения. Поля, которых нет в теле, сохраняют прежние значения.

Поле files_path этим методом не меняется.

Ответ — 200 и объект лендинга.

Ошибки:

• 400, bad_request, invalid json;
• 422, validation, name is required — название передано пустым.

Удалить лендинг

DELETE /api/v1/landers/{id}

Переносит лендинг и его файлы в корзину. Восстановление — методами страницы Admin API: корзина.

Ответ — 204 без тела.

Копия и доступ

Клонировать лендинг

POST /api/v1/landers/{id}/clone

Создаёт копию с названием «<название> (копия)». У локального лендинга копируются и файлы.

Тело можно не передавать.

Ответ — 201 и объект нового лендинга.

Кому открыт лендинг

GET /api/v1/landers/{id}/shares

Возвращает пользователей, которым открыт просмотр лендинга.

Ответ — 200:

{"user_ids": ["9a1d2c3b-4e5f-4a6b-8c7d-0e1f2a3b4c5d"]}

Задать доступ к лендингу

POST /api/v1/landers/{id}/shares

Заменяет список пользователей, которым открыт просмотр. Идентификаторы пользователей отдаёт Admin API: пользователи.

Ответ — 204 без тела.

Ошибки: 400, bad_request, invalid json.

Загрузка архива и файлов

Оба метода принимают multipart/form-data. Пределы: 1 ГБ на запрос, 1 ГБ на один файл, 1 ГБ на распакованный архив, 10 000 файлов в лендинге. Требования к архиву — на странице Локальный хостинг.

Загрузить архив

POST /api/v1/landers/{id}/upload

Распаковывает ZIP в папку лендинга. Прежние файлы заменяются содержимым архива. Если у лендинга уже были файлы, перед заменой они сохраняются как версия. Если архив не принят, прежние файлы остаются на месте. Внешний лендинг после загрузки становится локальным.

Ответ — 200 и список файлов после распаковки:

{"files": [{"path": "index.html", "size": 4812, "dir": false}]}

Ошибки:

• 400, bad_request, не удалось прочитать форму (загрузка прервана или повреждена);
• 413, too_large, превышен лимит загрузки 1 ГБ;
• 413, too_large, слишком много файлов;
• 413, too_large, файл слишком большой (лимит 1 ГБ на файл, 1 ГБ на распакованный архив);
• 422, validation, ожидался файл в поле archive;
• 422, validation, файл не является корректным .zip;
• 422, validation, архив сжат неподдерживаемым методом (LZMA, AES-шифрование и т.п.) — пересоберите обычным ZIP без пароля;
• 422, validation, архив повреждён — пересоберите его и загрузите заново.

curl -X POST https://panel.example.com/api/v1/landers/5b0c3f0e-7c1a-4a55-9d0e-2f6b8c1d4e7a/upload \
  -H "Api-Key: <токен>" \
  -F "[email protected]"

Догрузить файлы

POST /api/v1/landers/{id}/files

Добавляет один или несколько файлов к уже загруженным. Файл с тем же путём перезаписывается, остальные не меняются. Внешний лендинг становится локальным.

Ответ — 200:

{
  "files": [{"path": "img/hero.jpg", "size": 182044, "dir": false}, {"path": "index.html", "size": 4812, "dir": false}],
  "saved": ["img/hero.jpg"],
  "storage": "local"
}

files — все файлы лендинга, saved — пути только что сохранённых.

Ошибки:

• 400, bad_request — форма или один из файлов не прочитаны, либо путь недопустим;
• 413, too_large — превышен предел запроса, файла или числа файлов;
• 422, validation, ожидались файлы в поле files;
• 422, validation, нечего сохранять.

Файлы лендинга

Чтение и запись содержимого рассчитаны на текстовые файлы до 5 МБ. Файлы крупнее и картинки загружайте методами из раздела Загрузка архива и файлов.

Список файлов

GET /api/v1/landers/{id}/files

Возвращает файлы лендинга, отсортированные по пути. Папки отдельными строками не выводятся.

Ответ — 200:

{"files": [{"path": "css/style.css", "size": 2210, "dir": false}, {"path": "index.html", "size": 4812, "dir": false}]}

У лендинга без файлов массив пустой.

Прочитать файл

GET /api/v1/landers/{id}/file?path=index.html

Возвращает содержимое файла.

Ответ — 200:

Ошибки:

• 404, not_found, файл не найден;
• 413, too_large, файл больше 5 МБ — Редактор такие не открывает и не сохраняет; замените его загрузкой файла или архива;
• 422, validation, path is required.

Создать или сохранить файл

PUT /api/v1/landers/{id}/file

Записывает текстовый файл. Недостающие папки создаются. Внешний лендинг становится локальным.

Ответ — 200:

{"ok": true, "storage": "local"}

Ошибки:

• 400, bad_request, invalid json;
• 409, conflict, файл с таким путём уже есть;
• 413, too_large — содержимое больше 5 МБ или в лендинге уже 10 000 файлов;
• 422, validation, path is required.

Переименовать файл

POST /api/v1/landers/{id}/rename

Переименовывает файл или переносит его в другую папку лендинга. Существующий файл по новому пути не перезаписывается. Файл с именем leads.php не переименовывается: ответ — 400.

Ответ — 200:

{"ok": true}

Ошибки: 400, bad_request, нужны исходный и новый путь.

Удалить файл

DELETE /api/v1/landers/{id}/file?path=old.html

Удаляет один файл.

Ответ — 204 без тела.

Ошибки:

• 404, not_found, файл не найден;
• 422, validation, path is required.

Версии и архив

Версия — сохранённый снимок всех файлов лендинга. Хранится 10 последних версий, более старые удаляются при сохранении новой. В версии и в архив не попадают файлы и папки с точкой в начале имени и файл leads.php. Сохранение версии и скачивание архива рассчитаны на лендинг, у которого есть файлы. В панели те же действия описаны на странице Редактор файлов, версии и экспорт.

Список версий

GET /api/v1/landers/{id}/versions

Возвращает сохранённые версии, новые первыми.

Ответ — 200 и массив:

Если версий нет, массив пустой.

Сохранить версию

POST /api/v1/landers/{id}/versions

Сохраняет текущие файлы как новую версию. Тело не нужно.

Ответ — 201 и объект версии с полями id, created_at, size.

Ошибки: 413, too_large — в лендинге больше 10 000 файлов или больше 1 ГБ.

Восстановить версию

POST /api/v1/landers/{id}/versions/{version}/restore

Заменяет файлы лендинга файлами версии. {version} — поле id из списка версий. Перед заменой текущие файлы сохраняются как новая версия. Тело не нужно.

Ответ — 200:

{"ok": true}

Скачать архив

GET /api/v1/landers/{id}/archive

Отдаёт текущие файлы лендинга одним ZIP.

Ответ — 200, тип содержимого application/zip, имя файла page.zip.

curl https://panel.example.com/api/v1/landers/5b0c3f0e-7c1a-4a55-9d0e-2f6b8c1d4e7a/archive \
  -H "Api-Key: <токен>" \
  -o page.zip

Ошибки: 413, too_large — в лендинге больше 10 000 файлов или больше 1 ГБ.