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.
Компонент |
Тип |
Назначение |
|---|---|---|
|
Форма |
Форма типа |
|
Источник записей ( |
Принимает ИНН, хранит API-ключ 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 этим свойством не настраивается.
Параметры запроса к встроенному источнику:
Параметр |
Описание |
|---|---|
|
|
|
|
|
ИНН для поиска. Передаётся в поле |
|
Необязательный флаг выбора головной организации. По умолчанию |
Пример тела 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-ключ |
Подсказки, поиск организации по ИНН, банка по БИК, адреса по коду, справочники — всё, что оплачивается подпиской |
Да, в обоих описанных сценариях |
Секретный ключ |
Передаётся в заголовке |
Не используется в описанном автозаполнении и встроенном |
Для поиска организации через findById/party достаточно API-ключа. Если подключается другой сервис DaData, его заголовки аутентификации и способ разрешения секретов нужно настроить отдельно.
В браузерном виджете подсказок API-ключ может передаваться клиенту. Для стандартизации DaData требует дополнительный секретный ключ и серверный вызов. Такой ключ следует хранить на сервере, например в секретах, и получать его через настроенную серверную интеграцию.
Получение ключа
Перейдите на https://dadata.ru и нажмите кнопку «Войти» в правом верхнем углу экрана.
В открывшемся окне выберите «Зарегистрироваться». Введите имя пользователя, электронную почту и пароль, затем нажмите кнопку регистрации.
Подтвердите email: на указанный адрес придёт письмо со ссылкой для подтверждения. Неподтверждённая почта может быть причиной отказа API с кодом 403.
Перейдите в личный кабинет по адресу https://dadata.ru/profile/ — в нижней части страницы указаны API-ключ и секретный ключ аккаунта.
Скопируйте API-ключ. Секретный ключ для автозаполнения не нужен.
Настройка автозаполнения в форме
Эти действия относятся к сценарию модуля справочников через findCounterpartyByInn. Параметры встроенного dadata-party описаны в его разделе выше.
Перейдите в рабочее пространство «Раздел администратора» → Интеграция → Источники записей.
Откройте запись findCounterpartyByInn.
Вставьте API-ключ в параметр
tokenи сохраните запись.
В поставке параметр 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-источника данных ссылку на секрет |
Доработка |
Секреты станут доступны всем REST-источникам, включая Jira |
Перенести вызов DaData в маршрут Camel DSL с эндпоинтом и секретом |
Новый маршрут с получением ключа из секрета, переделка источника записей |
Решает задачу только для DaData |
Произвольный заголовок, включая X-Secret, можно задать обычным значением в REST DataSource. Это не добавляет автоматического разрешения ссылки на секрет. Встроенный dadata-party также читает ключ из свойства приложения, а не из ссылки на секрет.
Маппинг полей
Поле ответа DaData |
Ключ после JOLT |
Атрибут |
Статус |
|---|---|---|---|
|
|
|
Заполняется |
|
|
|
Заполняется |
|
|
|
Заполняется. У ИП пусто |
|
|
|
Заполняется. У ИП это ОГРНИП, для которого в модели есть отдельный атрибут |
|
|
|
Заполняется. Есть только у действующих головных организаций и ИП |
|
|
|
Не заполняется: ключи различаются регистром |
|
|
|
Заполняется с ошибками, см. ниже |
— |
— |
|
Не заполняется: почтового адреса в DaData нет |
Форма раскладывает значения по компонентам с совпадающими ключами, поэтому ключ после JOLT должен совпадать с ключом компонента формы.
Известные ограничения
Ограничение |
Где |
Причина и последствие |
|---|---|---|
Руководитель не заполняется |
Источник данных |
JOLT пишет |
Юридический адрес без индекса |
Форма |
Индекс приходит в |
Неверный порядок частей адреса |
Источник данных и форма |
Район города ( |
Формат «сокращение + точка + значение» |
Форма |
«р-н. Печатники», «пр-кт. Волгоградский», «обл. Московская» вместо готовых полей DaData |
Статус компании не проверяется |
Источник данных |
|
ИП не распознаются |
Источник данных и форма |
Не передаются |
ОПФ не заполняется |
Источник данных |
|
Формат ИНН не проверяется |
Форма |
Скрипт кнопки проверяет только непустое значение. У компонента есть |
Лишний запрос перезаписи почтового адреса |
Форма |
|
Лимиты и ошибки
Ограничения по частоте привязаны к внешнему 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. Чтобы передать поле в карточку:
Добавьте поле в JOLT-спецификацию.
Если в модели
ecos-counterpartyнет подходящего атрибута — добавьте атрибут в модель и компонент в форму.Если ключ после 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 совпадают с ключами компонентов. Проверьте условия их видимости и сохранения, особенно при переключении вида контрагента. Для следующих действий требуется доработка скрипта формы:
Что |
Как |
|---|---|
Юридический адрес |
Если пришёл |
Вид контрагента |
|
ОГРНИП |
При |
ОПФ |
Найти запись справочника |
Статус |
При |
ИНН |
Проверка |
Ошибки |
Для 403 — проверка ключа, подтверждения почты и лимита; для 429 — сообщение о превышении частоты. Не определять исчерпание суточного лимита только по коду 403 |
Диалог перезаписи |
Список атрибутов в |
Что ещё есть в 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.