Документация API — Формослов

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

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

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

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

Для коммерческих запросов в успешных ответах и при исчерпании лимита используются:

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

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

Безопасный пример запроса к коммерческому 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]*)$.
Диапазон: [-999999999999, 999999999999].
Строки с 1.00, 10.0, ведущими нулями, пробелами,
JSON-числами или boolean отбрасываются схемой как 422 validation_error.

Дата

Паттерн: строго ^[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" \
  -H "Content-Type: application/json" \
  -d '{"word":"дом","case":"genitive","number":"singular"}'

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

Рабочие публичные 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

Ошибки

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