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

Кој работи во Австрија, ги знае прашањата: Дали се точни фирменото име и адресата на мојот нов клиент? Дали фирмата сè уште е запишана во Firmenbuch или е во ликвидација? Дали е отворена постапка за стечај над клиентот што го снабдувам веќе две години? Одговорите се наоѓаат во Firmenbuch на Министерството за правда, но речиси никој не проверува редовно. Во Odoo контактот се создава еднаш, а потоа старее.

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

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

Проблемот: матични податоци што никој не ги одржува

Контактот во Odoo најчесто настанува под притисок на време: име, груба адреса, можеби UID. Тоа е доволно за првата понуда. Не е доволно за фактури што мора да бидат правно исправно адресирани, а уште помалку за да се забележи дека кај клиентот нешто се променило. Во пракса се покажуваат четири празнини:

• Нецелосни матични податоци. Бројот во Firmenbuch, судот и правната форма речиси секогаш недостасуваат, бидејќи барањето е рачна работа.
• Погрешно пишување. Фирмено име без правна форма, правописни грешки во улицата или местото, заменет поштенски број. Тоа се забележува дури кога ќе се врати поштата.
• Нема следење. Ако суд отвори постапка за стечај или клиент го распушти друштвото, Odoo не дознава за тоа. Продажбата продолжува да испорачува на фактура.
• Расфрлани извори. Firmenbuch, годишните сметки и адресниот регистар се на различни места. Кој сака да ги провери, рачно копира податоци меѓу прозорците на прелистувачот.

Што прави модулот

1. Новите фирми се бараат. Ако некој создаде контакт како фирма (земја Австрија или празно), модулот во рок од неколку минути бара во Firmenbuch. Ако има точно еден резултат, празните полиња се дополнуваат: улица, поштенски број, место, земја, број во Firmenbuch, суд и правна форма.
2. Отстапувањата се предлагаат, никогаш не се препишуваат. Ако во контактот стои нешто поинакво отколку во регистарот, настанува предлог за промена што вработен го одобрува по поле.
3. Пребарување во Firmenbuch кај контактот. Во табот Firmenbuch пребарувањето наоѓа фирми по име, дури и ако автоматскиот резултат не бил недвосмислен.
4. Дневен надзор. Модулот секој ден проверува кои фирми и документи (Urkunden) се променети во регистарот и ги проверува засегнатите клиенти. Дополнително, во подесливи интервали секоја фирма целосно се проверува одново.
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 го става адресниот регистар на располагање како отворени податоци (Адреса релациони табели – податоци на референтен ден, двапати годишно нов референтен ден, бесплатно за користење со наведување на изворот). Модулот го презема изводот преку официјалната услуга INSPIRE-ATOM, околу 120 MB со приближно 2,5 милиони адреси, и го увезува во сопствени, слабо оптоварени табели.

Потоа секоја австриска фирмена адреса со улица се проверува локално при создавањето и при секоја промена: поштенски број, улица, куќен број, место и сојузна држава. Ниту една адреса не оди до услуга. Резултатот стои како ознака под адресата:

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

Празна сојузна држава се дополнува директно. Приватните адреси на контакти (тип Приватна адреса) не се проверуваат. Наведувањето на изворот © Австриски адресен регистар, податоци на референтен ден од … стои со тековниот референтен ден во поставките. Ажурирањето се одвива неделно, но презема само ако BEV објавил понов референтен ден.

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

Пристапот до регистарот

Министерството за правда го нуди Firmenbuch преку FBW-WebServices (HVD) на JustizOnline како SOAP-интерфејс. Пристапот е бесплатен, но бара API-клуч што се бара со ID Austria под Повторна употреба на информации. Клучот оди во 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.“. Единечен резултат се презема само ако неговото име започнува со она на контактот.
• Промени на документи без број во 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), Повторна употреба на информации, API FBW.
4. Поставки → Firmenbuch: внесете го клучот и кликнете Тестирај врска. Потоа изберете канал, опции, клучни зборови и шифри на позиции.

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 на секои десет минути), а секоја адреса би се проверувала при создавањето.

Заштита на податоците: што модулот испраќа и до кого

• Лични податоци: Имињата на управителите се лични податоци, иако во регистарот се јавно достапни. Модулот ги зачувува само за да ја негува деловната врска. Кој не сака тоа, го брише полето или не го користи.
• Firmenbuch: Само името или бројот во Firmenbuch на контакти означени како фирма (без надредена фирма, земја Австрија или празно) оди до justizonline.gv.at, заедно со API-клучот. Физички лица и контакт-лица на фирма никогаш не се испраќаат.
• Адресен регистар: Се презема само јавниот извод. Адресите на клиентите не го напуштаат системот.
• Нема пораки до клиенти: Известувањата одат во внатрешниот канал, во chatter-от и како активност до вработените.
• Клуч: 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-feed-от, може да се наметне ажурирање.
• Тестирано за Odoo 19. Развиено и тестирано за Odoo 19.0 Community. За други верзии не сме го проверувале. Написот не е правен совет.

Често поставувани прашања

Дали пристапот до регистарот чини нешто?

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

Дали се препишуваат постојните податоци на контактите?

Не. Модулот внесува само во празни полиња. Отстапувачките вредности се создаваат како предлог што вработен го одобрува по поле.

Дали моите клиенти забележуваат нешто од проверката?

Не. Сите известувања одат во внатрешниот канал, во chatter-от на контактот и како активност до вработените. Модулот не испраќа е-пошта до клиенти.

Дали се зачувуваат управители или содружници?

Имињата на управителите овластени за застапување да (поле Управител во табот Firmenbuch), содружниците и адресите на лица не. Постапувајте со имињата како со лични податоци.

Колку од нашите клиенти ги наоѓа модулот?

Тоа зависи од клиентската база. Кај нас беа 138 од 438 фирмени контакти (околу една третина). Остатокот се физички лица, самостојни претприемачи, странски фирми и контакти чие име не одговара на фирменото име. Бројките стојат во делот Тестот врз сопствената клиентска база.

Можам ли да најдам клиент без број во Firmenbuch?

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

Што е со фирмите во Германија или Швајцарија?

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

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

Со куќни броеви околу 400 MB во базата на податоци и при увозот околу 120 MB привремен простор на дискот. Без проверка на куќни броеви стигаат околу 150.000 реда.

Што ако сакам само Firmenbuch, а не проверка на адреси?

Исклучете ја Проверката на австриски адреси во поставките и деактивирајте го закажаното дејство за адресниот регистар. Тогаш ништо не се презема.

Под која лиценца е модулот?

Под LGPL-3. Смеете да го користите, прилагодувате и пренесувате. Грешките и предлозите за подобрување се добредојдени како issue во GitHub-репозиториумот .

Поддршка од Biricon IT Services

Се грижиме за инсталации на Odoo за мали и средни претпријатија: од воведувањето преку прилагодувања и миграции до тековното работење. Ако сакате да ги одржувате чисти матичните податоци на клиентите во Odoo, порано да ги препознавате кредитните ризици или да проверите модул како овој и безбедно да го внесете во вашата производствена инстанца, со задоволство ќе ве поддржиме. Други сопствени развивања ќе најдете во нашиот блог, на пример Сетови производи во понудата како дел и Web RBL, црната листа за нападен сообраќај.

Контактирајте не сега

Состојба: 3 ноември 2026 година. Верзија на модулот 19.0.1.1.1. Примерните податоци на сликите се слободно избрани и не се вистински фирми.