DaData. Настройка и техническое описание

Интеграция с сервисом DaData заполняет реквизиты контрагента по ИНН. Пользователь вводит ИНН в карточке контрагента, нажимает «Автозаполнение» — и Citeck подставляет наименование, КПП, ОГРН, ОКПO и юридический адрес из ЕГРЮЛ.

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

Состав интеграции

Сценарий автозаполнения карточки поставляется артефактами модуля справочников и выполняется микросервисом ecos-integrations. Помимо него, в integrations есть отдельный встроенный источник записей dadata-party, описанный ниже.

Маппинг и поведение формы ниже соответствуют артефактам ecos-datalist 1.19.0-SNAPSHOT. В доработанной поставке они могут отличаться. Основные файлы модуля:

  • app/artifacts/ui/form/ecos-counterparty-form.json — форма и скрипт автозаполнения;

  • app/artifacts/integration/recsrc/findCounterpartyByInn.yml — параметры источника записей;

  • app/artifacts/integration/datasource/counterparty-suggestions-dadata.yml — HTTP-запрос и JOLT;

  • app/artifacts/model/type/ecos-counterparty.yml — модель контрагента.

Пути приведены относительно src/main/resources проекта ecos-datalist.

Компонент

Тип

Назначение

ecos-counterparty-form

Форма

Форма типа ecos-counterparty: кнопка «Автозаполнение», сборка юридического адреса, диалог перезаписи заполненных полей

findCounterpartyByInn

Источник записей (rest)

Принимает ИНН, хранит API-ключ DaData в параметре token

counterparty-suggestions-dadata

Источник данных (REST)

Отправляет запрос в DaData и преобразует ответ JOLT-спецификацией

Поток запроса

        sequenceDiagram
    actor U as Пользователь
    participant F as Форма контрагента
    participant R as Источник записей<br/>findCounterpartyByInn
    participant S as Источник данных<br/>counterparty-suggestions-dadata
    participant D as DaData
    U->>F: Кнопка «Автозаполнение»
    F->>F: Проверка: ИНН не пустой
    F->>R: Records.query(integrations/rs-findCounterpartyByInn, { inn })
    R->>S: inn, token (API-ключ DaData)
    S->>D: POST /suggestions/api/4_1/rs/findById/party<br/>Authorization: Token, { branch_type: MAIN, query: inn }
    D-->>S: Сведения из ЕГРЮЛ / ЕГРИП
    S->>S: JOLT (jsonRespTfmSpec): отбор реквизитов,<br/>адрес → legalAddress
    S-->>R: Реквизиты
    R-->>F: Реквизиты
    F->>F: Выбор первого результата,<br/>сборка юридического адреса
    alt Непустое прежнее значение отличается от нового
        F->>U: Перезаписать заполненные поля?
        U-->>F: Подтверждение или отказ
        opt Пользователь подтвердил
            F->>F: Заполнение полей карточки
        end
    else Подтверждение не требуется
        F->>F: Заполнение полей карточки
    end
    

В обычном пути одного нажатия выполняется один запрос к DaData. Форма берёт только первый результат; выбора из нескольких найденных организаций нет. Метод findById/party с branch_type: MAIN ограничивает поиск головной организацией. Полнота возвращаемых данных зависит от тарифа DaData.

Встроенный источник dadata-party

Источник integrations/dadata-party реализован в IntegrationsDAO и DadataClient. Он напрямую вызывает метод DaData findById/party. Этот путь использует свойства приложения и возвращает данные без JOLT-преобразования; подключение к форме контрагента через findCounterpartyByInn настраивается отдельно.

Настройки микросервиса integrations:

dadata.api-key: "<API-ключ DaData>"
dadata.root-uri: https://suggestions.dadata.ru/suggestions/api/4_1/rs/

DadataClientConfig добавляет заголовок Authorization: Token <API-ключ>. Свойство dadata.api-key относится к встроенному клиенту; параметр token источника записей findCounterpartyByInn этим свойством не настраивается.

