Odoo 19 Community: коммерческий реестр (Firmenbuch) и проверка адресов для австрийских клиентов – наш модуль с открытым исходным кодом partner_firmenbuch_at

Кто ведёт бизнес в Австрии, знает эти вопросы: верны ли фирменное наименование и адрес моего нового клиента? Числится ли компания по-прежнему в коммерческом реестре или она в стадии ликвидации? Не открыто ли в отношении клиента, которого я снабжаю уже два года, дело о несостоятельности? Ответы есть в коммерческом реестре (Firmenbuch) министерства юстиции, но заглядывает туда регулярно едва ли кто-то. В Odoo контакт создаётся один раз, а потом устаревает.

Для этого мы разработали модуль Firmenbuch для партнёров (partner_firmenbuch_at). Он связывает контакты Odoo с коммерческим реестром (Firmenbuch) и с официальным адресным реестром BEV. Он написан для Odoo 19 и бесплатно доступен на GitHub как свободное программное обеспечение под лицензией LGPL-3:

github.com/Alex0176/odoo-partner-firmenbuch-at

Проблема: основные данные, о которых никто не заботится

Контакт в Odoo чаще всего создаётся в спешке: название, приблизительный адрес, возможно, UID. Для первого коммерческого предложения этого достаточно. Но этого недостаточно для счетов, которые должны быть юридически корректно адресованы, и тем более для того, чтобы заметить, что у клиента что-то изменилось. На практике проявляются четыре пробела:

• Неполные основные данные. Номер в коммерческом реестре, суд и организационно-правовая форма почти всегда отсутствуют, потому что поиск вручную — это трудоёмкая работа.
• Неверное написание. Фирменное наименование без организационно-правовой формы, опечатки в улице или населённом пункте, перепутанный почтовый индекс. Это замечают только тогда, когда почта возвращается.
• Отсутствие наблюдения. Если суд возбуждает дело о несостоятельности или клиент ликвидирует своё общество, Odoo об этом ничего не узнаёт. Отдел продаж продолжает поставлять товары в кредит.
• Разрозненные источники. Коммерческий реестр, годовая отчётность и адресный реестр находятся в разных местах. Тот, кто хочет их проверить, вручную копирует данные между окнами браузера.

Что делает модуль

1. Новые компании ищутся в реестре. Если кто-то создаёт контакт как компанию (страна Австрия или не указана), модуль в течение нескольких минут ищет её в коммерческом реестре. Если найдено ровно одно совпадение, пустые поля заполняются: улица, почтовый индекс, населённый пункт, страна, номер в коммерческом реестре, суд и организационно-правовая форма.
2. Расхождения предлагаются, но не перезаписываются. Если в контакте указано не то, что в реестре, создаётся предложение об изменении, которое сотрудник утверждает по каждому полю отдельно.
3. Поиск в Firmenbuch в контакте. На вкладке Firmenbuch поиск находит компании по названию, даже если автоматическое совпадение не было однозначным.
4. Ежедневный мониторинг. Модуль ежедневно запрашивает, какие компании и документы изменились в реестре, и проверяет затронутых клиентов. Дополнительно через настраиваемые интервалы каждая компания проверяется заново в полном объёме.
5. Уровни предупреждений. Открытые дела о несостоятельности и процедуры санации (по правовым фактам реестра), ликвидация, исключение из реестра, отрицательный собственный капитал и низкий коэффициент собственного капитала распознаются и отображаются в контакте.
6. Проверка адресов. Австрийские адреса проверяются локально по официальному адресному реестру Федерального ведомства мер и измерений (BEV).
7. Данные реестра в контакте. Суд, организационно-правовая форма, директора и правовые факты находятся на вкладке Firmenbuch. Они отражают реестр и обновляются напрямую.
8. Сообщения только внутри компании. Все сообщения отправляются во внутренний канал Discuss Firmenbuch и в Chatter контакта. Проверка по множеству компаний создаёт одно сводное сообщение вместо отдельного для каждой компании. Клиентам модуль никогда ничего не отправляет.

Предложения вместо перезаписи

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

В разделе Контакты → Firmenbuch → Предложения Firmenbuch вы видите для каждого поля текущее значение и значение из реестра. Поля, которые вы не хотите принимать, оставьте без отметки. С помощью Применить выбранное записываются только отмеченные поля, с помощью Отклонить предложение аннулируется. Новое предложение заменяет прежние открытые предложения того же контакта, чтобы не применялись устаревшие значения.

Предупреждения: несостоятельность, ликвидация, баланс

