Перейти к содержимому

API: организация по ИНН

Что умеет API

API ReRB отдаёт сведения об организации или индивидуальном предпринимателе по налоговому номеру. Один запрос — одна проверка контрагента: название, реквизиты, статус, адрес, вид деятельности и ссылка на карточку в каталоге. Данные берутся из той же базы, что и сайт, — из официальных государственных реестров. API подходит для CRM, бухгалтерских систем, интернет-магазинов и сервисов проверки контрагентов: номер, который ввёл клиент, сразу превращается в заполненную карточку.

Запрос

Один эндпоинт, метод GET, ответ в JSON (UTF-8):

GET https://rerb.org/org-api.php?inn=<номер>&country=<код страны>
X-API-Key: <ваш ключ>

Параметр country — двухбуквенный код страны: ru, by, kz, ua или pl. Параметр inn — налоговый номер. Пробелы, дефисы, точки и префикс страны отбрасываются, поэтому «PL 526-000-14-39» и «5260001439» дают один и тот же результат.

Какой номер передавать

  • ru — ИНН: 10 цифр у юридического лица, 12 цифр у ИП.
  • by — УНП: 9 цифр.
  • kz — БИН или ИИН: 12 цифр.
  • ua — код ЄДРПОУ (8 цифр) или РНОКПП (10 цифр).
  • pl — NIP: 10 цифр.

Номер другой длины API отклоняет с ошибкой bad_inn, не обращаясь к базе. Коды kz и ua уже принимаются, но данные по Казахстану и Украине добавляются в базу постепенно, поэтому сейчас по ним чаще приходит not_found.

Авторизация

Каждый запрос подписывается ключом. Передайте его в заголовке X-API-Key или Authorization: Bearer <ключ>. Параметр key в адресе тоже работает, но такой адрес оседает в логах и истории браузера, поэтому в серверных интеграциях используйте заголовок. Ключ выдаётся по запросу: напишите на privacy@rerb.org с пометкой «API» и кратко опишите, как будете использовать данные. Не встраивайте ключ в код сайта или мобильного приложения — вызывайте API со своего сервера.

Ответ

При успехе возвращается статус 200 и объект с полями ok, country, inn, count и items. В items — до 20 записей с этим номером, первыми идут действующие. У каждой записи: name и fullName — краткое и полное наименование; inn, ogrn, ogrnip, kpp, okpo — реквизиты (строками, с ведущими нулями); type — IP или OOO; status — active или liquidated, для ликвидированных ещё dateEliminate; dateCreate — дата регистрации; chief — руководитель; address, region, regionName и city — местонахождение; okved и okvedName — основной вид деятельности; category — раздел каталога; rating и reviewsCount — оценки пользователей; url — адрес карточки на rerb.org. Если реквизита в реестре нет, поле равно null.

Пример

curl -H "X-API-Key: ваш_ключ" "https://rerb.org/org-api.php?inn=7707083893&country=ru"

Ошибки

  • 400 bad_country — неизвестный код страны.
  • 400 bad_inn — номер не соответствует формату страны.
  • 401 unauthorized — ключ не передан или недействителен.
  • 404 not_found — организации с таким номером в этой стране нет в базе.
  • 503 db_unavailable — база временно недоступна, повторите запрос позже.

В каждой ошибке есть поле error с кодом, в части — message с пояснением. Ориентируйтесь на HTTP-статус и код, а не на текст сообщения.

Ограничения

Поиск идёт по точному совпадению номера; поиска по названию в API нет — для этого есть каталог на сайте. Ответы не кэшируются, поэтому вы всегда получаете текущее состояние базы. Сведения публикуются из открытых реестров и обновляются вместе с каталогом; юридически значимую выписку получайте в самом реестре. Использование API регулируется Условиями использования сайта.