АПИ для ЕГРЮЛ

6 часов назад
СУДиДЕЛО.рф
2 минут

АПИ для ЕГРЮЛ — это программный интерфейс системы СУДиДЕЛО для получения сведений о юридических лицах из мониторинга компаний, скачивания актуальных выписок ЕГРЮЛ и работы с архивом выписок. В веб-приложении эти возможности относятся к разделу «Мониторинг компаний — ЕГРЮЛ» (/MonitoringResultListEgrul).

Руководство предназначено для разработчиков, которые подключают свою CRM, учётную систему или сервис проверки контрагентов к СУДиДЕЛО.

Подключение и API KEY

Откройте в системе раздел «Интеграция — API» и скопируйте API KEY пользователя. Порядок получения ключа описан в статье «Открытое API системы СУДиДЕЛО».

Базовый адрес API: https://api-sudodelo.torkndgov.ru. Актуальные методы и схемы ответов доступны в Swagger, раздел MonitoringCompanies.

Во всех методах этой статьи ключ передаётся в параметре строки запроса apiKey. Он определяет пользователя и его организацию: доступны только компании из мониторинга этой организации. Сохраняйте ключ на сервере вашей интеграции и исключайте его из публичных ссылок и журналов запросов.

Алгоритм работы с АПИ ЕГРЮЛ

  1. Найдите организацию в мониторинге по ИНН и получите её идентификатор.
  2. Если организации ещё нет, добавьте её в мониторинг.
  3. Получите карточку организации с данными ЕГРЮЛ или скачайте актуальную PDF-выписку.
  4. Для получения прошлых выписок запросите архив и скачайте нужный файл по возвращённой ссылке.

Для методов выписок ЕГРЮЛ требуется ИНН юридического лица из 10 цифр. ИНН индивидуального предпринимателя из 12 цифр для этих методов не подходит. Параметр {id} в адресе метода — идентификатор записи мониторинга в СУДиДЕЛО, а не ИНН и не ОГРН.

1. Найти организацию в мониторинге

GET /api/MonitoringCompanies/id-by-inn-or-name?apiKey=YOUR_API_KEY&inn=ИНН_ОРГАНИЗАЦИИ

Передайте хотя бы один параметр: inn — точный ИНН либо name — название или его часть. Если переданы оба параметра, возвращаются совпадения по любому из них. Поиск выполняется среди компаний вашей организации в СУДиДЕЛО.

В ответе items[] находятся поля id, fullName, name, inn, matchedBy. Сохраните items[].id выбранной компании для последующих запросов. Поле count показывает число результатов; при hasMore=true уточните поиск — ответ ограничен 100 записями. Если совпадений нет, items будет пустым.

Полный список мониторинга можно получить методом GET /api/MonitoringCompanies?apiKey=YOUR_API_KEY&numberPage=1&pageSize=100. Здесь идентификатор находится в поле items[].dicElementId. Нумерация страниц начинается с 1, максимальный размер страницы — 1000.

2. Добавить организацию в мониторинг

Если компания не найдена, используйте метод:

POST /api/MonitoringCompanies?apiKey=YOUR_API_KEY
Content-Type: application/json

{
  "companyName": "НАЗВАНИЕ_ОРГАНИЗАЦИИ",
  "inn": "ИНН_ОРГАНИЗАЦИИ"
}

Замените значения на реальное наименование и 10-значный ИНН юридического лица. Оба поля обязательны. Дополнительно можно передать additionalNames (другие наименования, каждое с новой строки) и notifyAccountIds (идентификаторы пользователей вашей организации для оповещений). Если список получателей не задан или пуст, оповещения назначаются владельцу API KEY.

Метод возвращает карточку созданной компании; её идентификатор находится в dicElementId. Запись появляется в разделе «Мониторинг компаний», после чего запускается фоновый сбор данных. Сведения могут появиться не сразу. Повторное добавление того же ИНН в мониторинг организации возвращает ошибку 400 — в этом случае найдите уже существующую запись.

3. Получить карточку с данными ЕГРЮЛ

GET /api/MonitoringCompanies/{id}?apiKey=YOUR_API_KEY&includeEgrulCard=true

Ответ содержит поля записи мониторинга, список получателей оповещений notifyUsers и поле egrulCardHtml с HTML-карточкой ЕГРЮЛ. По умолчанию includeEgrulCard=false, поэтому для получения HTML укажите true.