Модуль различает три уровня:

• Без замечаний: сообщать нечего.
• Предупреждение (жёлтый): в реестре есть действующие записи о ликвидации, роспуске, прекращении деятельности, исключении из реестра или слиянии, компания помечена как исключённая либо ранее начатое дело о несостоятельности было прекращено в последние годы (по умолчанию три года, настраивается). Либо годовая отчётность показывает отрицательный собственный капитал, коэффициент собственного капитала ниже 8 % (значение по умолчанию по аналогии с § 23 URG, настраивается), годовой убыток или снижение выручки на 25 % и более.
• Критический (красный): открыто дело о несостоятельности, банкротстве или процедура санации, которое ещё не прекращено, либо заявление отклонено из-за недостаточности имущества для покрытия расходов. Последнее считается неплатёжеспособностью.

В контакте появляется цветной баннер, в списке контактов — пометка, а в поиске есть фильтры Предупреждение Firmenbuch и Firmenbuch: критический. Если клиент становится критическим, ответственный менеджер по продажам (при его отсутствии — администратор) получает задачу Firmenbuch: проверить клиента, а канал Firmenbuch получает сообщение.

Правовые факты. Дела о несостоятельности указаны в реестре не в тексте о компании, а как правовые факты с датой, номером дела и судом. Модуль считывает их, сопоставляет открытие и прекращение по одному и тому же номеру дела и показывает их в контакте списком. Так прекращённое дело через несколько лет остаётся лишь информацией, а текущее отображается красным.

Годовая отчётность. Если последняя годовая отчётность имеется в формате XML, модуль считывает собственный капитал, годовой результат, сумму баланса и выручку и рассчитывает коэффициент собственного капитала, изменение выручки и категорию размера по § 221 UGB (включая микропредприятия). Малые общества не обязаны публиковать свою выручку, в таком случае модуль её не показывает. Их результат он выводит из балансовой прибыли за вычетом перенесённой прибыли и помечает как оценку. Названия позиций, по которым ведётся поиск, настраиваются, потому что структура XML зависит от формуляра.

Проверка адресов по адресному реестру BEV

BEV предоставляет адресный реестр как открытые данные (Adresse Relationale Tabellen – Stichtagsdaten, новая контрольная дата дважды в год, бесплатное использование с указанием источника). Модуль загружает выгрузку через официальную службу INSPIRE-ATOM, около 120 МБ примерно с 2,5 миллионами адресов, и импортирует её в собственные компактные таблицы.

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

• Действителен: такой адрес есть в реестре.
• Номер дома неизвестен: улица и населённый пункт совпадают, номер дома — нет.
• Предложено исправление: опечатка в улице или населённом пункте, неверный почтовый индекс. Исправление готово в виде предложения.
• Не найден: реестр не знает такого адреса.

Пустая федеральная земля заполняется сразу. Частные адреса контактов (тип Частный адрес) не проверяются. Указание источника © Österreichisches Adressregister, Stichtagsdaten vom … с актуальной контрольной датой находится в настройках. Обновление выполняется еженедельно, но загрузка происходит только тогда, когда BEV опубликовал более новую контрольную дату.

Техническая реализация

Доступ к реестру

Министерство юстиции предоставляет Firmenbuch через FBW-WebServices (HVD) на JustizOnline в виде SOAP-интерфейса. Доступ бесплатный, но требует ключа API, который запрашивается через ID Austria в разделе Informationsweiterverwendung. Ключ передаётся в HTTP-заголовке X-API-KEY. Модуль использует службу напрямую, без скрапинга экрана.

Клиент models/firmenbuch_client.py — это чистый Python без зависимости от Odoo. Он знает запросы SUCHEFIRMAREQUEST, AUSZUG_V2_REQUEST, SUCHEURKUNDEREQUEST, URKUNDEREQUEST, а также VERAENDERUNGENFIRMAREQUEST и VERAENDERUNGENURKUNDEREQUEST. Благодаря этому его можно тестировать на сохранённых ответах. Запросы отправляются с интервалом 0,3 секунды, запросы об изменениях — блоками по семь дней.

Обработка выписки

Из выписки используются только ещё действующие записи (атрибут AUFRECHT не равен false). Название берётся из признака данных FI_DKZ02, адрес — из FI_DKZ03, местонахождение — из FI_DKZ06, организационно-правовая форма — из FI_DKZ07. Кроме того, учитываются суд, веб-адрес, лица с полномочиями представительства и правовые факты. Для уровня предупреждения тексты всех действующих записей просматриваются на наличие настраиваемых ключевых слов:

