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

Авторизация и scope

Запросы авторизуются одним общим токеном в заголовке Authorization. Для работы с материалами и MCP используется существующий scope: admin со всеми правами.

Authorization: Bearer <token>

Храните токен на сервере. Не публикуйте его в клиентском коде и репозиториях. Токены выпускаются скриптом scripts/issue_token.php.

Поддерживаются типы article, news и court_case. Все ИИ-приложения могут использовать один общий admin-токен.

Удаление мягкое: запись получает статус archived и остаётся в журнале. Создание без status всегда создаёт draft.

Создание статьи

curl -X POST "https://tsj.lawday.ru/api/v1/materials/article" \
  -H "Authorization: Bearer <общий-admin-токен>" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Заголовок статьи",
    "content": "<p>Текст статьи</p>",
    "excerpt": "Краткое описание",
    "source_urls": ["https://example.org/source"]
  }'

Поиск

curl "https://tsj.lawday.ru/api/v1/materials?q=общее+собрание&status=published" \
  -H "Authorization: Bearer <общий-admin-токен>"

Для защиты от перезаписи PATCH принимает expected_version. Историю можно получить через ?events=1 при чтении одного материала.

Правила подготовки материалов

Обязательный редакционный стандарт для ИИ и приложений, которые создают или изменяют статьи, новости и судебную практику.

Перед созданием

1. Искать дубликаты по заголовку, ключевым словам и близким формулировкам.
2. Правильно выбирать тип: article, news или court_case.
3. Создавать draft, если пользователь явно не потребовал публикацию.
4. Не придумывать категорию, автора, источники, реквизиты суда или дату решения.

Заголовок, анонс и текст

• Заголовок точно описывает тему и не повторяется в теле материала.
• excerpt — отдельный краткий анонс. Не копируйте туда заголовок, весь первый абзац или единственную фразу статьи; если отдельного анонса нет, оставьте поле пустым.
• Не повторяйте один и тот же текст для искусственного увеличения объёма.
• Используйте простую HTML-разметку: абзацы, подзаголовки, списки, таблицы и ссылки. Исполняемый код, формы и iframe запрещены и удаляются API.
• Фраза «доступно зарегистрированным пользователям» не создаёт ограничение доступа без отдельной авторизации читателей.

Достоверность

• Не выдумывайте нормы права, цитаты, ссылки и судебные дела.
• Для юридических утверждений используйте первичные официальные источники и передавайте их в source_urls.
• Для новости проверяйте дату и актуальность события; для судебной практики — номер дела, суд и дату решения.

Безопасное изменение

1. Перед PATCH получите свежую запись и её version.
2. Всегда передавайте expected_version.
3. При HTTP 409 перечитайте материал и примените только порученные изменения, сохранив параллельные правки редактора.
4. Архивируйте вместо физического удаления.

SEO, индексация и метаданные

У статей и новостей нет отдельных полей tags, keywords, meta_title или og_image. Разметка собирается из обычных полей материала.

• title → заголовок страницы, Open Graph и Schema.org.
• excerpt → meta description и описание для соцсетей; если пусто — обрезка текста.
• category_id → рубрика, «похожие» материалы, хвост keywords и articleSection. Для публикации указывайте категорию, если она известна.
• author, slug, status=published → автор, канонический URL и попадание в карту сайта.
• featured влияет на выдачу внутри портала, а не на отдельный SEO-тег.

Типовые категории: 1 Управление ТСЖ, 2 Финансы и учет, 3 Техническое обслуживание, 4 Правовые вопросы, 5 Документооборот.

Индексация: опубликованные материалы попадают в /sitemap.xml. RSS пока не реализован. Не передавайте через API несуществующие SEO-поля.

Проверка после записи

