Odoo 19 Community: Търговски регистър и проверка на адреси за австрийски клиенти – нашият модул с отворен код partner_firmenbuch_at

Който прави бизнес в Австрия, знае въпросите: Верни ли са наименованието на фирмата и адресът на новия ми клиент? Все още ли е фирмата вписана в търговския регистър или е в ликвидация? Образувано ли е производство по несъстоятелност срещу клиент, когото снабдявам от две години? Отговорите се намират в търговския регистър (Firmenbuch) на министерството на правосъдието, но почти никой не проверява редовно. В Odoo контактът се създава веднъж и после остарява.

За тази цел разработихме модула Търговски регистър за партньори (partner_firmenbuch_at). Той свързва контактите в Odoo с търговския регистър и с официалния адресен регистър на BEV. Написан е за Odoo 19 и е достъпен безплатно в GitHub като свободен софтуер под лиценза LGPL-3:

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

Проблемът: основни данни, които никой не поддържа

Контактът в Odoo обикновено се създава под натиск на времето: име, приблизителен адрес, може би UID. Това стига за първата оферта. Не стига за фактури, които трябва да са юридически коректно адресирани, и още по-малко, за да се забележи, че при клиента нещо се е променило. На практика се проявяват четири пропуска:

• Непълни основни данни. Номерът в търговския регистър, съдът и правната форма почти винаги липсват, защото търсенето е ръчна работа.
• Грешно изписване. Наименование на фирмата без правна форма, правописни грешки в улица или населено място, разменен пощенски код. Това се забелязва едва когато пощата се върне.
• Липса на наблюдение. Ако съд образува производство по несъстоятелност или клиент прекрати дружеството си, Odoo не научава за това. Търговският отдел продължава да доставя на фактура.
• Пръснати източници. Търговският регистър, годишните финансови отчети и адресният регистър се намират на различни места. Който иска да ги провери, копира данни на ръка между прозорците на браузъра.

Какво прави модулът

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

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

Официалните данни не са автоматично по-добрите данни за вашия бизнес: може би в контакта умишлено е записан адресът за доставка, може би е въведено кратко име. Затова модулът никога не променя сам съществуващи стойности. Той само допълва празни полета и при отклонения създава предложение.

В Контакти → Търговски регистър → Предложения от търговския регистър виждате за всяко поле текущата стойност и стойността от регистъра. Полетата, които не искате да приемете, оставяте без отметка. С Приемане на избраните се записват само маркираните полета, с Отхвърляне предложението отпада. Ново предложение заменя по-старите отворени предложения за същия контакт, за да не се прилагат остарели стойности.

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

Модулът разграничава три нива:

• Без забележки: Няма какво да се съобщава.
• Предупреждение (жълто): В регистъра има валидни вписвания за ликвидация, прекратяване, обявяване в ликвидация, заличаване или сливане, фирмата е означена като заличена или предишно производство по несъстоятелност е било прекратено през последните години (по подразбиране три години, настройваемо). Или годишният финансов отчет показва отрицателен собствен капитал, коефициент на собствения капитал под 8 % (стойност по подразбиране по образец на § 23 URG, настройваемо), годишна загуба или спад на оборота от 25 % и повече.
• Критично (червено): Образувано е производство по несъстоятелност, по фалит или по оздравяване, което още не е прекратено, или молба е била отхвърлена поради липса на имущество, покриващо разноските. Последното се счита за неплатежоспособност.

В контакта се появява цветен банер, в списъка с контакти – бележка, а в търсенето има филтри за Предупреждение от търговския регистър и Търговски регистър: критично. Ако клиент стане критичен, отговорният търговец (при липса – администраторът) получава дейност Търговски регистър: проверка на клиенти, а каналът Търговски регистър получава съобщение.

Правнозначими факти. Производствата по несъстоятелност не стоят в регистъра във фирмения текст, а като правнозначими факти с дата, номер на дело и съд. Модулът ги чете, свързва образуването и прекратяването по един и същ номер на дело и ги показва в контакта като списък. Така едно прекратено производство след няколко години остава само информация, а течащото е червено.

Годишни финансови отчети. Ако последният годишен финансов отчет е налице като XML, модулът чете собствения капитал, годишния резултат, сбора на баланса и оборота и изчислява коефициента на собствения капитал, промяната на оборота и категорията по размер според § 221 UGB (включително микропредприятия). Малките дружества не са длъжни да публикуват оборота си, тогава модулът не показва такъв. Резултата им той извежда от счетоводната печалба минус пренесената печалба и го маркира като приблизителна оценка. Наименованията на позициите, по които се търси, са настройваеми, защото XML има различна структура в зависимост от формуляра.

