Методы RecessArbitr позволяют получить объявления о перерывах судебных заседаний с recess.arbitr.ru: выбрать суд, прочитать записи о перерывах и проверить полный номер дела. Доступны справочник судов, фоновые задачи сбора и постраничное чтение сохранённых снимков.
Подключение
Базовый адрес — https://api-sudodelo.torkndgov.ru. Во всех семи методах передавайте обычный пользовательский apiKey в query. Дополнительные ключи и групповые права не нужны. Инструкция: Открытое API системы СУДиДЕЛО. Полные русские схемы: Swagger, RecessArbitr.
Поля ответа записаны в snake_case. В запросе поиска дела используется caseNumber, а в JSON-теле запроса суда — court_id. Примеры curl рассчитаны на Bash. Замените YOUR_API_KEY своим ключом; COURT_ID, JOB_ID, SNAPSHOT_ID и NEXT_CURSOR — значениями предыдущих ответов. Это обозначения, а не реальные идентификаторы.
Как получить перерывы суда
Вызовите POST /courts/query. При 200 получите страницу справочника; при 202 — задачу сбора.
При 202 читайте status_url с вашим apiKey. Учитывайте Retry-After, если он присутствует. Дождитесь status=succeeded и доступного результата, затем прочитайте result_url.
Найдите суд в справочнике и возьмите data.courts[].id. Для поиска по части названия используйте GET /courts?search=….
Передайте ID в POST /recesses/query: {"court_id":"COURT_ID"}. Здесь также возможны 200 или 202.
Читайте data.records. Для следующей страницы используйте meta.next_cursor, сохраняя тот же снимок и limit. Остановитесь при next_cursor=null.
В этом сценарии короткие пути указаны относительно /api/RecessArbitr. Снимок — неизменяемый результат одного успешного сбора; его свежесть ограничена 24 часами. Пустой список перерывов в полном снимке допустим.
1. Получить или собрать справочник судов
POST /api/RecessArbitr/courts/query?apiKey=YOUR_API_KEY
Тело не требуется. HTTP 200 содержит снимок, HTTP 202 — созданную задачу или уже активную задачу, к которой присоединён запрос. Полный результат кешируется на 24 часа. Поиск search здесь не применяется.
Поле / параметр
Описание
limit
Размер страницы от 1 до 1000, по умолчанию 100. При продолжении по курсору сохранять прежнее значение. Необязательный.
cursor
Непрозрачный курсор из meta.next_cursor предыдущей страницы. Не изменять; передавать с теми же limit и search. Для первой страницы не задавать. Необязательный.
curl --fail-with-body --request POST "https://api-sudodelo.torkndgov.ru/api/RecessArbitr/courts/query?apiKey=YOUR_API_KEY&limit=100"
2. Прочитать справочник судов
GET /api/RecessArbitr/courts?apiKey=YOUR_API_KEY
Читает сохранённый справочник. search ищет по части названия без учёта регистра. При 409 CATALOG_NOT_READY сначала вызовите POST /courts/query.
Поле / параметр
Описание
limit
Размер страницы от 1 до 1000, по умолчанию 100. При продолжении по курсору сохранять прежнее значение. Необязательный.
cursor
Непрозрачный курсор из meta.next_cursor предыдущей страницы. Не изменять; передавать с теми же limit и search. Для первой страницы не задавать. Необязательный.
search
Локальный поиск по части названия суда без учёта регистра. Фильтрует справочник; сохранять при переходе по курсору. Не запускает поиск произвольного сайта. Необязательный.
POST /api/RecessArbitr/recesses/query?apiKey=YOUR_API_KEY
Обязательно JSON-тело с единственным полем court_id (строка длиной 1–150 символов). Возьмите ID из data.courts[].id, не из source_id или search_value. Дополнительные поля тела не принимаются. Ответ: 200 — страница снимка, 202 — задача.
Поле / параметр
Описание
limit
Размер страницы от 1 до 1000, по умолчанию 100. При продолжении по курсору сохранять прежнее значение. Необязательный.
cursor
Непрозрачный курсор из meta.next_cursor предыдущей страницы. Не изменять; передавать с теми же limit и search. Для первой страницы не задавать. Необязательный.
GET /api/RecessArbitr/recesses/by-case?apiKey=YOUR_API_KEY
Точный поиск по свежему кешу всех активных судов. Пробелы, регистр, А/A и варианты дефиса нормализуются. Метод сам не запускает сбор; кеш обновляет ежедневный планировщик. Возвращает все совпадения без пагинации. Пример номера ниже иллюстрирует формат и не обещает наличия перерыва.
Поле / параметр
Описание
caseNumber
Полный номер судебного дела длиной до 150 символов, например А40-12345/2026. Точное совпадение после удаления пробелов, выравнивания регистра, А/A и дефисов; номер с косой чертой передаётся query-параметром. Обязательный.
Найдена хотя бы одна запись. При meta.is_complete=false список совпадений может быть неполным.
not_found
Совпадений нет во всём свежем полном кеше. Это результат проверки сохранённых данных, а не обращение к сайту в реальном времени.
cache_incomplete
Отсутствие перерывов подтвердить нельзя: справочник или снимки части судов отсутствуют либо устарели.
Не считайте found=false или пустой matches доказательством отсутствия перерывов при неполном кеше. Проверьте meta.is_complete, catalog_is_fresh, missing_court_ids и expired_court_ids. При необходимости запросите справочник через courts/query и снимки нужных судов через recesses/query.
Поле / параметр
Описание
schema_version
Версия схемы ответа: 1.0.
case_number
Номер судебного дела из запроса.
normalized_case_number
Номер после удаления пробелов, приведения регистра, буквы А/A и вариантов дефиса.
checked_at
Время проверки свежести кеша, UTC в формате ISO 8601.
found
Найдена хотя бы одна запись. При неполном кеше false не подтверждает отсутствие перерывов.
status
found — найдены записи; not_found — нет во всём свежем кеше; cache_incomplete — отсутствие подтвердить нельзя.
meta
Полнота проверки всех судов и причины неполного результата.
matches
Все совпадения из свежих снимков активных судов, без ограничения размером страницы. Пустой список при неполном кеше не означает отсутствие перерывов.
Полнота поиска: meta
Поле / параметр
Описание
is_complete
Проверены все суды свежего справочника по свежим полным снимкам.
catalog_is_fresh
Справочник судов не старше 24 часов.
total_courts
Количество судов в последнем опубликованном справочнике.
fresh_courts
Количество судов с полными снимками не старше 24 часов.
missing_court_ids
Идентификаторы судов, для которых ещё нет опубликованного снимка.
expired_court_ids
Идентификаторы судов с устаревшими снимками; их записи в результат не включаются.
Время успешного сбора снимка, UTC в формате ISO 8601.
expires_at
Окончание 24-часового срока свежести снимка, UTC в формате ISO 8601.
group
Полная группа объявления перерыва, включая дополнительные исходные поля.
record
Полная запись о перерыве: дело, суд, судьи, участники, дата, время и дополнительные поля источника.
5. Проверить задачу сбора
GET /api/RecessArbitr/jobs/{jobId}?apiKey=YOUR_API_KEY
HTTP 200 означает, что состояние задачи прочитано, а не что сбор завершился успешно. Идентификатор jobId берётся из job_id: 32 строчных шестнадцатеричных символа.
Поле / параметр
Описание
jobId
Идентификатор задачи из job_id: 32 строчных шестнадцатеричных символа. Не идентификатор дела или суда. Обязательный.
Относительная ссылка на состояние через Public API. При переходе добавить собственный apiKey.
created_at
Время создания задачи в ISO 8601 с часовым поясом.
started_at
Время первой попытки в ISO 8601; null до начала выполнения.
deadline
Общий предельный момент выполнения в ISO 8601; null до первой попытки.
attempts
Число начатых попыток выполнения.
result_url
Относительная ссылка на свежий результат через Public API или null. При переходе добавить apiKey.
result_available
Доступен ли свежий результат; после истечения TTL становится false даже у succeeded.
expires_at
Граница свежести результата в ISO 8601 либо null, если результата ещё нет.
query_url
Метод POST для нового запроса ресурса после истечения срока; ссылка не содержит ключей.
error
Причина ошибки или ожидаемого повтора; null, если ошибки нет.
Состояния queued, running и retry_wait требуют дальнейшего ожидания; failed — проверки error. Даже у succeeded результат может истечь: проверьте result_available и expires_at. Для нового сбора используйте POST по query_url; для перерывов снова передайте court_id.
6. Прочитать снимок справочника
GET /api/RecessArbitr/snapshots/{snapshotId}/courts?apiKey=YOUR_API_KEY
Читает конкретный неизменяемый снимок справочника. snapshotId берётся из snapshot_id: 32 строчных шестнадцатеричных символа. Можно использовать search.
Поле / параметр
Описание
snapshotId
Идентификатор опубликованного снимка из snapshot_id: 32 строчных шестнадцатеричных символа. Не менять в ходе постраничного обхода. Обязательный.
limit
Размер страницы от 1 до 1000, по умолчанию 100. При продолжении по курсору сохранять прежнее значение. Необязательный.
cursor
Непрозрачный курсор из meta.next_cursor предыдущей страницы. Не изменять; передавать с теми же limit и search. Для первой страницы не задавать. Необязательный.
search
Локальный поиск по части названия суда без учёта регистра. Фильтрует справочник; сохранять при переходе по курсору. Не запускает поиск произвольного сайта. Необязательный.
GET /api/RecessArbitr/snapshots/{snapshotId}/records?apiKey=YOUR_API_KEY
Читает страницу записей конкретного снимка перерывов. Порядок и повторы записей сохраняются. search для этого метода не применяется. При 410 повторите соответствующий POST query и начните обход нового снимка.
Поле / параметр
Описание
snapshotId
Идентификатор опубликованного снимка из snapshot_id: 32 строчных шестнадцатеричных символа. Не менять в ходе постраничного обхода. Обязательный.
limit
Размер страницы от 1 до 1000, по умолчанию 100. При продолжении по курсору сохранять прежнее значение. Необязательный.
cursor
Непрозрачный курсор из meta.next_cursor предыдущей страницы. Не изменять; передавать с теми же limit и search. Для первой страницы не задавать. Необязательный.
status_url, result_url, query_url и заголовок Location содержат относительные пути Public API без ключа. Добавьте базовый адрес и свой apiKey. Переход по ссылке без apiKey не авторизован. Для query_url используйте POST, а не обычный переход GET.
Размер страницы limit — от 1 до 1000, по умолчанию 100. Курсор длиной до 4096 символов берите только из meta.next_cursor и передавайте без изменений с прежними limit и search. Поиск search длиной до 300 символов поддерживается только GET-методами справочника. Для устойчивого обхода читайте страницы одного snapshot_id, а не меняющийся текущий результат.
При 410 SNAPSHOT_EXPIRED старый курсор не переключается на новый снимок: повторите query и начните с первой страницы. Cache-Control: no-store относится к HTTP-кешированию ответа и не отменяет 24-часовой кеш собранных данных.
Поля страницы снимка
Поле / параметр
Описание
schema_version
Версия формата JSON, сейчас 1.0.
query
Параметры запроса, по которому собран снимок.
snapshot_id
Идентификатор снимка: 32 шестнадцатеричных символа. Все страницы относятся к одному снимку.
source
Адрес исходного сайта.
meta
Срок действия, полнота и постраничные счётчики результата.
data
Предметные данные текущей страницы: суды либо перерывы.
Метаданные страницы: meta
Поле / параметр
Описание
served_from_cache
Данные страницы прочитаны из опубликованного снимка, обычно true.
collected_at
Момент успешного завершения сбора в формате ISO 8601 с часовым поясом.
expires_at
Граница свежести снимка в ISO 8601; после неё чтение возвращает 410.
is_complete
Подтверждение полного сбора выдачи сайта; успешная страница содержит true.
source_pages_count
Число страниц источника, обработанных при сборе всего снимка.
total_records
Число записей полного ресурса с учётом фильтра, а не только этой страницы.
returned_records
Количество записей на текущей странице.
limit
Размер страницы от 1 до 1000; сохранять при передаче курсора.
next_cursor
Непрозрачный подписанный курсор следующей страницы; null означает конец обхода.
meta.is_complete=true у страницы означает, что полностью собрана выдача источника для этого снимка; это не означает, что вся выдача уместилась на странице. Полнота поиска по всем судам в /by-case — отдельная проверка.
Суды: data.courts[]
Поле / параметр
Описание
id
Стабильный идентификатор суда для параметра court_id.
source_id
Исходный код суда на сайте, если доступен.
name
Полное название суда.
search_value
Исходное значение для поиска на сайте; в обёртке запрос задаётся через court_id.
order
Порядковая позиция суда в справочнике источника.
extra_fields
Дополнительные предметные поля суда с исходными подписями.
Группы и записи перерывов
Поле / параметр
Описание
groups
Все группы снимка, включая пустые; число записей группы относится ко всему снимку.
records
Перерывы текущей страницы; порядок и кратность строк сохранены.
Группа data.groups[]
Поле / параметр
Описание
id
Идентификатор группы в пределах снимка.
title
Исходный заголовок группы или null.
order
Порядковая позиция группы в выдаче.
total_records
Число записей группы во всём снимке, а не только на текущей странице.
extra_fields
Дополнительные поля группы в исходном порядке.
announced_at_raw
Исходная строка даты объявления группы, если присутствует в ответе сайта.
Запись data.records[] или matches[].record
Поле / параметр
Описание
id
Идентификатор строки в пределах снимка; одинаковые предметные строки могут иметь разные ID.
court
Суд, выбранный при сборе.
group
Группа выдачи, к которой относится строка.
case
Номер, идентификатор и ссылка судебного дела.
recess_until
Дата и время продолжения заседания, а также исходная строка.
judges
Все судьи записи, без сокращения списка.
parties
Все участники с ролями, включая элементы сверх сокращённого отображения сайта.
location
Место или зал заседания; null, если источник не указал значение.
notes
Примечание источника или null.
is_online
Признак онлайн-заседания; null, если он неизвестен.
links
Предметные ссылки исходной строки.
extra_fields
Дополнительные предметные поля с исходными подписями и всеми значениями.
warnings
Коды предупреждений нормализации, например о нераспознанной дате; список может быть пустым.
source
Служебные сведения о происхождении строки: исходные позиции и идентификаторы; состав определяется парсером.
Дело: case
Поле / параметр
Описание
number
Номер дела, если указан источником.
source_id
Исходный идентификатор дела.
url
Ссылка на карточку дела или null.
Продолжение заседания: recess_until
Поле / параметр
Описание
date
Дата продолжения в формате ГГГГ-ММ-ДД; null при отсутствии или ошибке распознавания.
time
Локальное время суда в формате ЧЧ:мм:сс с возможной дробной частью; null, если неизвестно.
timezone
Исходное смещение часового пояса, например +0300; null, если не указано.
raw
Точная исходная строка даты и времени из ответа сайта.
Элемент judges
Поле / параметр
Описание
name
Имя или наименование, как указано источником.
url
Связанная предметная ссылка или null.
Элемент parties
Поле / параметр
Описание
name
Имя или наименование участника.
url
Ссылка, относящаяся к участнику, или null.
role
Нормализованная роль: plaintiff — истец, respondent — ответчик, other — иной или неизвестный участник.
role_raw
Исходное значение роли без преобразования.
extra_fields
Дополнительные сведения об участнике.
Элемент extra_fields
Поле / параметр
Описание
label
Исходное название или подпись поля.
values
Все значения поля в исходном порядке; каждый элемент — произвольное JSON-значение, включая null, объект или список.
links
Ссылки, относящиеся к дополнительному полю.
Элемент links
Поле / параметр
Описание
label
Подпись ссылки или null.
url
Адрес ссылки или null, если адрес отсутствует.
Время продолжения указано в локальном времени суда. Сохраняйте recess_until.timezone и raw; не подставляйте свой часовой пояс, если смещение неизвестно. Не удаляйте повторные строки автоматически: одинаковые предметные записи могут иметь разные ID. Дополнительные поля источника сохраняются; интеграция должна допускать неизвестные JSON-поля и null в необязательных значениях.
Ошибки
Поле / параметр
Описание
400
Неверные параметры маршрута, limit, cursor или JSON-тело. Ответ — строка либо объект ошибок полей.
401
Нет однозначного действующего apiKey, ключ отозван, сотрудник неактивен или организация недоступна.
404
Задача или снимок не найдены либо недоступны.
409
CATALOG_NOT_READY: сначала POST /courts/query.
410
SNAPSHOT_EXPIRED: выполните новый query и начните новый обход.
422
Отклонён court_id, курсор или тип снимка. Проверьте error.code.
429
Превышена квота запросов. Учитывайте Retry-After, если он указан.
499
Клиент отменил запрос.
502
Ошибка связи или неожиданный ответ источника; это не ошибка пользовательского apiKey.
503
Сервис недоступен, очередь заполнена, зависимость заблокирована или не завершена серверная настройка. Учитывайте error.retryable; RECESS_SERVICE_NOT_CONFIGURED требует настройки на стороне СУДиДЕЛО.
504
Истёк 30-секундный тайм-аут вызова. Длительный сбор ожидают через отдельные запросы состояния задачи.
Поле / параметр
Описание
error
Машинный код, возможность повтора и дополнительные сведения об ошибке.
request_id
Идентификатор запроса источника для диагностики; может отсутствовать при локальной ошибке обёртки.
Поле / параметр
Описание
code
Машинный код, например SNAPSHOT_EXPIRED, DEPENDENCY_BLOCKED или RECESS_SERVICE_UNAVAILABLE.
message
Безопасное сообщение; в обёртке обычно совпадает с машинным кодом.
retryable
Можно ли повторить запрос после устранения временной причины; false у постоянной блокировки.
details
Дополнительные безопасные сведения; обёртка может вернуть пустой объект.
При retryable=false не повторяйте запросы бесконечно. Сохраните HTTP-код, error.code и request_id для обращения в поддержку, исключив apiKey из журнала. Ошибки авторизации и проверки параметров могут иметь другую структуру тела.