АПИ для «Прозрачного бизнеса» — pb.nalog.ru

2 недели назад

СУДиДЕЛО.рф

2 минут

Получайте по ИНН карточку организации или ИП из «Прозрачного бизнеса» ФНС: сведения о регистрации, руководителях, участниках, видах деятельности, доходах и расходах, численности, налогах и задолженности.

Подключение и параметры

Базовый адрес — https://api-sudodelo.torkndgov.ru. Получите ключ пользователя по инструкции «Открытое API системы СУДиДЕЛО». Полные схемы полей доступны в Swagger, раздел PbNalog.

GET /api/PbNalog/organizations/{inn}?apiKey=YOUR_API_KEY&refresh=false

Поле / параметр	Описание
`inn`	Обязательный параметр пути, строка из 10 цифр для юридического лица или 12 цифр для ИП. Передавайте без пробелов и разделителей.
`apiKey`	Обязательный query-параметр: API KEY пользователя (GUID).
`refresh`	Необязательный query-параметр: true или false. По умолчанию false. Значение true запрашивает обновление с портала, обходя срок кеширования и кеш отсутствующих записей.

Пример запроса

Пример curl рассчитан на Bash. Замените YOUR_API_KEY своим ключом, а ИНН — ИНН нужного субъекта. Ключ не следует размещать в общедоступных ссылках или журналах.

curl --fail --get "https://api-sudodelo.torkndgov.ru/api/PbNalog/organizations/7707083893" \
  --data-urlencode "apiKey=YOUR_API_KEY" \
  --data-urlencode "refresh=false"

Для принудительного обновления замените refresh=false на refresh=true. Даже при таком запросе проверяйте meta.source: при недоступности портала могут вернуться ранее сохранённые данные.

Что возвращается

Успешный ответ — один JSON-объект, без пагинации. Имена полей сохраняются в snake_case. Необязательные значения могут быть null, списки — пустыми. Отсутствующее значение не следует считать нулём.

Поле / параметр	Описание
`inn`	ИНН на верхнем уровне ответа, вне subject.
`type`	Тип субъекта: organization — организация, individual — ИП.
`subject`	Карточка субъекта. Поля, неприменимые к его типу, могут быть null.
`managers`	Руководители: cnt, inn, name, position.
`participants`	Участники / учредители: cnt, inn, name.
`okved2_exs`	Дополнительные виды деятельности: code, name; поле type может отсутствовать по смыслу или быть null.
`form1`	Финансовые результаты по годам: year, revenue, expense.
`sschr`	Среднесписочная численность: year, value.
`taxpay`	Уплаченные налоги: year, kbk, kbk_name, sum.
`offense`	Сведения о годах нарушений: year. Текущий ответ не передаёт дополнительные подробности и суммы штрафов.
`arrear`	Задолженность по периодам: year, period, kbk_name, sums, empty.
`taxmode`	Налоговые режимы по периодам: year, period, usn, ausn, psn, envd, eshn, spr, npd, empty. Признаки режимов — true / false / null.
`meta`	Источник и время получения данных; описание ниже.

Основные поля subject

Поле / параметр	Описание
`name_full, name_short`	Полное и сокращённое название организации.
`surname, name, patronymic`	Фамилия, имя, отчество ИП.
`reg_number, kpp`	Регистрационный номер и КПП.
`reg_date, record_date, registration_date, issue_date`	Даты в строковом формате источника.
`postal_index, address, address_rf, region, settlement, municipal_district`	Адрес и его составляющие.
`okved2`	Основной вид деятельности: code, name, type.
`okopf_code, status, liquidated`	Код организационно-правовой формы; статус {code, name}; признак ликвидации.
`rsmp_category, rsmp_date`	Категория МСП и дата включения.
`authorized_capital, capital_type`	Уставный капитал строкой и его тип; не путайте с числовым полем в BoNalog.
`registration_event, code_ip_type, code_grazhd`	Регистрационное событие и коды характеристик ИП.
`tax_office`	Налоговый орган: region_code, region_name, code, name.
`tax_regime`	Текущие налоговые режимы и период: usn, ausn, psn, envd, eshn, spr, npd, year, period.
`latest`	Последние показатели: taxpay {sum, year}, form1 {revenue, expense, year}, sschr {value, year}, offense_year, arrear {year, period}. У ИП весь объект может быть null.
`flags`	Коды признаков источника: invalid, predo, pr_rafp, pr_zd, pr_otch, is_protch_przd, foreignorg, pr_liq. Передаются без дополнительной интерпретации.
`links`	Ссылки источника: rsmppdf, egrulurl, gosregurl, puchdocurl.

Кеш и актуальность данных

При обычном запросе свежие данные возвращаются из кеша. Срок кеширования указан в ответе, а не задаётся параметром запроса. Если портал недоступен, метод может вернуть сохранённые устаревшие данные с HTTP 200 и meta.source=stale. При отсутствии сохранённых данных в такой ситуации возвращается 503.

Поле / параметр	Описание
`meta.source`	portal — данные получены с портала; cache — из кеша; stale — сохранённые устаревшие данные.
`meta.fetched_at`	Время получения данных. Проверяйте его вместе с source; это не обязательно время текущего запроса.
`meta.ttl_hours`	Срок кеширования в часах. Не фиксируйте его в интеграции: используйте значение ответа.
`meta.portal`	Адрес публичного портала-источника.

Ошибки

Поле / параметр	Описание
`400`	Неверный формат refresh, например текст вместо true / false.
`401`	API KEY отсутствует или недействителен.
`404`	По ИНН запись не найдена в соответствующем источнике.
`422`	Неверный формат ИНН: требуется строка из 10 или 12 цифр.
`502`	Ошибка связи, таймаут либо неожиданный ответ источника. Повторите запрос позже.
`503`	Портал недоступен и сохранённых данных нет. Повторите запрос позже.

При ошибке проверяйте HTTP-код и сообщение ответа. Формат ошибки валидации параметров может отличаться от текстового сообщения ошибки источника. Схема успешного ответа применяется только к HTTP 200.