Проверка на адреси с адресния регистър на BEV

BEV предоставя адресния регистър като отворени данни (Adresse Relationale Tabellen – Stichtagsdaten, два пъти годишно нова референтна дата, безплатно ползване с посочване на източника). Модулът изтегля извлечението през официалната услуга INSPIRE-ATOM, около 120 MB с около 2,5 милиона адреса, и го импортира в собствени, компактни таблици.

След това всеки австрийски фирмен адрес с улица се проверява локално при създаването и при всяка промяна: пощенски код, улица, номер, населено място и федерална земя. Никакъв адрес не се изпраща към услуга. Резултатът се показва като маркировка под адреса:

• Валиден: Адресът съществува в регистъра в този вид.
• Номерът е неизвестен: Улицата и населеното място съвпадат, номерът не.
• Предложена корекция: Правописна грешка в улицата или населеното място, грешен пощенски код. Корекцията е налична като предложение.
• Не е намерен: Регистърът не познава този адрес.

Празна федерална земя се допълва директно. Частните адреси на контакти (тип Частен адрес) не се проверяват. Посочването на източника © Österreichisches Adressregister, Stichtagsdaten vom … е в настройките с текущата референтна дата. Актуализацията се изпълнява седмично, но изтегля само ако BEV е публикувала по-нова референтна дата.

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

Достъпът до регистъра

Министерството на правосъдието предлага търговския регистър чрез 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 MB в базата данни. Който не желае това, изключва Проверка на номерата и се задоволява с около 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.“. Единично съвпадение се приема само ако името му започва с това на контакта.
• Промени в документи без номер в търговския регистър. Списъкът на променените документи съдържа само един ключ. Номерът в търговския регистър (без контролната буква) стои в началото на този ключ. Модулът свързва промените с клиентите чрез него.

За всяка от тези точки вече има автоматизиран тест с имитиран отговор.

Тестът върху собствената клиентска база

След версия 1.1.0 изпробвахме модула върху собствената си клиентска база. Първо се изпълни само търсене по име в режим на четене, след това съпоставянето на еднозначните съвпадения. При това нищо не беше променено без оглед на съществуващите стойности: празните полета бяха допълнени, отклоненията чакат като предложения за одобрение и нито един имейл не беше изпратен. Резултатът, без да назоваваме отделни фирми:

• 438 фирмени контакта със статус на клиент в Австрия или без държава бяха търсени.
• 138 от тях бяха еднозначно съпоставени в търговския регистър. Други 18 имаха еднозначно съвпадение по име, но друг адрес в регистъра (преместване или фирма със същото име) и затова останаха недокоснати. 2 имена са двусмислени.
• Около 280 не намерихме или намерихме само като частично съвпадение. Това са физически лица, еднолични търговци, чуждестранни фирми, контакти, които назовават само марка или населено място, и фирми, чието име в контакта се отклонява от вписаното, например защото там стои друга правна форма. За тях остава ръчното Търсене в търговския регистър.
• 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 Търговски регистър (вътрешни потребители) и записва всички администратори. Освен това се създават трите планирани действия.
3. Заявете API ключ: JustizOnline (ID Austria), Informationsweiterverwendung, API FBW.
4. Настройки → Търговски регистър: въведете ключа и натиснете Тест на връзката. След това изберете канал, опции, ключови думи и кодове на позиции.

odoo-bin -c /etc/odoo/odoo.conf -d <datenbank> -i partner_firmenbuch_at --stop-after-init

Важно в продуктивни системи: Първото изпълнение на актуализацията на адресния регистър стартира автоматично през нощта след инсталирането в 03:15 и изтегля около 120 MB. След това се проверяват всички австрийски контакти; забележките се появяват като предложения и като едно съобщение в канала. Който не желае това, предварително деактивира планираното действие Адресен регистър (BEV): актуализиране или изключва Проверка на австрийските адреси в настройките.

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

Защита на данните: какво изпраща модулът и на кого

