Odoo 19 Community: Firmenbuch і перевірка адрес для австрійських клієнтів – наш модуль з відкритим кодом partner_firmenbuch_at

Хто веде бізнес в Австрії, знає ці запитання: чи правильні назва фірми та адреса мого нового клієнта? Чи фірма ще є у Firmenbuch, чи перебуває в ліквідації? Чи відкрито щодо клієнта, якому я постачаю товари вже два роки, провадження про неплатоспроможність? Відповіді є у Firmenbuch Міністерства юстиції, але мало хто заглядає туди регулярно. В Odoo контакт створюють один раз, а потім він застаріває.

Для цього ми розробили модуль Firmenbuch для партнерів (partner_firmenbuch_at). Він поєднує контакти Odoo з Firmenbuch та з офіційним адресним реєстром BEV. Його написано для Odoo 19, і він безкоштовно доступний на GitHub як вільне програмне забезпечення за ліцензією LGPL-3:

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

Проблема: основні дані, якими ніхто не опікується

Контакт в Odoo зазвичай створюється поспіхом: ім’я, приблизна адреса, можливо, UID. Цього досить для першої пропозиції. Цього не досить для рахунків, які мають бути юридично правильно адресовані, і тим паче для того, щоб помітити, що у клієнта щось змінилося. На практиці виявляються чотири прогалини:

• Неповні основні дані. Номер у Firmenbuch, суд і організаційно-правова форма майже завжди відсутні, бо пошук — це ручна робота.
• Неправильне написання. Назва фірми без організаційно-правової форми, помилки у вулиці чи місті, переплутаний поштовий індекс. Це помічають лише тоді, коли пошта повертається.
• Немає спостереження. Якщо суд відкриває провадження про неплатоспроможність або клієнт ліквідує своє товариство, Odoo про це нічого не знає. Відділ продажів і далі постачає з відстрочкою платежу.
• Розрізнені джерела. Firmenbuch, річна звітність і адресний реєстр містяться в різних місцях. Хто хоче їх перевірити, вручну копіює дані між вікнами браузера.

Що робить модуль

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

Пропозиції замість перезапису

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

У меню Контакти → 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. Модуль використовує службу напряму, без screen scraping.

Клієнт 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 <datenbank> -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. Приватні особи та контактні особи фірми не надсилаються ніколи.
• Адресний реєстр: завантажується лише публічний витяг. Адреси клієнтів не залишають систему.
• Жодних листів клієнтам: повідомлення надходять до внутрішнього каналу, в чат і як активність співробітникам.
• Ключ: ключ API видно лише адміністраторам.

Firmenbuch — це публічний реєстр. Повторне використання даних підпорядковується умовам повторного використання інформації JustizOnline.

Тести

Модуль постачається з 18 автоматизованими тестами. Вони працюють зі змодельованими відповідями реєстру та мініатюрним адресним витягом, тому не потребують ні ключа API, ні мережі:

• Нормалізація номера у Firmenbuch
• Обробка витягу (назва, адреса, суд, директор, виключена фірма, недійсні записи ігноруються)
• Порівняння назв: варіанти написання організаційно-правової форми, «in Liqu.», символи HTML, відсутність збігу для стороннього підприємства
• Річна звітність: власний капітал, результат, сума балансу
• Нову фірму знайдено, порожні поля доповнено, відхилення запропоновано, пропозицію частково застосовано
• Моніторинг: відкрите провадження про неплатоспроможність встановлює рівень критичний і створює активність, скасоване провадження дає попередження, контактні особи окремо не перевіряються
• Зміни документів зіставляються за ключем
• Без ключа API нічого не запитується
• Перевірка адрес за мініатюрним витягом

odoo-bin -d <testdatenbank> -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. Визначальними є чинні умови Міністерства юстиції.

Чи перезаписуються наявні дані контактів?

Ні. Модуль вносить дані лише в порожні поля. Відмінні значення створюються як пропозиція, яку співробітник схвалює окремо для кожного поля.

Чи дізнаються мої клієнти про перевірку?

Ні. Усі повідомлення надходять до внутрішнього каналу, в чат контакту та як активність співробітникам. Модуль не надсилає клієнтам електронних листів.

Чи зберігаються директори або учасники товариства?

Імена директорів, уповноважених представляти фірму, — так (поле Директор на вкладці 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. Приклади даних на ілюстраціях обрано довільно, це не справжні фірми.