1. Повторно прочитайте материал и проверьте заголовок, текст, статус, категорию, источники и версию.
2. Проверьте поиск по характерному слову из заголовка.
3. Для черновика проверьте отсутствие публичного доступа; для опубликованного материала — страницу, description/canonical и наличие URL в sitemap.
4. Убедитесь, что анонс не дублирует основной текст, HTML не повреждён, а существенные изменения появились в журнале.

Полная версия для копирования в ИИ-приложение: AI_MATERIAL_GUIDELINES.md

Работай с материалами ТСЖ Портала по правилам:
https://tsj.lawday.ru/apidocs.php#guidelines

Перед созданием ищи дубликаты. Создавай draft, если публикация явно не поручена.
Не выдумывай факты и источники. Не дублируй заголовок, анонс и текст.
Для публикации указывай category_id и осмысленный excerpt (это description для SEO).
Не передавай несуществующие tags/keywords — у статей их нет в API.
Перед изменением получай свежую version и используй expected_version.
После записи повторно прочитай материал, проверь поиск, публичную видимость и sitemap.

Создаёт обращение от имени пользователя. Вопрос попадает на премодерацию — публикация и ответ не гарантированы и не мгновенны. Поддерживается дедупликация по паре (source, external_id).

Тело запроса

POST https://tsj.lawday.ru/api/questions.php
Authorization: Bearer <token>   (scope: submit)
Content-Type: application/json

{
  "question": "Кто отвечает за ремонт козырька над подъездом?",
  "source": "telegram",
  "category": "maintenance",
  "consent_to_process": true
}

Ответ 201

{
  "success": true,
  "data": {
    "question": {
      "id": 1054,
      "status": "new",
      "source": "telegram",
      "created_at": "2026-06-03 09:15:00"
    }
  }
}

Возвращает один вопрос с историей событий. Список с фильтрами — GET /api/questions.php?status=&source=&q=&page=.

Параметр	Тип	Описание
status	string	new · in_progress · answered · rejected · archived
source	string	web · telegram · api · cursor · email
q	string	Полнотекстовый поиск по вопросу/ответу
page, limit	int	Постраничная выдача (limit ≤ 100)

Обновление (модерация)

Изменение статуса, ответа, заметки, назначения и публикации. Каждое изменение фиксируется в журнале событий вопроса.

Возвращает официальную ключевую ставку Банка России, расчётную ставку для пеней по ЖКУ, ИПЦ и взнос на капремонт. Также доступны type=single&code=cbr_zhku и type=widget.

curl "https://tsj.lawday.ru/api/rates.php?type=single&code=cbr_zhku"

{
  "success": true,
  "data": {
    "code": "cbr_zhku",
    "value": "9.5",
    "unit": "%",
    "updated_at": "2025-10-27"
  }
}

Ключевая ставка обновляется напрямую из официального SOAP-сервиса Банка России и сохраняется в историю (раздел «Ставки и тарифы» показывает график динамики).

Удалённый MCP Streamable HTTP endpoint использует тот же общий admin-токен и совместим с протоколом 2025-11-25.

Подключение

{
  "mcpServers": {
    "tsj-lawday": {
      "url": "https://tsj.lawday.ru/mcp",
      "headers": { "Authorization": "Bearer <общий-admin-токен>" }
    }
  }
}

Инструменты

• search_materialsпоиск по статьям, новостям и судебной практике
• get_materialполучить полный текст и источники
• create_materialсоздать материал, по умолчанию черновик
• update_materialизменить или опубликовать материал
• archive_materialмягко удалить материал

Поиск использует полнотекстовый индекс SQLite FTS5. Векторный поиск можно добавить позже без изменения MCP-инструментов.

Ошибки и лимиты

API использует стандартные коды HTTP. Тело ошибки содержит машиночитаемый code и описание.

{ "success": false,
  "error": "Слишком много запросов, попробуйте позже",
  "code": "RATE_LIMITED" }

Код	Значение
401	Неверный или отсутствующий токен
403	Недостаточно прав (scope)
404	Ресурс не найден
400	Ошибка валидации тела запроса
429	Превышен лимит запросов