• Лични данни: Имената на управителите са лични данни, дори когато са публично достъпни в регистъра. Модулът ги съхранява само за да поддържа търговската връзка. Който не желае това, изтрива полето или не го използва.
• Търговски регистър: Само името или номерът в търговския регистър на контакти, маркирани като фирма (без родителска фирма, държава Австрия или празно), се изпращат до justizonline.gv.at заедно с API ключа. Физически лица и лица за контакт на фирма никога не се изпращат.
• Адресен регистър: Изтегля се само публичното извлечение. Адресите на клиентите не напускат системата.
• Без имейли до клиенти: Съобщенията отиват във вътрешния канал, в чатера и като дейност към служители.
• Ключ: API ключът е видим само за администратори.

Търговският регистър е публичен регистър. Повторното използване на данните е подчинено на условията за повторно използване на информация на JustizOnline.

Тестове

Модулът включва 18 автоматизирани теста. Те работят с имитирани отговори на регистъра и миниатюрно адресно извлечение и затова не изискват нито API ключ, нито мрежа:

• Нормализиране на номера в търговския регистър
• Обработка на извлечението (име, адрес, съд, управител, заличена фирма, невалидните вписвания се игнорират)
• Сравнение на имена: варианти на изписване на правната форма, „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 се пропускат. При много малки дружества балансът може да е подаден в съкратен вид, без числата, които модулът чете.
• Само Австрия. Чуждестранни фирми не се заявяват. Уебсайтовете на фирмите не стоят в регистъра и не се допълват.
• Автоматично съпоставяне само при еднозначно съвпадение. Ако има няколко фирми със същото име, съобщение в канала пита за ръчното Търсене в търговския регистър.
• Интерфейсите могат да се променят. Модулът зависи от услугите на BMJ и BEV. Ако се променят крайна точка, схема или ATOM feed, може да се наложи актуализация.
• Тестван за Odoo 19. Разработен и тестван за Odoo 19.0 Community. За други версии не сме го проверявали. Статията не е правна консултация.

Често задавани въпроси

Струва ли нещо достъпът до регистъра?

Според нашите данни не: FBW-WebServices за повторно използване на информация са безплатни, но изискват API ключ, който заявявате чрез JustizOnline. Меродавни са актуалните условия на министерството на правосъдието.

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

Не. Модулът записва само в празни полета. Отклоняващите се стойности се създават като предложение, което служител одобрява за всяко поле поотделно.

Забелязват ли моите клиенти проверката?

Не. Всички съобщения отиват във вътрешния канал, в чатера на контакта и като дейност към служители. Модулът не изпраща имейли до клиенти.

Съхраняват ли се управители или съдружници?

Имената на управителите с представителна власт – да (поле Управител в раздела Търговски регистър), съдружниците и адресите на лица – не. Третирайте имената като лични данни.

Колко от нашите клиенти намира модулът?

Това зависи от клиентската база. При нас бяха 138 от 438 фирмени контакта (около една трета). Останалите са физически лица, еднолични търговци, чуждестранни фирми и контакти, чието име не отговаря на наименованието на фирмата. Числата са в раздела Тестът върху собствената клиентска база.

Мога ли да намеря клиент без номер в търговския регистър?

Да. Разделът Търговски регистър има бутон Търсене в търговския регистър с търсене по име. Модулът записва автоматично само когато пасва точно една фирма. Иначе сами избирате съвпадението.

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

Те не се заявяват. Модулът разглежда само контакти с държава Австрия или без държава.

Колко памет изисква проверката на адреси?

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

Какво да правя, ако искам само търговския регистър, без проверка на адреси?

Изключете Проверка на австрийските адреси в настройките и деактивирайте планираното действие за адресния регистър. Тогава нищо не се изтегля.

Под какъв лиценз е модулът?

Под LGPL-3. Можете да го използвате, адаптирате и разпространявате. Грешки и предложения за подобрения са добре дошли като issue в хранилището в GitHub .

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

Грижим се за инсталации на Odoo за малки и средни предприятия: от внедряването през адаптациите и миграциите до текущата експлоатация. Ако искате да поддържате основните данни на клиентите в Odoo в ред, да разпознавате по-рано рискове за платежоспособността или да проверите модул като този и да го въведете безопасно във вашата продуктивна инстанция, с удоволствие ще ви подкрепим. Още собствени разработки ще намерите в нашия блог, например Продуктови комплекти в офертата като раздел и Web RBL, списъкът за блокиране на трафик от атаки.

Свържете се с нас

Към: 3 ноември 2026 г. Версия на модула 19.0.1.1.1. Примерните данни в изображенията са произволно избрани и не са истински фирми.