Собрать самим или взять готовое: честная математика семнадцати интеграций

Продакт приносит задачу: «проверять контрагента по ИНН прямо в карточке сделки». Разработчик открывает сайт налоговой, тыкает в форму, смотрит в панель разработчика браузера, видит обычный JSON и говорит: тут работы на два дня. И он не врёт.

В четверг вечером всё действительно работает. Вбиваешь ИНН — прилетает карточка: наименование, адрес, ОКВЭД, руководитель. Демо для продакта проходит на ура.

В понедельник источник начинает отвечать пятисотыми. Во вторник вместо JSON приходит требование пройти проверку картинкой. В среду выясняется, что нужен ещё справочник банков, и он обновляется каждый день. Через месяц кто-то спрашивает, почему сервер съел 29 гигабайт памяти, и вы впервые произносите вслух слова «адресный реестр ФИАС».

Мы прошли этот путь семнадцать раз — по одному на каждый сервис Atlorium. Ниже: что именно приходится держать, во что это обходится за год при честно названных допущениях и в каких случаях писать своё всё-таки правильно. Такие случаи есть, и мы их назовём.

Что начинается после четверга

Первая версия интеграции решает задачу «получить данные». Всё остальное время вы решаете задачу «получать данные каждый день, когда источник этого не хочет». Это две разные работы, и вторая стоит на порядок дороже.

Сколько это стоит за год

Считаем четыре интеграции: реестр ЮЛ и ИП, адресный реестр, справочник БИК, проверка почты. Все допущения называем вслух — подставьте свои и пересчитайте, арифметика простая.

Допущение 1. Полностью нагруженный час разработчика — 3 000 ₽. Это не зарплата на руки: сюда входят налоги, отпуск, техника, аренда, доля тимлида и доля рекрутинга. Возьмите свою цифру.

Допущение 2. Часы — из нашего опыта, а не из оценки «на глаз». Мы эти интеграции написали, и часть из них — дважды.

Это только вход. Дальше начинается владение.

Теперь вторая сторона. Оплата по факту — это цена за запрос, умноженная на объём, без абонентской платы, минимального платежа и договора с каждым провайдером отдельно. Точка безубыточности считается одной формулой:

Запросов в год, при которых своё дешевле = Годовая стоимость владения ÷ Цена одного запроса

Своих цифр мы сюда намеренно не подставляем: цены меняются, статья остаётся. Возьмите актуальную цену нужного сервиса на странице тарифов, поделите на неё 2 184 000 ₽ за первый год — и получите свой порог в запросах. Ниже порога разговор окончен. Выше — читайте раздел о том, когда своё оправдано.

Где на самом деле проходит граница

Граница проходит не по слову «интеграция», а по свойствам источника. Мы бы сформулировали её так.

Пишите сами, если источник ведёт себя как файл. Стабильный формат, публикуется по расписанию, не требует авторизации, не банит и не капчит. Справочник БИК ЦБ — ровно такой: один ZIP в сутки, три дня работы, дальше почти ноль поддержки. Если он вам нужен и у вас есть кто-то, кто раз в квартал посмотрит логи, — берите и пишите, это честно дешевле.

Покупайте, если источник ведёт себя как противник. Реестр ЮЛ и ИП не отдаёт данные — он их защищает от автоматизации: двухшаговый протокол, привязка к сессии, проверочная картинка, баны по адресу. Каждое ваше улучшение он рано или поздно встретит своим. Это не разовая работа, это подписка на гонку, оплаченная временем вашей команды.

Считайте отдельно, если источник — это данные, а не запрос. Адресный реестр — не API, а датасет: 35+ ГБ архива, ETL, движок поиска, регулярная пересборка. Если вам нужны единичные проверки адреса — брать всё это себе бессмысленно. Если вы строите поверх реестра аналитику, джойните его со своими таблицами и гоняете по нему тяжёлые выборки — API по одному адресу вам не поможет вообще, и правильный ответ здесь: тащить базу к себе.

Код: четыре источника, один ключ

Всё, что описано выше, снаружи выглядит как один GET с заголовком авторизации. Ключ в примерах — публичный демо-ключ песочницы: он работает без регистрации и отдаёт моки — правдоподобные, но сгенерированные данные. Они детерминированы (один и тот же запрос даёт один и тот же ответ), так что на них можно писать тесты. Реальные данные приходят с личным ключом. Ответ песочницы помечен заголовком X-Atlorium-Sandbox: true.

curl -H "Authorization: Bearer ak_sandbox_demo_mockdata_v1" \
     "https://atlorium.com/api/egrul/7707083893"
        

import requests

resp = requests.get(
    "https://atlorium.com/api/egrul/7707083893",
    headers={"Authorization": "Bearer ak_sandbox_demo_mockdata_v1"},
    timeout=30,
)

if resp.status_code == 503:
    # Внешний источник недоступен. Деньги за такой запрос не списываются.
    raise RuntimeError("Реестр временно недоступен, повторим позже")

data = resp.json()
if not data["found"]:
    raise ValueError("Организация не найдена в реестре")

if not data["active"]:
    print("Внимание: организация не действует —", data["status"])
        

using var http = new HttpClient();
http.DefaultRequestHeaders.Authorization =
    new AuthenticationHeaderValue("Bearer", "ak_sandbox_demo_mockdata_v1");