Параметры запроса к встроенному источнику:

Параметр

Описание

sourceId

integrations/dadata-party. Префикс rs- не используется.

language

json.

query.tin

ИНН для поиска. Передаётся в поле query HTTP-запроса DaData.

query.main

Необязательный флаг выбора головной организации. По умолчанию false. Ограничение текущей реализации описано ниже.

Пример тела POST-запроса к {{host}}/gateway/api/records/query:

{
  "version": 1,
  "query": {
    "sourceId": "integrations/dadata-party",
    "language": "json",
    "query": {
      "tin": "7707083893",
      "main": true
    }
  },
  "attributes": ["data?json"]
}

Каждый элемент suggestions преобразуется в запись: идентификатор берётся из data.hid, а сведения об организации доступны в атрибуте data. Автоматического переноса этих значений в поля карточки контрагента этот DAO не выполняет.

Важно

В проверенной реализации ecos-integrations 2.40.0-SNAPSHOT поле клиента branchType помечено @JsonProperty("branch-type"). При main=true клиент формирует branch-type: MAIN, тогда как API DaData ожидает branch_type: MAIN — с подчёркиванием.

Пока расхождение не исправлено и не проверено запросом, нельзя полагаться на main=true как на фильтр головной организации. Исправление требуется в DadataClient.PartyByIdQuery: имя JSON-поля должно быть branch_type. Добавление branch_type в запрос Records API не заменяет исправление клиента: DAO принимает параметры tin и main и самостоятельно формирует HTTP-тело.

Подключение

Ключи DaData

В личном кабинете DaData доступны два ключа:

Ключ

Для чего нужен

Используется в Citeck

API-ключ

Подсказки, поиск организации по ИНН, банка по БИК, адреса по коду, справочники — всё, что оплачивается подпиской

Да, в обоих описанных сценариях

Секретный ключ

Передаётся в заголовке X-Secret при серверных вызовах API стандартизации. Требования других методов проверяйте по их документации.

Не используется в описанном автозаполнении и встроенном dadata-party

Для поиска организации через findById/party достаточно API-ключа. Если подключается другой сервис DaData, его заголовки аутентификации и способ разрешения секретов нужно настроить отдельно.

В браузерном виджете подсказок API-ключ может передаваться клиенту. Для стандартизации DaData требует дополнительный секретный ключ и серверный вызов. Такой ключ следует хранить на сервере, например в секретах, и получать его через настроенную серверную интеграцию.

Получение ключа

  1. Перейдите на https://dadata.ru и нажмите кнопку «Войти» в правом верхнем углу экрана.

  2. В открывшемся окне выберите «Зарегистрироваться». Введите имя пользователя, электронную почту и пароль, затем нажмите кнопку регистрации.

  3. Подтвердите email: на указанный адрес придёт письмо со ссылкой для подтверждения. Неподтверждённая почта может быть причиной отказа API с кодом 403.

  4. Перейдите в личный кабинет по адресу https://dadata.ru/profile/ — в нижней части страницы указаны API-ключ и секретный ключ аккаунта.

  5. Скопируйте API-ключ. Секретный ключ для автозаполнения не нужен.

Настройка автозаполнения в форме

Эти действия относятся к сценарию модуля справочников через findCounterpartyByInn. Параметры встроенного dadata-party описаны в его разделе выше.

  1. Перейдите в рабочее пространство «Раздел администратора» → Интеграция → Источники записей.

  2. Откройте запись findCounterpartyByInn.

  3. Вставьте API-ключ в параметр token и сохраните запись.

../_images/dadata_01.png

../_images/dadata_02.png

В поставке параметр token пустой — без ключа автозаполнение не работает.

Предупреждение

Ключ хранится в параметре источника записей открытым текстом, а не в секретах. Учитывайте права чтения этой конфигурации и ограничьте доступ к ней.

Почему ключ не в секрете