DEFAULT_CRITICAL = "Konkursverfahren, Insolvenzverfahren, Sanierungsverfahren, Konkurs eröffnet, ..."
DEFAULT_WARNING  = "Liquidation, aufgelöst, Auflösung, Abwicklung, Löschung, gelöscht, Verschmelzung, in Liqu."

Преимущество проверки по ключевым словам: она работает независимо от того, в каком поле реестр ведёт тот или иной процесс. Недостаток описан в разделе Ограничения.

Мониторинг

Модуль создаёт три запланированных действия:

• Поиск новых компаний (каждые 10 минут, до 20 контактов за запуск). Кроме того, поиск запускается сразу при создании.
• Мониторинг компаний (ежедневно в 04:30). Запрашивает изменённые компании и документы с момента последнего запуска (не более чем за 30 дней), проверяет затронутых клиентов, а затем до 50 клиентов, у которых последняя проверка была дольше установленного срока назад. Каждая компания сохраняется в отдельной транзакции, чтобы ошибка не приводила к потере прежних результатов. Результат запуска приходит в канал одним сводным сообщением.
• Обновление адресного реестра (еженедельно в 03:15).

Без ключа API первые два действия сразу завершаются. Контрольная сумма для каждой компании не позволяет повторно обрабатывать неизменённые выписки.

Адресный реестр

Данные BEV хранятся в трёх таблицах (bev.locality, bev.street, bev.address) с индексом по почтовому индексу, коду улицы и номеру дома. Импорт выполняется через COPY в одной транзакции, то есть таблицы заменяются за один шаг. Номера домов нормализуются в написании реестра (51-55, 12a). С номерами домов таблицы занимают в базе данных около 400 МБ. Кому это не нужно, тот отключает Проверять номера домов и обходится примерно 150 000 строк.

Чему нас научил настоящий сервис

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

• Только краткая информация. Выписку с этим ключом можно получить только в объёме краткой информации. Запросы с полной информацией служба отклоняет. В версии 1.0.0 ежедневный запуск ещё делал неверный запрос, версия 1.1.0 это исправляет. Из сведений о лицах модуль берёт только имена директоров с полномочиями представительства; участники общества и адреса физических лиц не считываются.
• Улица и номер дома раздельно. Адрес приходит как STRASSE и HAUSNUMMER в отдельных элементах, а не одним текстом. Модуль объединяет их.
• Суд в блоке исполнения. Компетентный суд указан не в части о компании, а в последнем блоке VOLLZ выписки.
• Исключённые компании. Исключённую компанию распознают по атрибуту (MIT_FIRMA_GELOESCHT_DURCH_VNR), а не по тексту. Модуль формирует из этого вывод Компания исключена, который вызывает предупреждение.
• Название компании — это не поисковое слово. Поиск сравнивает начало названия. «Muster GmbH» ничего не находит, если в реестре записано «Muster Gesellschaft m.b.H.»; компании в стадии ликвидации содержат в названии «in Liqu.», а в названии контакта иногда всё ещё стоит &. Поэтому модуль повторяет поиск без организационно-правовой формы и сравнивает названия без вариантов написания организационно-правовой формы, без HTML-символов и без приписки «in Liqu.». Единственное совпадение принимается только в том случае, если его название начинается так же, как название контакта.
• Изменения документов без номера Firmenbuch. Список изменённых документов содержит только ключ. Номер Firmenbuch (без контрольной буквы) находится в начале этого ключа. По нему модуль сопоставляет изменения с клиентами.

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

Тест на собственной клиентской базе

После версии 1.1.0 мы опробовали модуль на собственной клиентской базе. Сначала выполнялся только читающий поиск по названию, затем сопоставление однозначных совпадений. При этом ничего не изменялось без учёта имеющихся значений: пустые поля заполнялись, расхождения ожидают утверждения в виде предложений, и не было отправлено ни одного электронного письма. Результат, без названий отдельных компаний:

