Главная

Документация API

Практическая документация соответствует текущей публичной версии API сервиса «Химия слова».

Быстрый старт

  • Коммерческие маршруты: /api/v1/....
  • Публичные инструменты: /api/public/v1/tools/....
  • Коммерческий запрос выполняется с заголовком:
    Authorization: Bearer <API_KEY>.
  • Создавать и отзывать ключи можно после регистрации в
    личном кабинете.
  • В ответе используется единый envelope: ok, data,
    meta.request_id.

Rate-limit заголовки

Коммерческий и анонимный публичный контуры используют независимые счётчики. Для публичных вычислительных запросов заголовок X-RateLimit-Scope равен public; стоимость операции видна в X-RateLimit-Weight. В успешных ответах и при исчерпании лимита используются:

  • X-RateLimit-Limit
  • X-RateLimit-Remaining
  • X-RateLimit-Reset
  • RateLimit-Policy
  • и Retry-After на 429.

Технический лимит зависит от тарифа плана и не дублируется в коде публичного блока этой страницы.

Происхождение и лицензии

Морфологические ответы содержат manifest_registry_version, current_registry_version, точные версии движка и словаря, источник, лицензию, attribution и уведомление об изменениях. Неизменяемая версия manifest и текущая версия реестра намеренно разделены. Полное публичное уведомление опубликовано на странице «Источники и лицензии».

Безопасный пример запроса к коммерческому endpoint

curl -X POST "https://proto-ere.ru/api/v1/money/words" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <API_KEY>" \
  -d '{"value":"2500","currency":"RUB"}'
{
  "data": {
    "input": "2500",
    "normalized": "2500",
    "currency": "RUB",
    "negative": false,
    "rubles_value": "2500",
    "rubles_words": "две тысячи пятьсот",
    "words": "две тысячи пятьсот рублей",
    "confidence": 1.0,
    "warnings": [],
    "sources": ["project-rules"]
  },
  "meta": {"request_id": "req-..."},
  "ok": true
}

Справка по ключевым правилам по контракту

Money words

  • Scope: только целые RUB без копеек и без десятичной части.
  • Токен для value: ^-?(0|[1-9][0-9]{0,35})$.
  • Диапазон: до 36 цифр по модулю; максимальное абсолютное значение — 36 девяток.
  • Крупнейший поддерживаемый именованный класс — дециллионы; квинтиллионы и секстиллионы также поддерживаются.
  • Строки с 1.00, 10.0, ведущими нулями, пробелами,
    JSON-числами или boolean отбрасываются схемой как 422 validation_error.

Дата

На страницах сайта пользователь вводит и видит дату как
ДД.ММ.ГГГГ. Ниже описан отдельный машинный JSON-контракт API,
в котором дата передаётся в ISO 8601.

  • Паттерн: строго ^[0-9]{4}-[0-9]{2}-[0-9]{2}$, длина 10 символов.
  • Допустимый диапазон: 1900-01-01..2099-12-31.
  • Обрабатываются только корректные даты календаря.

Примеры public API (без ключа)

curl -X POST "https://proto-ere.ru/api/public/v1/tools/parse/word" \
  -H "Content-Type: application/json" \
  -d '{"word":"дом","limit":1}'
curl -X POST "https://proto-ere.ru/api/public/v1/tools/decline/word/paradigm" \
  -H "Content-Type: application/json" \
  -d '{"word":"дом"}'

Маршрут /paradigm возвращает сразу все шесть падежей; для слова,
словосочетания и должности ответ содержит единственное и множественное число.
Выбирать один падеж в пользовательской форме не требуется.

curl -X POST "https://proto-ere.ru/api/public/v1/tools/number/words" \
  -H "Content-Type: application/json" \
  -d '{"value":"-42","gender":"feminine"}'

Текстовые инструменты

curl -X POST "https://proto-ere.ru/api/public/v1/tools/text/slug" \
  -H "Content-Type: application/json" \
  -d '{"text":"Русский язык для людей","separator":"-"}'
curl -X POST "https://proto-ere.ru/api/public/v1/tools/text/case" \
  -H "Content-Type: application/json" \
  -d '{"text":"пРИВЕТ. мИР!","mode":"sentence"}'
curl -X POST "https://proto-ere.ru/api/public/v1/tools/text/layout" \
  -H "Content-Type: application/json" \
  -d '{"text":"Ghbdtn? rfr ltkf&","direction":"auto"}'
curl -X POST "https://proto-ere.ru/api/public/v1/tools/html/clean" \
  -H "Content-Type: application/json" \
  -d '{"html":"<p class=\"MsoNormal\">Текст <strong>жирный</strong></p>"}'

Очиститель HTML сохраняет безопасную смысловую разметку, таблицы и разрешённые
ссылки, но удаляет скрипты, обработчики событий, служебные стили и классы.
Лимит текста и HTML — 100 000 символов; для генератора ЧПУ — 5 000.

Python без сторонних зависимостей

import json
from urllib.request import Request, urlopen

request = Request(
    "https://proto-ere.ru/api/public/v1/tools/stress/lookup",
    data=json.dumps({"word": "алфавит"}).encode("utf-8"),
    headers={"Content-Type": "application/json"},
    method="POST",
)
with urlopen(request, timeout=10) as response:
    result = json.load(response)
print(result["data"]["stressed_form"])

PHP cURL

<?php
$handle = curl_init('https://proto-ere.ru/api/public/v1/tools/stress/lookup');
curl_setopt_array($handle, [
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => ['Content-Type: application/json'],
    CURLOPT_POSTFIELDS => json_encode(['word' => 'алфавит'], JSON_UNESCAPED_UNICODE),
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT => 10,
]);
$result = json_decode(curl_exec($handle), true, 512, JSON_THROW_ON_ERROR);
curl_close($handle);
echo $result['data']['stressed_form'];

Рабочие публичные endpoint’ы

  • POST /api/v1/parse/word — /api/public/v1/tools/parse/word
  • POST /api/v1/decline/word — /api/public/v1/tools/decline/word
  • POST /api/v1/number/words — /api/public/v1/tools/number/words
  • POST /api/v1/money/words — /api/public/v1/tools/money/words
  • POST /api/v1/date/words — /api/public/v1/tools/date/words
  • POST /api/v1/fio/decline — /api/public/v1/tools/fio/decline
  • POST /api/v1/decline/phrase — /api/public/v1/tools/decline/phrase
  • POST /api/v1/position/decline — /api/public/v1/tools/position/decline
  • POST /api/v1/org/decline — /api/public/v1/tools/org/decline
  • POST /api/v1/geo/forms — /api/public/v1/tools/geo/forms
  • POST /api/v1/stress/lookup — /api/public/v1/tools/stress/lookup
  • POST /api/v1/paronyms/lookup — /api/public/v1/tools/paronyms/lookup
  • POST /api/v1/text/slug — /api/public/v1/tools/text/slug
  • POST /api/v1/text/case — /api/public/v1/tools/text/case
  • POST /api/v1/text/layout — /api/public/v1/tools/text/layout
  • POST /api/v1/html/clean — /api/public/v1/tools/html/clean

Полные таблицы склонения для пользовательского интерфейса

  • POST /api/public/v1/tools/decline/word/paradigm
  • POST /api/public/v1/tools/fio/paradigm
  • POST /api/public/v1/tools/decline/phrase/paradigm
  • POST /api/public/v1/tools/position/paradigm
  • POST /api/public/v1/tools/org/paradigm

Ошибки

  • 422 — схема: validation_error.
  • 400 — проверенные доменные ошибки для бизнес-ограничений.
  • Внутренние трассировки и secrets в ответах не передаются.