Обзор

REST JSON API для мобильного приложения IPR SMART. Совместим по маршрутам и формату ответов с legacy old-mobible-api, работает с базой данных ipr_smart.

Установка и запуск

composer install
cp .env.example .env        # Windows: copy .env.example .env
php artisan key:generate

Настройте .env (см. раздел ниже), затем:

php artisan serve
# → http://localhost:8000

Для production: document root указывает на каталог public/. CI деплоит на mobile2.iprbookshop.ru (master) и mobile.dev.iprbookshop.ru (develop).

Переменные окружения

Для MariaDB/MySQL 5.7 в OSPanel укажите DB_COLLATION=utf8mb4_unicode_ci (MySQL 8 collation utf8mb4_0900_ai_ci не поддерживается).

Заголовки и версии API

Почти все запросы обязаны содержать заголовок:

VERSION-API: 3

Исключение: GET /oauth — заголовок не требуется (как в old-mobible-api).

Авторизация

Публичные маршруты (с VERSION-API)

Параметры uid / deviceId / accessToken не нужны:

• POST /users/auth
• GET /users/status
• GET /users/check
• GET /users/restore
• POST /users/create
• GET|POST /users/register
• GET /users/code/check
• GET /users/code/info
• GET|POST /users/create/by-code
• GET /v3/books/catalog, GET /v3/books/{id}
• GET /v3/journals/catalog, GET /v3/journals/{id}
• GET /v3/years/{yearId}, GET /v3/numbers/{id}
• GET /v3/authors, GET /v3/publication-types, GET /v3/education-types, GET /v3/ugnps, GET /v3/scientific-schools, GET /v3/languages, GET /v3/bbks, GET /v3/isbns
• GET /v3/journals/years, GET /v3/journals/publishers, GET /v3/journals/ugnps, GET /v3/journals/vak, GET /v3/journals/isbns
• GET /v3/home/novelties, GET /v3/home/popular, GET /v3/home/journals

Если в запросе каталога передан верный uid и токен, выдача ограничивается организацией пользователя. Без них каталог общий, избранное в карточке — 0.

Без VERSION-API

• GET /oauth

Защищённые маршруты

Middleware ApiAccess проверяет следующие параметры (query string или body):

Формула токена доступа

Поток авторизации

Пароли при входе

• Принимается только формат приложения: md5(md5(plain) + MOBILE_AUTH_SALT)
• Legacy MD5 в БД → сравнивается с md5(хранимый_md5 + соль)
• Bcrypt в БД → хеш приложения сверяется с сохранённым верификатором (регистрация, восстановление пароля)

Формат ответов

v3 (VERSION-API: 3)

{
  "meta": { "success": true, "message": "" },
  "data": { ... }
}

Ошибка:

{
  "meta": { "success": false, "message": "Текст ошибки" },
  "data": null
}

Legacy (VERSION-API: 1–2)

{ "success": "true", "message": "", ... }
{ "success": "false", "message": "Текст ошибки" }

Авторизация (POST /users/auth) при legacy оборачивает данные в ключ user:

{
  "success": "true",
  "message": "",
  "user": {
    "username": "...", "uid": 123, "accessToken": "...",
    "cid": 45, "fullname": "...", "org_name": "..."
  }
}

Исключения из общих правил

Пагинация

{
  "meta": { "success": true, "message": "" },
  "data": {
    "total": 100,
    "per_page": 50,
    "current_page": 1,
    "last_page": 2,
    "next_page_url": "...",
    "prev_page_url": null,
    "from": 1,
    "to": 50,
    "data": [ ... ]
  }
}

Исключение: GET /users/status всегда возвращает legacy-формат независимо от версии API (см. таблицу выше).

Совместимость с old-mobible-api

API реализован как замена legacy old-mobible-api с сохранением маршрутов, имён полей (pagetitle, tv_*) и форматов ответов.

Сводка по группам маршрутов

Значения selection_options (каталог книг)

Пользователи

{
  "meta": { "success": true, "message": "" },
  "data": {
    "username": "user@example.com",
    "uid": 123,
    "cid": 45,
    "fullname": "Иванов И.И.",
    "org_name": "Университет",
    "email": "user@example.com",
    "blockedAfter": 1735689600,
    "blockedHash": "abc...",
    "accessToken": "device_token_from_db",
    "clientLogotype": "https://...",
    "clientColor": "ff9900"
  }
}

{
  "success": "true",
  "message": "",
  "version": { "version": 13, "strong": true },
  "username": "Иванов И.И.",
  "org_name": "Университет",
  "clientLogotype": "https://...",
  "clientColor": "ff9900"
}

{
  "success": true,
  "message": "Вы успешно зарегистрировались в системе",
  "data": { "user": { "email": "...", "fullname": "...", "role_id": 5 } }
}