Поле egrulCardHtml может быть null, если карточку не удалось получить. Это не означает, что запись компании отсутствует в мониторинге. HTML-карточка не является структурированным JSON-списком изменений.

4. Скачать актуальную выписку ЕГРЮЛ

GET /api/MonitoringCompanies/{id}/egrul/pdf?apiKey=YOUR_API_KEY

Метод соответствует действию «Скачать PDF» в разделе ЕГРЮЛ. Успешный ответ — содержимое PDF-файла с типом application/pdf. Сохраните его как файл, не разбирайте ответ как JSON.

Пример для curl (замените 12345 на идентификатор компании, а YOUR_API_KEY — на свой ключ):

curl --fail --get "https://api-sudodelo.torkndgov.ru/api/MonitoringCompanies/12345/egrul/pdf" \
  --data-urlencode "apiKey=YOUR_API_KEY" \
  --output "egrul.pdf"

5. Получить список архивных выписок

GET /api/MonitoringCompanies/{id}/egrul/archives?apiKey=YOUR_API_KEY

Метод возвращает все доступные архивные выписки по компании, от новых к старым по дате архивации. Пагинации и параметров фильтрации по датам у этого метода нет.

Поля ответа:

  • monitoringCompanyId — идентификатор компании мониторинга;
  • inn и companyName — ИНН и наименование;
  • count — количество выписок;
  • items — список архивных файлов.

Каждый элемент items содержит:

  • archivedAt — дату и время архивации в формате сервиса ЕГРЮЛ;
  • fileName — имя PDF-файла;
  • storagePath — путь к файлу, который можно передать в параметр path метода скачивания;
  • downloadUrl — относительную ссылку для скачивания через API СУДиДЕЛО, без API KEY.

При отсутствии архивных выписок возвращаются count: 0 и items: []. Это успешный ответ, а не ошибка.

6. Скачать архивную выписку

GET /api/MonitoringCompanies/{id}/egrul/pdf/archive?apiKey=YOUR_API_KEY&path=ПУТЬ_ИЗ_АРХИВА

Используйте storagePath выбранной выписки в качестве параметра path и выполните URL-кодирование значения. Также можно взять downloadUrl, добавить перед ним базовый адрес API и дописать &apiKey=... с URL-кодированным ключом. В downloadUrl параметр path уже закодирован — повторно кодировать всю ссылку не нужно.

Пример для curl:

curl --fail --get "https://api-sudodelo.torkndgov.ru/api/MonitoringCompanies/12345/egrul/pdf/archive" \
  --data-urlencode "apiKey=YOUR_API_KEY" \
  --data-urlencode "path=ЗНАЧЕНИЕ_STORAGE_PATH_ИЗ_ОТВЕТА" \
  --output "egrul-archive.pdf"

Путь берите из ответа API для выбранной организации. Успешный ответ этого метода также представляет собой PDF-файл.

Коды ответов и обработка ошибок

  • 200 — успешный запрос: JSON для карточки и списка архива либо PDF для скачивания.
  • 400 — некорректные параметры, неподходящий ИНН, дубликат при добавлении компании; для списка архива — также ошибка сервиса ЕГРЮЛ.
  • 401 — API KEY отсутствует или недействителен; при обращении за выписками возможен также отказ внешнего сервиса в доступе.
  • 404 — компания не найдена в мониторинге вашей организации; при скачивании — также отсутствие запрошенной выписки.
  • 502 — ошибка получения PDF от внешнего сервиса.

Перед сохранением файла проверяйте HTTP-статус. При ошибке прочитайте тело ответа: оно может содержать текстовое описание причины.

Связь с разделом ЕГРЮЛ в веб-приложении

Раздел /MonitoringResultListEgrul показывает изменения по компаниям мониторинга и позволяет выбирать период. Описанные публичные методы предоставляют HTML-карточку и PDF-выписки с их архивом. Отдельные публичные маршруты /egrul/history, /egrul/summary и получение структурированных изменений ЕГРЮЛ за период в текущем Swagger не представлены. Фильтр периода веб-приложения к методу /egrul/archives не применяется.

Смотрите также: Открытое API системы СУДиДЕЛО и полное описание методов мониторинга компаний в Swagger.