В текущей конфигурации REST-источника данных нет поля для ссылки на endpoint, credentials или secret. Поэтому в данном сценарии ключ передаётся параметром источника записей и подставляется в заголовок Authorization. Подстановка параметров в заголовки используется и в REST-источниках Jira.

Это ограничение конкретного REST DataSource, а не отсутствие секретов в платформе. Например, KonturFocusService в integrations получает токен из секрета kontur-focus-api-token через endpoint kontur-focus-api-endpoint и делает HTTP-вызов через RestTemplate. В модуле справочников также есть отдельный REST-источник counterparty-focus-api-kontur, передающий token параметром запроса. Эти пути Контур.Фокуса настраиваются независимо.

Возможные варианты доработки хранения ключа DaData:

Вариант

Что потребуется

Эффект

Добавить в конфигурацию REST-источника данных ссылку на секрет

Доработка ecos-integrations и формы REST-источника данных

Секреты станут доступны всем REST-источникам, включая Jira

Перенести вызов DaData в маршрут Camel DSL с эндпоинтом и секретом

Новый маршрут с получением ключа из секрета, переделка источника записей

Решает задачу только для DaData

Произвольный заголовок, включая X-Secret, можно задать обычным значением в REST DataSource. Это не добавляет автоматического разрешения ссылки на секрет. Встроенный dadata-party также читает ключ из свойства приложения, а не из ссылки на секрет.

Маппинг полей

Поле ответа DaData

Ключ после JOLT

Атрибут ecos-counterparty

Статус

data.name.full_with_opf

fullOrganizationName

fullOrganizationName

Заполняется

data.name.short_with_opf

shortOrganizationName

shortOrganizationName

Заполняется

data.kpp

kpp

kpp

Заполняется. У ИП пусто

data.ogrn

ogrn

ogrn

Заполняется. У ИП это ОГРНИП, для которого в модели есть отдельный атрибут psrnsp

data.okpo

okpo

okpo

Заполняется. Есть только у действующих головных организаций и ИП

data.management.name

CEOname

ceoName

Не заполняется: ключи различаются регистром

data.address.data.*: индекс, регион, район города, город, населённый пункт, улица, дом, корпус, квартира — с типами

legalAddress.{zipCode, regionName, district, city, settlement, street, house, bulk, flat}

juridicalAddress — строка собирается в форме

Заполняется с ошибками, см. ниже

—

—

postAddress

Не заполняется: почтового адреса в DaData нет

Форма раскладывает значения по компонентам с совпадающими ключами, поэтому ключ после JOLT должен совпадать с ключом компонента формы.

Известные ограничения

Ограничение

Где

Причина и последствие

Руководитель не заполняется

Источник данных

JOLT пишет CEOname, форма и модель ждут ceoName. Если поле заполнено вручную, форма каждый раз спрашивает про перезапись: сравнивает значение с undefined

Юридический адрес без индекса

Форма

Индекс приходит в legalAddress.zipCode, но в строку адреса не попадает

Неверный порядок частей адреса

Источник данных и форма

Район города (city_district) положен в слот district, который в строке стоит перед городом; район субъекта (area) не передаётся. Для региональных городов район встаёт перед городом, для сёл и посёлков пропадает муниципальный район

Формат «сокращение + точка + значение»

Форма

«р-н. Печатники», «пр-кт. Волгоградский», «обл. Московская» вместо готовых полей DaData *_with_type

Статус компании не проверяется

Источник данных

data.state.status не передаётся — ликвидированная или банкротящаяся компания заполняется без предупреждения

ИП не распознаются

Источник данных и форма

Не передаются data.type и data.fio: не проставляется counterpartyKind, не заполняются lastName, firstName, patronymicName, ОГРНИП уходит в ogrn вместо psrnsp

ОПФ не заполняется

Источник данных

data.opf.code не передаётся. Справочник legal-form пока не содержит кодов ОКОПФ, поэтому сопоставить ОПФ по коду нельзя

Формат ИНН не проверяется