{
  "success": false,
  "message": "Пользователь с таким email уже существует",
  "errors": { "email": ["Пользователь с таким email уже существует"] }
}

{
  "success": true,
  "message": "Данные кода были успешно получены",
  "data": {
    "organization": { "id": 45, "name": "Организация" },
    "role": { "id": 5, "name": "Студент" }
  }
}

Книги

Каталог и карточка публичные. Избранное защищённое. Канонический путь: /v3/books/...

Справочники фильтров книг

Списки для выпадающих фильтров каталога. Значения из ответов передаются в GET /v3/books/catalog параметрами из таблицы выше. Списки authors и scientific-schools постраничные: query, page, per_page.

Журналы

Фильтры журналов

Публичные списки для выпадающих фильтров. Списки книг (/v3/ugnps) для УГСН тоже подходят: GET /v3/journals/ugnps отдаёт тот же справочник.

Номера журналов

Поиск

Главная

Блоки как на главной ipr-smart.local: новинки, популярные книги и журналы. Публичные. Параметр limit — размер списка (по умолчанию 10, максимум 50).

{
  "meta": { "success": true, "message": "" },
  "data": {
    "last": {
      "id": 68,
      "publication_id": 105644,
      "publication_type": 1,
      "page": 12,
      "publication": { "id": 105644, "title": "...", "title_additional": "", "pagetitle": "...", "authors": "...", "cover": "...", "image": "..." },
      "book": { "...": "то же, если publication_type = 1" }
    }
  }
}

Избранное

Тип публикации: type=1 — книга, type=2 — журнал или номер. Если type не указан, тип определяется по ID.

listId[]=123&listId[]=456&uid=123
→ { "success": "true", "message": "Издания успешно добавлены!" }

{
  "uploads": [
    { "id": 123, "type": 1, "action": "add" },
    { "id": 456, "type": 2, "action": "delete" }
  ]
}

Подборки

Пользовательские подборки книг — как в личном кабинете ipr-smart.local. Защищённые маршруты. Канонический путь: /v3/selections/... (те же пути есть и без префикса /v3).

{
  "meta": { "success": true, "message": "Подборки были успешно получены" },
  "data": {
    "selections": [
      {
        "id": 1,
        "name": "К курсовой",
        "first_book_cover": "https://www.iprbookshop.ru/images/books/...",
        "books_count": 3
      }
    ]
  }
}

Скачивание

Два защищённых метода без префикса /v3. Нужны uid, deviceId и ежедневный accessToken (или Authorization: Bearer …). Ответ — не JSON, а бинарный файл.

SSL-скачивание (для мобильной разработки)

Руководство для разработчика приложения: как скачать и расшифровать PDF через GET /ssl-download.

Что отличается от /download

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

1. Сделать GET /ssl-download?... с теми же auth-параметрами, что для остальных защищённых методов. Заголовок VERSION-API: 3 обязателен.
2. Проверить HTTP-статус: 200 — ок; 404 с пустым телом — ошибка (нет файла / нет доступа / нет устройства). JSON-ошибки не будет.
3. Сразу прочитать заголовки ответа (до или вместе с телом — ключ в теле не дублируется):

   Заголовок	Обязателен клиенту	Описание
   X-Session-Key	Да	Base64 → ровно 32 байта AES-ключа
   X-Encryption-Mode	Рекомендуется	Должен быть chunked
   X-Chunk-Size	Нет	Размер plaintext-чанка на сервере (обычно 4194304). На расшифровку не влияет
   X-IV	Нет	Базовый IV сессии. Для расшифровки не нужен: IV каждого чанка уже лежит в теле

4. Скачать тело как сырые байты (не UTF-8 string, не JSON).
5. Разобрать тело на кадры и расшифровать каждый AES-256-CBC.
6. Склеить plaintext-чанки по порядку → это PDF. Сохранить/открыть.

Формат тела (кадр за кадром)

offset 0:
  uint8   ivLength          // всегда 16
  bytes   chunkIv[ivLength] // 16 байт
  uint32  cipherLength      // big-endian (network byte order)
  bytes   ciphertext[cipherLength]

далее — следующий кадр, пока не кончатся байты

Алгоритм расшифровки одного кадра

key = Base64Decode(response.headers["X-Session-Key"])  // 32 bytes

AES-256-CBC decrypt:
  key     = key
  iv      = chunkIv из кадра
  data    = ciphertext из кадра
  padding = PKCS7

результат кадра = plaintext bytes
итог = concat(plaintext_0, plaintext_1, ...)

Библиотеки: Android — javax.crypto.Cipher / AES/CBC/PKCS5Padding (это PKCS7); iOS — CommonCrypto / CryptoKit; Flutter — pointycastle / encrypt с AES-CBC + PKCS7.

Псевдокод парсера