• Было выполнено 438 поисков по контактам компаний со статусом клиента в Австрии или без указания страны.
• 138 из них были однозначно сопоставлены в Firmenbuch. Ещё у 18 было однозначное совпадение по названию, но другой адрес в реестре (переезд или одноимённая компания), поэтому они остались нетронутыми. 2 названия неоднозначны.
• Примерно 280 мы не нашли или нашли только частичные совпадения. Это физические лица, индивидуальные предприниматели, иностранные компании, контакты, в которых указан только бренд или населённый пункт, и компании, название которых в контакте отличается от записи в реестре, например потому, что там указана другая организационно-правовая форма. Для них остаётся ручной поиск в Firmenbuch.
• Возникло 63 предложения об изменении, в основном по улице и номеру дома (написание) и по стране.
• 66 предупреждений, критического уровня нет. 36 компаний помечены в реестре как исключённые (9 из них также находятся в ликвидации), у 2 было уже прекращённое дело о несостоятельности, а у 42 привлекла внимание годовая отчётность: низкий коэффициент собственного капитала, убыток или снижение выручки. Исключённая компания — это не обязательно потерянный клиент, но повод проверить адрес и получателя счёта.

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

Установка и настройка

Требования: Odoo 19.0 со стандартными приложениями Контакты и Discuss, пакет Python requests (есть в любой установке Odoo) и исходящий HTTPS-доступ к justizonline.gv.at и data.bev.gv.at. У модуля нет зависимостей за пределами стандартных приложений, поэтому он не подтягивает другие модули.

1. Поместите папку partner_firmenbuch_at в addons_path, обновите список приложений и установите модуль; в рабочих системах лучше сначала установить на тестовую базу данных.
2. Модуль создаёт канал Discuss Firmenbuch (для внутренних пользователей) и добавляет в него всех администраторов. Кроме того, создаются три запланированных действия.
3. Запросить ключ API: JustizOnline (ID Austria), Informationsweiterverwendung, API FBW.
4. Настройки → Firmenbuch: ввести ключ и нажать Проверить соединение. Затем выбрать канал, параметры, ключевые слова и коды позиций.

odoo-bin -c /etc/odoo/odoo.conf -d <база_данных> -i partner_firmenbuch_at --stop-after-init

Важно для рабочих систем: первый запуск обновления адресного реестра стартует автоматически в ночь после установки в 03:15 и загружает около 120 МБ. После этого проверяются все австрийские контакты; замечания отображаются как предложения и одно сообщение в канале. Кто этого не хочет, заранее отключает запланированное действие Адресный реестр (BEV): обновить или выключает Проверять австрийские адреса в настройках.

Массовый импорт: импортируйте с ключами контекста fb_no_lookup=True и bev_no_check=True. Иначе каждая импортированная австрийская компания была бы поставлена в очередь на запрос в реестр (20 за десять минут), а каждый адрес проверялся бы при создании.

Защита данных: что модуль отправляет и кому

• Персональные данные: имена директоров являются персональными данными, даже если они публично указаны в реестре. Модуль сохраняет их только для поддержания деловых отношений. Кто этого не хочет, удаляет поле или не использует его.
• Firmenbuch: только название или номер Firmenbuch контактов, помеченных как компания (без вышестоящей компании, страна Австрия или не указана), передаётся на justizonline.gv.at вместе с ключом API. Физические лица и контактные лица компании никогда не передаются.
• Адресный реестр: загружается только публичная выгрузка. Адреса клиентов не покидают систему.
• Никаких писем клиентам: сообщения направляются во внутренний канал, в Chatter и в виде задачи сотрудникам.
• Ключ: ключ API виден только администраторам.

Firmenbuch — публичный реестр. Повторное использование данных регулируется условиями Informationsweiterverwendung на JustizOnline.

Тесты

В комплект модуля входят 18 автоматических тестов. Они работают с воссозданными ответами реестра и миниатюрной адресной выгрузкой, поэтому не требуют ни ключа API, ни сети:

• Нормализация номера Firmenbuch
• Обработка выписки (название, адрес, суд, директор, исключённая компания, недействительные записи игнорируются)
• Сравнение названий: варианты написания организационно-правовой формы, «in Liqu.», HTML-символы, нет совпадения с чужой компанией
• Годовая отчётность: собственный капитал, результат, сумма баланса
• Новая компания находится, пустые поля заполняются, расхождения предлагаются, предложение применяется частично
• Мониторинг: открытое дело о несостоятельности устанавливает уровень критический и создаёт задачу, прекращённое дело даёт предупреждение, контактные лица отдельно не проверяются
• Изменения документов сопоставляются по ключу
• Без ключа API ничего не запрашивается
• Проверка адресов по миниатюрной выгрузке

odoo-bin -d <тестовая_база> -i partner_firmenbuch_at \
         --test-enable --test-tags=/partner_firmenbuch_at --stop-after-init

Немецкий перевод находится в i18n/de.po.

Ограничения и юридическое примечание

