Client API v1 — документация

Обзор

BookFlip Client API позволяет автоматизировать публикацию PDF-документов. Типичный сценарий: загружаете PDF, получаете flipbook_id и version_id, отслеживаете статус обработки, после done флипбук готов.

API доступен по адресу https://bookflip.ru/api/v1/.

Аутентификация

Получение ключа

API-ключи создаются в личном кабинете: Профиль → API ключи (/app/profile/api-keys). Доступно только на тарифе Команда. При создании можно задать дату истечения.

Важно: токен показывается только один раз при создании. Сохраните его сразу — восстановить токен невозможно.

Передача ключа

Ключ передаётся одним из двух способов:

Через Authorization (рекомендуется):

Authorization: Bearer bookflip_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Через X-Api-Key:

X-Api-Key: bookflip_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Формат токена

Формат: bookflip_ + 48 шестнадцатеричных символов. В базе хранится только SHA-256 хеш токена — восстановить токен по хешу невозможно.

Ограничения

Rate limiting

120 запросов/мин на API-ключ на все эндпоинты /api/v1/*. При превышении — 429 Too Many Requests.

Размер запросов

Загрузка файлов: 512 МБ. Остальные эндпоинты (JSON): 1 МБ. Лимиты загрузки учитывают тариф workspace.

Справочник API

GET /api/v1/flipbooks Список флипбуков

Постраничный список флипбуков workspace с поиском и фильтрацией.

Query-параметры

Параметр	Тип	По умолч.	Описание
page	int	1	Номер страницы (≥ 1)
per_page	int	20	Записей на странице (1–100)
search	string	—	Поиск по названию
status	string	—	Фильтр: `published`, `archived`
sort	string	created_at	Поле сортировки
dir	string	desc	Направление: `asc`, `desc`

Ответ 200

{
  "flipbooks": [ /* Flipbook[] */ ],
  "page": 1,
  "per_page": 10,
  "total_pages": 1
}

Пример

curl -X GET "https://bookflip.ru/api/v1/flipbooks?page=1&per_page=10&status=published" \
  -H "Authorization: Bearer bookflip_xxx..."

Ошибки: 401 Unauthorized, 400 Workspace not found, 500 Failed to list flipbooks

GET /api/v1/flipbooks/:id Получить флипбук

Детальная информация о флипбуке: все версии и страницы активной версии — те, что видит читатель.

Параметры пути

Параметр	Тип	Описание
id	UUID	ID флипбука

Ответ 200

Объект Flipbook со всеми versions[] (новые первыми) и полем pages[] — страницы активной версии. В списке флипбуков pages нет, а в versions только активная версия.

Пример

curl -X GET "https://bookflip.ru/api/v1/flipbooks/0199abcd-1234-7abc-8901-234567890abc" \
  -H "Authorization: Bearer bookflip_xxx..."

Ошибки: 400 Invalid flipbook ID, 404 Flipbook not found

POST /api/v1/flipbooks Создать флипбук

Загружает PDF-файл и создаёт новый флипбук. Обработка асинхронная — сразу возвращается статус pending.

Тело запроса (multipart/form-data)

Поле	Тип	Обязат.	Описание
file	file	да	PDF-файл
title	string	нет	Название (иначе — имя файла)

Ответ 201

{
  "flipbook_id": "0199abcd-1234-7abc-8901-234567890abc",
  "version_id": "0199abcd-8765-7def-4321-234567890def",
  "title": "Каталог 2026",
  "status": "pending",
  "file_size": 5242880,
  "estimated_seconds": 30.5,
  "created_at_unix": 1718123456
}

Пример

curl -X POST "https://bookflip.ru/api/v1/flipbooks" \
  -H "Authorization: Bearer bookflip_xxx..." \
  -F "file=@catalog.pdf" \
  -F "title=Каталог 2026"

Ошибки: 400 file is required, 422 — ошибка сервиса

POST /api/v1/flipbooks/:id/versions Создать версию

Загружает новый PDF как дополнительную версию существующего флипбука.