Форма

Скрипт кнопки проверяет только непустое значение. У компонента есть required: true и maxLength: 12, но нет проверки цифрового состава, точной длины 10/12 и контрольных разрядов. При отсутствии результата показывается «Data is empty»

Лишний запрос перезаписи почтового адреса

Форма

postAddress включён в список сравнения, но отсутствует в результате JOLT. Непустой прежний адрес сравнивается с undefined и может вызвать диалог, хотя новое значение для него не задано

Лимиты и ошибки

Ограничения по частоте привязаны к внешнему IP, который видит DaData. Несколько экземпляров integrations или инсталляций могут делить один адрес через NAT/прокси либо использовать разные адреса. Учитывайте суммарные параллельные запросы, включая ручное автозаполнение.

Ниже приведены ограничения метода findById/party; ограничения других методов проверяйте отдельно по документации DaData.

Ограничение

Значение

Запросов в сутки

Зависит от тарифа — от 10 000 на бесплатном. Лимит общий на все сервисы подписки

Частота запросов

30 в секунду с одного IP-адреса

Новые соединения

60 в минуту с одного IP-адреса, на всех тарифах. При переиспользовании соединения запросов в минуту может быть больше

Длина запроса

До 300 символов

Актуальность данных

Сведения ЕГРЮЛ отстают не более чем на 3 дня, адреса обновляются раз в неделю

Форма показывает «Error while requesting data», если Records API вернул непустой массив errors; «Data is empty» — если нет первого результата .json; «Undefined error» — при иной ошибке без подготовленного сообщения. Отдельных сообщений для HTTP-кодов DaData в текущем скрипте нет.

При диагностике различайте ошибку HTTP, отсутствие организации в ответе и ошибку JOLT. Проверяйте ответ Records API и логи integrations: HTTP-исключение может возникнуть до проверки статуса в клиентском коде, поэтому конкретная запись лога не гарантирована для каждого отказа.

Код ответа

Причина

Что делать

403

Неправильный API-ключ, неподтверждённая почта или исчерпанный суточный лимит

Проверить ключ, подтверждение почты и остаток лимита в личном кабинете. При исчерпании дождаться следующих суток или изменить тариф; ожидание не исправляет неверный ключ

429

Превышена частота запросов или число новых соединений

Прекратить поток запросов и уменьшить частоту/число новых соединений. Автоматическая обработка 429 и отложенный повтор в описанных клиентах не реализованы

Причины 403 перечислены в официальной инструкции DaData.

Расширение набора полей

Ответ DaData на запрос по ИНН содержит больше данных, чем попадает в карточку: лишнее отбрасывает JOLT-спецификация (jsonRespTfmSpec) источника данных counterparty-suggestions-dadata. Чтобы передать поле в карточку:

  1. Добавьте поле в JOLT-спецификацию.

  2. Если в модели ecos-counterparty нет подходящего атрибута — добавьте атрибут в модель и компонент в форму.

  3. Если ключ после JOLT совпадает с ключом компонента, существующий цикл заполнения передаст значение компоненту. Проверьте также его видимость, валидацию, сохранение и включение в диалог перезаписи. Для преобразования значения или другого ключа доработайте скрипт.

Доступность дополнительных сведений зависит от тарифа и наличия данных у DaData. Для переноса этих сведений в карточку нужны соответствующие маппинг и поля формы.

Пример расширенной JOLT-спецификации (уровень data)

В примере исправлен регистр ceoName и добавлены тип, статус, ОПФ, ФИО ИП, основной ОКВЭД, идентификатор DaData, должность руководителя, готовая строка адреса и коды ФИАС и КЛАДР. Текущий маппинг address.data → legalAddress сохраните внутри блока address.data рядом с новыми полями.

Это фрагмент для замены data внутри spec.suggestions.* операции shift, а не полная спецификация jsonRespTfmSpec. Сохраните окружающий список операций и проверьте преобразование на примере ответа DaData.