• Совпадение — это подсказка, а не юридическая справка. Статус выводится из ключевых слов в действующих записях реестра. Проверьте реестр самостоятельно, прежде чем принимать решение о кредите или условиях поставки.
• Распознавание несостоятельности проверено только на воссозданных случаях. Модуль распознаёт дела по словам в свободном тексте правовых фактов (открытие, прекращение, утверждённый план санации, из-за отсутствия имущества). Их формат мы воссоздали по настоящей выписке из реестра, однако настоящего случая несостоятельности при разработке у нас под рукой не было. Поэтому необычная формулировка может быть пропущена. Официальную Ediktsdatei модуль не заменяет.
• Годовая отчётность только в формате XML. Подачи исключительно в формате PDF пропускаются. У очень малых обществ баланс может быть подан в сокращённом виде, без цифр, которые считывает модуль.
• Только Австрия. Иностранные компании не запрашиваются. Веб-сайты компаний в реестре не указаны и не добавляются.
• Автоматическое сопоставление только при однозначном совпадении. Если есть несколько компаний с одним и тем же названием, сообщение в канале предлагает выполнить ручной поиск в Firmenbuch.
• Интерфейсы могут измениться. Модуль зависит от служб BMJ и BEV. Если изменятся конечная точка, схема или канал ATOM, может потребоваться обновление.
• Протестировано для Odoo 19. Разработано и протестировано для Odoo 19.0 Community. Для других версий мы его не проверяли. Эта статья не является юридической консультацией.

Часто задаваемые вопросы

Стоит ли доступ к реестру денег?

По нашим сведениям, нет: FBW-WebServices для Informationsweiterverwendung бесплатны, но требуют ключа API, который вы запрашиваете через JustizOnline. Определяющими являются актуальные условия министерства юстиции.

Перезаписываются ли существующие данные контактов?

Нет. Модуль вносит данные только в пустые поля. Отличающиеся значения создаются как предложение, которое сотрудник утверждает по каждому полю отдельно.

Узнают ли мои клиенты о проверке?

Нет. Все сообщения направляются во внутренний канал, в Chatter контакта и в виде задачи сотрудникам. Модуль не отправляет клиентам электронные письма.

Сохраняются ли директора или участники общества?

Имена директоров с полномочиями представительства — да (поле Директор на вкладке Firmenbuch), участники общества и адреса физических лиц — нет. Относитесь к именам как к персональным данным.

Сколько наших клиентов находит модуль?

Это зависит от клиентской базы. У нас это было 138 из 438 контактов компаний (около трети). Остальное — физические лица, индивидуальные предприниматели, иностранные компании и контакты, название которых не соответствует фирменному наименованию. Цифры приведены в разделе Тест на собственной клиентской базе.

Могу ли я найти клиента без номера Firmenbuch?

Да. На вкладке Firmenbuch есть кнопка Поиск в Firmenbuch с поиском по названию. Модуль автоматически вносит данные только в том случае, если подходит ровно одна компания. В остальных случаях вы выбираете совпадение сами.

Что с компаниями в Германии или Швейцарии?

Они не запрашиваются. Модуль просматривает только контакты со страной Австрия или без указания страны.

Сколько памяти требует проверка адресов?

С номерами домов около 400 МБ в базе данных и около 120 МБ временного дискового пространства при импорте. Без проверки номеров домов хватает примерно 150 000 строк.

Что, если мне нужен только Firmenbuch, а проверка адресов не нужна?

Отключите Проверять австрийские адреса в настройках и деактивируйте запланированное действие для адресного реестра. Тогда ничего не будет загружаться.

Под какой лицензией распространяется модуль?

Под LGPL-3. Вы можете использовать, изменять и распространять его. Сообщения об ошибках и предложения по улучшению приветствуются в виде issue в репозитории GitHub .

Поддержка от Biricon IT Services

Мы обслуживаем установки Odoo для малых и средних предприятий: от внедрения через доработки и миграции до постоянной эксплуатации. Если вы хотите поддерживать основные данные клиентов в Odoo в порядке, раньше выявлять риски платёжеспособности или проверить подобный модуль и безопасно внедрить его в рабочий экземпляр, мы охотно поддержим вас. Другие наши собственные разработки вы найдёте в нашем блоге, например Наборы продуктов в коммерческом предложении как раздел и Web RBL — чёрный список для вредоносного трафика.

Связаться с нами

По состоянию на 3 ноября 2026 г. Версия модуля 19.0.1.1.1. Примеры данных на иллюстрациях выбраны произвольно и не относятся к настоящим компаниям.