Публичная документация API

ID книг и томов

GET /api/v1/translator/statuses

{
  "data": [
    { "id": 1, "title": "В процессе" },
    { "id": 2, "title": "Завершено" }
  ],
  "appliesTo": ["books", "volumes"]
}

Книги и тома используют один production-справочник. Не фиксируйте соответствия в импортёре навсегда: получите их перед импортом и передавайте выбранный statusId. Списки и ответы создания также возвращают это поле.

Создание и пересчёт

POST /api/v1/translator/books/125/chapters
{
  "volume": 1,
  "number": 12,
  "title": "Глава 12",
  "html": "<p>Текст…</p><img src="/api/media/9001" alt="Карта">",
  "draft": false,
  "sourceId": "import:12",
  "source": {
    "provider": "ranobelib",
    "sourceId": "import:12",
    "sourceUrl": "https://source.example/chapter/12",
    "language": "ru",
    "sourceTitle": "Глава 12",
    "rawHtml": "<p>Оригинальная разметка источника…</p>"
  },
  "translatorIds": [12, 18]
}

HTML очищается на сервере. Количество Unicode-символов и hasImages пересчитываются при создании, обновлении, восстановлении и отложенной публикации. Необязательный объект source сохраняет приватный исходный HTML для повторного безопасного импорта; читателю он не выдаётся.

translatorIds необязателен. В PATCH отсутствие поля сохраняет прежнее авторство, массив заменяет его, а [] очищает явное авторство главы. Все ID должны заранее быть назначены книге через её taxonomy. Ответы GET содержат translatorIds и translators.

Сначала файл, затем HTML

curl --fail-with-body \
  -H "Authorization: Bearer $RANOBEHUB_TOKEN" \
  -F "image=@map.webp" \
  https://ranobehub.org/api/v1/translator/books/125/images

Ответ содержит mediaId и относительный url. Этот URL вставляется в <img src>. Внешние HTTPS-изображения тоже допустимы, но управлять их жизненным циклом RanobeHub не может.

Сравнение текста без скачивания HTML

GET /api/v1/translator/books/125/chapter-hashes?limit=100&cursor=0

{
  "data": [
    { "id": 436210, "volume": 1, "number": 12, "textHash": "57f516dcf9033f3914b87f6f43c3955c67b1a9fa1dbd47f746b65d4194a6b58f" }
  ],
  "hash": {
    "algorithm": "sha256",
    "normalization": "plain-text-v1"
  },
  "nextCursor": 436309
}

plain-text-v1 удаляет HTML-теги, изображения, SVG, скрипты и другие нетекстовые медиа, декодирует HTML-сущности, приводит Unicode к NFC и сворачивает пробелы. Поэтому косметическое форматирование не меняет хеш. Изменение видимого текста меняет его. Страница содержит до 200 глав; продолжайте по nextCursor, пока он не станет null. Для одной известной главы используйте лёгкий GET /api/v1/translator/chapters/:id/hash без HTML. Полный GET /api/v1/translator/chapters/:id возвращает тот же хеш вместе с содержимым.

Справочные ссылки книги

GET /api/v1/content/books/125/links

POST /api/v1/content/books/125/links
{
  "sourceId": 4,
  "url": "https://example.org/novel/slug"
}

PATCH /api/v1/content/books/125/links/81
{ "url": "" }

GET возвращает одновременно data со ссылками книги и sources с допустимыми sourceId. Для одного источника у книги допускается одна ссылка. Пустой url в PATCH сохраняет старое поведение панели и скрывает ссылку; DELETE удаляет её полностью.

Конфигурация источника

PUT /api/v1/content/books/125/parser
{
  "url": "https://example.org/novel/slug",
  "provider": "novel-tl",
  "enabled": false,
  "config": {},
  "schedule": null,
  "canRefresh": false
}

PATCH /api/v1/content/books/125/parser
{ "provider": "ranobelib", "enabled": true }

provider определяет адаптер: legacy, ranobelib, rulate или novel-tl (Novel TL, ZNovel и RuRaNovel). PUT безопасно создаёт настройку или полностью заменяет первую запись книги; пропущенные provider и enabled равны legacy и false. PATCH меняет только переданные поля. Если в старой базе у книги несколько записей, ответ показывает остальные в additionalParserIds, но изменяется только первая — как в текущей панели.

Endpoint хранит и валидирует конфигурацию поставщика, но сам не скачивает главы в HTTP-запросе: запуск выполняет отдельный импортёр по расписанию. Это исключает случайную публикацию пустых книг и позволяет безопасно повторять синхронизацию.

RanobeLib и другие источники

PUT /api/v1/content/books/125/external-ratings/ranobelib
{
  "rating": 4.63,
  "ratingScale": 5,
  "votes": 1842,
  "sourceBookId": "mushoku-tensei",
  "observedAt": "2026-08-20T10:00:00Z"
}

source — постоянный ASCII-ключ импортёра. ratingScale описывает исходную шкалу и по умолчанию равен 10: сервер сам преобразует 4,63/5 или 92/100 к шкале сайта. Повторный PUT полностью заменяет снимок только этого источника.

Пока на RanobeHub не больше 20 локальных оценок, итог является взвешенным средним всех локальных и внешних голосов, а счётчики суммируются. С 21-й локальной оценки внешние снимки остаются сохранены, но перестают влиять на публичные computedRating и computedRatingVotes.