"data": {
  "kpp": "[&2].kpp",
  "okpo": "[&2].okpo",
  "ogrn": "[&2].ogrn",
  "type": "[&2].partyType",
  "okved": "[&2].okved",
  "hid": "[&2].dadataHid",
  "management": {
    "name": "[&3].ceoName",
    "post": "[&3].ceoPost"
  },
  "name": {
    "short_with_opf": "[&3].shortOrganizationName",
    "full_with_opf": "[&3].fullOrganizationName"
  },
  "fio": {
    "surname": "[&3].lastName",
    "name": "[&3].firstName",
    "patronymic": "[&3].patronymicName"
  },
  "opf": {
    "code": "[&3].opfCode"
  },
  "state": {
    "status": "[&3].partyStatus"
  },
  "address": {
    "unrestricted_value": "[&3].juridicalAddressFull",
    "data": {
      "fias_id": "[&4].juridicalAddressFiasId",
      "kladr_id": "[&4].juridicalAddressKladrId"
    }
  }
}

Ключи ceoName, lastName, firstName, patronymicName совпадают с ключами компонентов. Проверьте условия их видимости и сохранения, особенно при переключении вида контрагента. Для следующих действий требуется доработка скрипта формы:

Что

Как

Юридический адрес

Если пришёл juridicalAddressFull — записать его в juridicalAddress, сборку из legalAddress не выполнять

Вид контрагента

partyType: LEGAL → legalEntity, INDIVIDUAL → individualEntrepreneur в counterpartyKind

ОГРНИП

При INDIVIDUAL переложить ogrn в psrnsp

ОПФ

Найти запись справочника legal-form по opfCode и проставить legalForm — после того как в справочник добавят коды ОКОПФ

Статус

При partyStatus не ACTIVE — предупреждение до заполнения полей

ИНН

Проверка ^\d{10}$ или ^\d{12}$ до запроса

Ошибки

Для 403 — проверка ключа, подтверждения почты и лимита; для 429 — сообщение о превышении частоты. Не определять исчерпание суточного лимита только по коду 403

Диалог перезаписи

Список атрибутов в isNeedAsk привести к ключам формы

Что ещё есть в DaData

Ниже — возможности DaData, которые Citeck пока не использует. Они перечислены, чтобы оценить, что можно подключить.

Дополнительные сведения об организации

На любом тарифе, включая бесплатный, DaData уже возвращает в ответе на запрос по ИНН больше данных, чем попадает в карточку:

Сведения

Применение

Тип: юридическое лицо или ИП, ФИО предпринимателя

Заполнение вида контрагента, ФИО и ОГРНИП для ИП

Организационно-правовая форма и код ОКОПФ

Заполнение ОПФ

Статус: действующая, ликвидируется, ликвидирована, банкротство, реорганизация

Предупреждение при заполнении карточки нерабочей компании

Даты регистрации, ликвидации и последних изменений

Возраст компании, дата сверки с ЕГРЮЛ

Должность руководителя и дата вступления в должность

«В лице генерального директора…» в шаблонах документов, проверка полномочий подписанта

Основной ОКВЭД

Отрасль клиента, сегментация в CRM

Коды ОКАТО, ОКТМО, ОКОГУ, ОКФС, КПП крупнейшего налогоплательщика

Полный набор реквизитов

Головная организация или филиал, число филиалов

Структура клиента

Юридический адрес готовой строкой с индексом, коды ФИАС (ГАР) и КЛАДР, координаты, признак качества разбора

Корректный адрес без сборки по частям, связь с ФИАС, карта клиентов

Реквизиты банков, адреса и контакты

Отдельные запросы, доступные на любом тарифе. Для большинства из них в карточке контрагента уже есть поля.

Возможность

Что даёт

Банк по БИК, SWIFT или ИНН

Наименование, БИК, SWIFT, корреспондентский счёт, адрес и статус банка — одним запросом

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

Ввод почтового и других адресов с кодами ФИАС (ГАР) и КЛАДР, индексом и координатами