Тело запроса (multipart/form-data)

Поле	Тип	По умолч.	Описание
file	file	обязат.	PDF-файл новой версии
activate	string	true	Автоактивация после обработки

Ответ 201

{
  "version_id": "0199abcd-9999-7def-8888-234567890def",
  "version_status": "pending",
  "activate_on_done": true,
  "file_size": 6291456,
  "estimated_seconds": 35.2,
  "created_at_unix": 1718124567
}

Пример

curl -X POST "https://bookflip.ru/api/v1/flipbooks/UUID/versions" \
  -H "Authorization: Bearer bookflip_xxx..." \
  -F "file=@catalog_v2.pdf" \
  -F "activate=true"

Ошибки: 400 Invalid flipbook ID, 400 file is required, 422 — ошибка сервиса

POST /api/v1/flipbooks/:id/versions/:vid/activate Активировать версию

Делает указанную версию активной. Предыдущая активная версия автоматически деактивируется.

Параметры пути

Параметр	Тип	Описание
id	UUID	ID флипбука
vid	UUID	ID версии

Ответ 200

{
  "success": true,
  "active_version_id": "0199abcd-9999-7def-8888-234567890def"
}

Пример

curl -X POST "https://bookflip.ru/api/v1/flipbooks/UUID/versions/UUID/activate" \
  -H "Authorization: Bearer bookflip_xxx..."

Ошибки: 400 Invalid IDs, 422 — ошибка сервиса

GET /api/v1/flipbooks/:id/versions/:vid/status Статус версии

Возвращает текущий статус обработки версии. Используйте для отслеживания готовности после создания.

Ответ 200

{
  "version_id": "0199abcd-9999-7def-8888-234567890def",
  "status": "done",
  "is_active": true,
  "version": 2,
  "pages": 24,
  "file_name": "catalog_v2.pdf",
  "file_size": 6291456
}

Поле	Описание
status	`pending` / `processing` / `done` / `error`
is_active	Является ли версия активной
version	Номер версии
pages	Количество страниц (0 пока `pending`)
file_name	Оригинальное имя файла
file_size	Размер в байтах

Ошибки: 400 Invalid IDs, 404 Version not found

DELETE /api/v1/flipbooks/:id/versions/:vid Удалить версию

Удаляет неактивную версию флипбука.

Нельзя удалить активную версию. Сначала активируйте другую версию.

Ответ 200

{"success": true}

Пример

curl -X DELETE "https://bookflip.ru/api/v1/flipbooks/UUID/versions/UUID" \
  -H "Authorization: Bearer bookflip_xxx..."

Ошибки: 400 Invalid IDs, 422 — ошибка сервиса

Коды ответов

Код	Описание
200	Успешный запрос
201	Ресурс создан (флипбук или версия)
400	Неверные параметры запроса
401	Невалидный или отсутствующий API-ключ
404	Ресурс не найден
422	Ошибка бизнес-логики (лимиты, ограничения, формат)
429	Превышен лимит запросов (120/мин)
500	Внутренняя ошибка сервера

Все ошибки возвращают тело в формате {"error": "описание"}.

Типы данных

Flipbook

{
  "id": "uuid",
  "title": "string",
  "slug": "string",
  "description": "string",
  "status": "published | archived",
  "url": "ссылка на читалку",
  "created_at": "datetime",
  "updated_at": "datetime",
  "versions": [ /* Version[] */ ],
  "pages": [ /* Page[], только GET /flipbooks/:id */ ]
}

Version (версия)

{
  "id": "uuid",
  "version": "int",
  "status": "pending|processing|done|error",
  "is_active": "bool",
  "activate_on_done": "bool",
  "file_name": "string",
  "file_type": "string",
  "mime_type": "string",
  "file_size": "int64",
  "width": "int",
  "height": "int",
  "created_at": "datetime"
}

Page (страница)

{
  "id": "uuid",
  "position": "int",
  "width": "int",
  "height": "int",
  "img_max": "URL картинки",
  "img_mid": "URL картинки",
  "img_min": "URL картинки"
}