fun decryptSslDownload(body: ByteArray, sessionKeyBase64: String): ByteArray {
  key = base64Decode(sessionKeyBase64)
  assert key.size == 32

  out = empty buffer
  i = 0
  while i < body.size:
    if i + 1 > body.size: error("truncated")
    ivLen = body[i] as uint8; i += 1
    if ivLen != 16: error("unexpected IV length")
    if i + ivLen + 4 > body.size: error("truncated header")

    chunkIv = body[i .. i+ivLen); i += ivLen
    cipherLen = readUInt32BE(body, i); i += 4
    if i + cipherLen > body.size: error("truncated body")

    cipher = body[i .. i+cipherLen); i += cipherLen
    out.append( aes256CbcDecrypt(cipher, key, chunkIv, PKCS7) )

  return out  // PDF bytes, обычно начинается с "%PDF-"
}

Важные нюансы для мобильного клиента

• Ключ одноразовый. На каждый запрос новый X-Session-Key. Нельзя сохранить ключ с прошлого скачивания и применить к новому телу.
• Не путать с deviceToken. Здесь ключ не из access_token устройства и не ежедневный accessToken.
• Заголовки могут резаться прокси. На проде проверьте, что nginx/CDN пропускает X-Session-Key, X-IV, X-Encryption-Mode, X-Chunk-Size (при необходимости underscores_in_headers / CORS Access-Control-Expose-Headers для WebView).
• HTTP-клиент: нужен доступ к response headers + raw body. Обычный «скачать в файл по URL» без чтения заголовков не подойдёт — ключ потеряется.
• Прогресс: без Content-Length процент загрузки по размеру ответа недоступен; можно показывать индетерминированный прогресс или опираться на известный размер издания с карточки (приблизительно, тело будет больше).
• Проверка результата: после расшифровки первые байты должны быть %PDF. Иначе — битый поток или неверный ключ.
• Совместимость со smart: формат кадров тот же, что у web-ридера. Логику можно портировать с decryptChunked / decryptChunkedFromStream из сайта.
• Стримить расшифровку можно: накапливать входящие байты, как только собран полный кадр — расшифровать и дописать в файл; не обязательно ждать весь ответ в RAM.

Ошибки

Минимальный пример запроса

curl -D - -o book.bin \
  "https://mobile2.iprbookshop.ru/ssl-download?id=162291&type=1&uid=UID&deviceId=DEVICE&accessToken=TOKEN" \
  -H "VERSION-API: 3"

# Из ответа взять X-Session-Key, затем расшифровать book.bin → PDF

Цитаты, закладки, контент, рейтинг

Маршруты на уровне корня (не внутри /books/). {id} — ID публикации (книги).

{
  "meta": { "success": true, "message": "" },
  "data": { "value": 4.5, "user_value": 5 }
}

Примеры запросов

1. Авторизация

passwd — не открытый пароль, а md5(md5(plain) + MOBILE_AUTH_SALT):

curl -X POST "http://localhost:8000/users/auth" \
  -H "VERSION-API: 3" \
  -d "username=user@example.com" \
  -d "passwd=COMPUTED_ANDROID_HASH" \
  -d "device_id=my-device-001"

2. Вычисление токена (PHP)

$salt = 'Ga90IfDBzo2Mqcva';       // MOBILE_AUTH_SALT
$deviceToken = '...';              // accessToken из ответа auth
$deviceId = 'my-device-001';
$date = date('Ymd');

$token = md5($salt . $deviceToken . $deviceId . $date);

3. Каталог книг

curl "http://localhost:8000/v3/books/catalog?page=1&uid=123&deviceId=my-device-001&accessToken=COMPUTED_TOKEN&date=20250714" \
  -H "VERSION-API: 3"

4. Карточка книги

curl "http://localhost:8000/v3/books/42?uid=123&deviceId=my-device-001&accessToken=COMPUTED_TOKEN" \
  -H "VERSION-API: 3"

5. Поиск

curl "http://localhost:8000/v3/search?s=математика&type=1&page=1&uid=123&deviceId=my-device-001&accessToken=COMPUTED_TOKEN" \
  -H "VERSION-API: 3"

6. Добавить в избранное

curl -X PUT "http://localhost:8000/favorite/42?type=1&uid=123&deviceId=my-device-001&accessToken=COMPUTED_TOKEN" \
  -H "VERSION-API: 3"

7. Синхронизация избранного (legacy listId)

curl -X POST "http://localhost:8000/favorite/uploads" \
  -H "VERSION-API: 3" \
  -d "listId[]=42&listId[]=43&uid=123&deviceId=my-device-001&accessToken=COMPUTED_TOKEN"

8. OAuth (без VERSION-API)

curl "http://localhost:8000/oauth?username=user&password=secret&time=1234567890&hash=COMPUTED_HASH"

Типичные ошибки

IPR SMART Mobile API · Laravel 11.57.1 · Совместимость с old-mobible-api