Подсказки по ФИО и электронной почте

Ввод ФИО по частям с определением пола, дополнение домена почты

Кем выдан паспорт

Подразделение по коду

Поиск компании по названию

Поиск по названию, ФИО руководителя или адресу, а не только по ИНН; фильтры по статусу, ОКВЭД, региону

Компании Беларуси и Казахстана

Реквизиты контрагентов из ЕАЭС

Работа с ФИАС (ГАР) и КЛАДР

DaData даёт доступ к своей копии ФИАС (ГАР) и КЛАДР по API — это запросы к справочнику, а не выгрузка базы. Копия обновляется раз в неделю.

  • Подсказки по адресам — поиск адреса по любой части, индексу, коду ФИАС или кадастровому номеру; коды ФИАС и КЛАДР на каждом уровне от региона до квартиры.

  • Адрес по коду — по коду ФИАС (ГАР) до квартиры, по коду КЛАДР до улицы. Полезно, когда адрес приходит из внешней системы кодом.

  • Обратное геокодирование — адрес по координатам.

  • Стандартизация адресов — разбор адреса из строки по полям, индекс, координаты, часовой пояс, кадастровые номера. Предназначена для массовой чистки адресов при миграции и импорте; оплачивается поштучно.

Коды ФИАС домов и квартир иногда меняются, а поиск по коду работает только по актуальным, поэтому адрес стоит хранить строкой рядом с кодом.

Государственные справочники

Доступны на любом тарифе: ОКВЭД 2, ОКПД 2, ОКТМО, страны (ISO 3166), валюты (ISO 4217), налоговые инспекции, таможни, суды, станции метро, МКТУ, профессии и должности ОКПДТР, медицинские должности, марки автомобилей. Их можно использовать в формах модулей — например, ОКПД 2 для предмета договора, суды для претензионно-исковой работы.

Проверки данных

Оплачиваются поштучно с баланса DaData, первые 100 записей бесплатно.

Проверка

Что делает

ФИО

Разбирает ФИО на части, определяет пол, склоняет по падежам

Паспорт

Проверяет формат и сверяет со справочником недействительных паспортов МВД. Справочник не обновляется с 21 июня 2023 года

Телефон

Оператор с учётом переноса номера, страна, город, часовой пояс

Электронная почта

Исправляет опечатки, выявляет одноразовые адреса

Компания по электронной почте

Сведения об организации по корпоративному адресу

MCP-сервер для AI-агентов

DaData предоставляет MCP-сервер, через который AI-агент получает сведения о компаниях и адресах. Через него агент Citeck AI мог бы проверять контрагента и заполнять карточку прямо из диалога. Сведения о компаниях предоставляются по подписке, проверка адресов и поиск владельца домена оплачиваются поштучно.

Возможные направления развития

  • Исправление автозаполнения. Заполнение руководителя, юридический адрес в виде готовой строки DaData с индексом, предупреждение о ликвидированных и банкротящихся компаниях, распознавание ИП с заполнением ФИО и ОГРНИП, заполнение организационно-правовой формы, проверка формата ИНН, отдельные сообщения об исчерпании лимита.

  • Хранение ключа в секретах. Поддержка секретов в REST-источниках данных — это же нужно для подключения стандартизации и мониторинга лимита.

  • Дополнительные сведения на бесплатном тарифе. Должность руководителя, даты регистрации и ликвидации, основной ОКВЭД, коды статистики, коды ФИАС и КЛАДР юридического адреса.

  • Автозаполнение банка по БИК. Наименование банка, БИК и SWIFT по одному запросу.

  • Ввод адресов с подсказками. Почтовый и другие адреса с кодами ФИАС (ГАР), индексом и координатами.

  • Государственные справочники — по потребностям модулей.

  • Мониторинг лимита через API статистики DaData с предупреждением администратору до отказа.

  • MCP-сервер DaData для агентов Citeck AI.

Источники