// Таймаут щедрый: источник двухшаговый, и на его стороне возможна проверка.
http.Timeout = TimeSpan.FromSeconds(30);

var resp = await http.GetAsync("https://atlorium.com/api/egrul/7707083893");
if (resp.StatusCode == HttpStatusCode.ServiceUnavailable)
    throw new InvalidOperationException("Реестр временно недоступен");

var card = await resp.Content.ReadFromJsonAsync<JsonElement>();
Console.WriteLine(card.GetProperty("fullName").GetString());
        

{
  "found": true,
  "inn": "7707083893",
  "ogrn": "1027700132195",
  "fullName": "ПУБЛИЧНОЕ АКЦИОНЕРНОЕ ОБЩЕСТВО «СБЕРБАНК РОССИИ»",
  "shortName": "ПАО СБЕРБАНК",
  "status": "Действующее",
  "active": true,
  "address": "117312, г. Москва, ул. Вавилова, д. 19",
  "primaryOkved": { "code": "64.19", "name": "Денежное посредничество прочее" },
  "authorizedCapital": 67760844000.0,
  "dataDate": "2026-07-13"
}
        

Ключевые поля для принятия решения — found (есть ли субъект в реестре) и active (действует ли он). Отдельный флаг extended=true добирает из официальной выписки то, чего в базовой карточке нет: у ИП — почту и пол, у ЮЛ — состав участников и их доли. Это отдельный тариф: за расширенным режимом стоит скачивание PDF, обрезка до нужных страниц и платное извлечение структуры.

Остальные три источника — тем же ключом, тем же заголовком, тем же форматом ошибок.

KEY="ak_sandbox_demo_mockdata_v1"

# Автодополнение адреса из ГАР/ФИАС (за этим — база, собранная из десятков ГБ XML)
curl -H "Authorization: Bearer $KEY" \
     "https://atlorium.com/api/gar/suggest?query=Тагил%20Новострой&limit=7"

# Банк по БИК (справочник ЦБ, обновляется ежедневно)
curl -H "Authorization: Bearer $KEY" \
     "https://atlorium.com/api/cbr/044525225"

# Проверка почтового адреса перед сохранением лида
curl -H "Authorization: Bearer $KEY" \
     "https://atlorium.com/api/emailvalidation?email=ivan@example.com"
        

{
  "email": "ivan@example.com",
  "status": "Valid",
  "statusRaw": "valid",
  "domain": "example.com",
  "mxFound": true,
  "catchAllDomain": false,
  "freeEmail": false
}
        

Что делать с вердиктом проверки почты — таблица решений. Это ровно те значения, которые возвращает поле status:

Когда своё — правильный ответ

Мы продаём API, и было бы удобно закончить статью на «покупайте всегда». Это было бы неправдой. Есть четыре ситуации, в которых своя интеграция объективно выигрывает, и если вы в одной из них — считайте, а не покупайте.

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

Данные не должны покидать ваш контур. Банковская тайна, объекты КИИ, требования регулятора или собственная политика: если сам факт отправки ИНН клиента наружу — нарушение, вопрос закрыт. Никакая экономия этого не перевешивает.

Вам нужна база, а не ответы. Аналитика по всему адресному реестру, джойн ГАР с вашей географией доставки, ночные пересчёты по миллионам строк. Запросный API тут не инструмент — нужен датасет у себя. Кстати, именно так устроены мы: адресная база лежит у нас файлом, потому что для этой задачи другого способа нет.

Источника у нас просто нет. Семнадцать сервисов — это не весь мир. Нужен отраслевой реестр, которого в списке нет, — писать придётся самим, и наш опыт выше подскажет, к чему готовиться.

Чего это не умеет

Покупка API не отменяет зависимость от источника — она переносит на нас работу по её обслуживанию. Если реестр лежит, у нас тоже нет данных: вы получите 503, и деньги за такой запрос не спишутся, но данные из воздуха не появятся. Обещать «100% доступности поверх источника, который сам недоступен» мы не будем.

Мы не гарантируем полноту и юридическую силу сведений госреестров. Отдаём то, что отдал официальный источник, — в том виде, в котором он это отдал. Если в реестре ошибка, она приедет к вам.

Проверка почты отвечает на вопрос о доставляемости: существует ли ящик, принимает ли домен почту, не одноразовый ли он и не ловушка ли. Читает ли этот ящик живой человек — она не знает, письмо при проверке не отправляется. Статус CatchAll — это честное «проверить невозможно», а не завуалированное «плохо».

Повторный запрос по тому же идентификатору тарифицируется как новый: вы платите за обращение к сервису. Кэш на вашей стороне — законный и правильный способ платить меньше, и мы прямо рекомендуем его тем, у кого сценарий бьёт по одним и тем же ключам.

И арифметика из этой статьи — не универсальный закон. Это наши часы, наша ставка, наш набор источников. У вас может быть дешевле команда, проще требования или уже написанная половина. Формулы выше — чтобы вы посчитали своё, а не поверили нашему.

Частые вопросы

curl -H "Authorization: Bearer ak_sandbox_demo_mockdata_v1" \
     https://atlorium.com/openapi/egrul_ru.json