Odoo 19 Community: Firmenbuch i verificació d’adreces per a clients austríacs – el nostre mòdul de codi obert partner_firmenbuch_at

Qui fa negocis a Àustria coneix les preguntes: la raó social i l’adreça del meu nou client són correctes? L’empresa encara consta al Firmenbuch o està en liquidació? S’ha obert un procediment d’insolvència contra el client al qual subministro des de fa dos anys? Les respostes són al Firmenbuch del Ministeri de Justícia, però gairebé ningú no hi mira regularment. A Odoo el contacte es crea una vegada i després envelleix.

Per això hem desenvolupat el mòdul Firmenbuch per a partners (partner_firmenbuch_at). Connecta els contactes d’Odoo amb el Firmenbuch i amb el registre oficial d’adreces del BEV. Està escrit per a Odoo 19 i es troba disponible gratuïtament a GitHub com a programari lliure sota la llicència LGPL-3:

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

El problema: dades mestres que ningú manté

Un contacte a Odoo sol néixer amb pressa: nom, adreça aproximada, potser un UID. Això és suficient per al primer pressupost. No és suficient per a factures, que han d’estar adreçades de manera jurídicament correcta, i encara menys per adonar-se que alguna cosa ha canviat al client. A la pràctica apareixen quatre llacunes:

• Dades mestres incompletes. El número del Firmenbuch, el tribunal i la forma jurídica gairebé sempre falten, perquè la consulta és feina manual.
• Grafies incorrectes. Raó social sense forma jurídica, errors tipogràfics al carrer o a la localitat, codi postal intercanviat. Només ho notem quan el correu ens retorna.
• Cap seguiment. Si un tribunal obre un procediment d’insolvència o un client dissol la seva societat, Odoo no se n’assabenta. Vendes continua lliurant a crèdit.
• Fonts disperses. El Firmenbuch, els comptes anuals i el registre d’adreces es troben en llocs diferents. Qui els vol comprovar copia dades a mà entre finestres del navegador.

Què fa el mòdul

1. Les empreses noves es consulten. Si algú crea un contacte com a empresa (país Àustria o buit), el mòdul el cerca al Firmenbuch en pocs minuts. Si hi ha exactament una coincidència, s’ompleixen els camps buits: carrer, codi postal, localitat, país, número del Firmenbuch, tribunal i forma jurídica.
2. Les discrepàncies es proposen, mai se sobreescriuen. Si al contacte consta una cosa diferent del que hi ha al registre, es crea un suggeriment de canvi que un empleat valida camp per camp.
3. Cerca al Firmenbuch des del contacte. A la pestanya Firmenbuch, la cerca troba empreses per nom, fins i tot si la coincidència automàtica no era unívoca.
4. Vigilància diària. El mòdul consulta diàriament quines empreses i documents han canviat al registre i comprova els clients afectats. A més, a intervals configurables es torna a comprovar totalment cada empresa.
5. Nivells d’avís. Es detecten procediments d’insolvència i de sanejament oberts (a partir dels fets jurídics del registre), liquidació, cancel·lació, fons propis negatius i una ràtio de fons propis baixa, i es fan visibles al contacte.
6. Verificació d’adreces. Les adreces austríaques es comproven localment amb el registre oficial d’adreces de l’Oficina Federal de Metrologia i Cartografia (BEV).
7. Dades del registre al contacte. El tribunal, la forma jurídica, la gerència i els fets jurídics es troben a la pestanya Firmenbuch. Reflecteixen el registre i s’actualitzen directament.
8. Avisos només cap a dins. Tots els missatges van al canal intern de Discuss Firmenbuch i al chatter del contacte. Una execució de comprovació sobre moltes empreses genera un missatge col·lectiu en lloc d’un per empresa. El mòdul mai no envia res als clients.

Suggeriments en lloc de sobreescriure

Les dades oficials no són automàticament les millors dades per al vostre negoci: potser al contacte hi consta deliberadament l’adreça de lliurament, potser s’hi ha introduït un nom abreujat. Per això el mòdul mai no canvia per si mateix els valors existents. Només completa camps buits i, en cas de discrepància, crea un suggeriment.

A Contactes → Firmenbuch → Suggeriments del Firmenbuch veieu, per camp, el valor actual i el valor del registre. Els camps que no voleu adoptar els deixeu desmarcats. Amb Aplica els seleccionats només s’escriuen els camps marcats; amb Rebutja el suggeriment caduca. Un suggeriment nou substitueix els suggeriments oberts més antics del mateix contacte, perquè no s’apliquin valors obsolets.

Avisos: insolvència, liquidació, balanç

El mòdul distingeix tres nivells:

• Sense incidències: No hi ha res a comunicar.
• Avís (groc): Al registre hi ha inscripcions vàlides de liquidació, dissolució, extinció, cancel·lació o fusió, l’empresa està marcada com a cancel·lada, o un procediment d’insolvència anterior es va aixecar en els darrers anys (per defecte tres anys, configurable). O bé els comptes anuals mostren fons propis negatius, una ràtio de fons propis inferior al 8 % (valor per defecte d’acord amb el § 23 URG, configurable), una pèrdua anual o una caiguda de la facturació del 25 % o més.
• Crític (vermell): S’ha obert un procediment d’insolvència, de fallida o de sanejament que encara no s’ha aixecat, o una sol·licitud ha estat desestimada per manca de patrimoni que cobreixi les despeses. Això últim compta com a insolvència.

Al contacte apareix un bàner de color, a la llista de contactes un avís, i a la cerca hi ha filtres per a Avís del Firmenbuch i Firmenbuch crític. Si un client passa a crític, el venedor responsable (en el seu defecte, l’administrador) rep una activitat Firmenbuch: revisar clients, i el canal Firmenbuch rep un missatge.

Fets jurídics. Al registre, els procediments d’insolvència no consten al text de l’empresa, sinó com a fets jurídics amb data, número d’expedient i tribunal. El mòdul els llegeix, assigna l’obertura i l’aixecament al mateix número d’expedient i els mostra al contacte com a llista. Així, un procediment aixecat al cap d’uns anys queda només com a informació; un procediment en curs és vermell.

Comptes anuals. Si els últims comptes anuals estan disponibles en XML, el mòdul n’extreu els fons propis, el resultat de l’exercici, el total del balanç i la facturació, i calcula la ràtio de fons propis, la variació de la facturació i la classe de mida segons el § 221 UGB (també microsocietats). Les societats petites no han de publicar la seva facturació; aleshores el mòdul no en mostra. El seu resultat el dedueix del resultat del balanç menys el romanent de beneficis i el marca com a estimació. Els noms de les posicions que se cerquen són configurables, perquè l’XML té una estructura diferent segons el formulari.

Verificació d’adreces amb el registre d’adreces del BEV

El BEV posa el registre d’adreces a disposició com a dades obertes (Adresse Relationale Tabellen – Stichtagsdaten, nova data de referència dues vegades l’any, d’ús gratuït amb indicació de la font). El mòdul baixa l’extracte mitjançant el servei oficial INSPIRE-ATOM, uns 120 MB amb unes 2,5 milions d’adreces, i l’importa a taules pròpies i lleugeres.

Després, cada adreça d’empresa austríaca amb carrer es comprova localment en crear-la i a cada canvi: codi postal, carrer, número de porta, localitat i estat federat. Cap adreça no s’envia a cap servei. El resultat consta com a indicador sota l’adreça:

• Vàlida: L’adreça existeix així al registre.
• Número de porta desconegut: El carrer i la localitat coincideixen, el número de porta no.
• Correcció suggerida: Error tipogràfic al carrer o a la localitat, codi postal incorrecte. La correcció queda preparada com a suggeriment.
• No trobada: El registre no coneix aquesta adreça.

Un estat federat buit es completa directament. Les adreces de contacte privades (tipus Adreça privada) no es comproven. La indicació de la font © Österreichisches Adressregister, Stichtagsdaten vom … consta amb la data de referència actual a la configuració. L’actualització s’executa setmanalment, però només baixa si el BEV ha publicat una data de referència més recent.

Implementació tècnica

L’accés al registre

El Ministeri de Justícia ofereix el Firmenbuch mitjançant els FBW-WebServices (HVD) a JustizOnline com a interfície SOAP. L’accés és gratuït, però requereix una clau d’API que se sol·licita amb ID Austria a Informationsweiterverwendung. La clau s’envia a la capçalera HTTP X-API-KEY. El mòdul utilitza el servei directament, sense screen scraping.

El client models/firmenbuch_client.py és Python pur sense dependència d’Odoo. Coneix les consultes SUCHEFIRMAREQUEST, AUSZUG_V2_REQUEST, SUCHEURKUNDEREQUEST, URKUNDEREQUEST, així com VERAENDERUNGENFIRMAREQUEST i VERAENDERUNGENURKUNDEREQUEST. Així es pot provar amb respostes desades. Les sol·licituds es fan amb un interval de 0,3 segons, i les consultes de canvis, en blocs de set dies.

Interpretació de l’extracte

De l’extracte només s’utilitzen inscripcions que encara són vàlides (atribut AUFRECHT no és false). El nom prové de l’indicador de dades FI_DKZ02, l’adreça de FI_DKZ03, la seu de FI_DKZ06 i la forma jurídica de FI_DKZ07. A això s’hi afegeixen el tribunal, l’adreça web, les persones amb poder de representació i els fets jurídics. Per al nivell d’avís, els textos de totes les inscripcions vàlides es cerquen segons les paraules clau configurables:

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

L’avantatge de la comprovació per paraules clau: funciona independentment del camp en què el registre porti un tràmit. El desavantatge consta a la secció Límits.

Vigilància

El mòdul crea tres accions planificades:

• Cercar empreses noves (cada 10 minuts, fins a 20 contactes per execució). A més, s’activa immediatament en crear-les.
• Vigilar empreses (cada dia a les 04:30). Consulta les empreses i els documents canviats des de l’última execució (com a màxim 30 dies enrere), comprova els clients afectats i després fins a 50 clients l’última comprovació dels quals sigui anterior al termini configurat. Cada empresa es desa en una transacció pròpia, perquè un error no faci perdre resultats anteriors. El resultat de l’execució arriba al canal com un missatge col·lectiu.
• Actualitzar el registre d’adreces (setmanalment a les 03:15).

Sense clau d’API, les dues primeres tornen immediatament. Una suma de verificació per empresa evita que s’interpretin de nou extractes sense canvis.

El registre d’adreces

Les dades del BEV es troben en tres taules (bev.locality, bev.street, bev.address) amb un índex sobre el codi postal, el codi de carrer i el número de porta. La importació s’executa mitjançant COPY en una transacció, de manera que les taules se substitueixen en un sol pas. Els números de porta es normalitzen a la grafia del registre (51-55, 12a). Amb números de porta, les taules ocupen uns 400 MB a la base de dades. Qui no ho vulgui, desactiva Comprova els números de porta i se’n surt amb unes 150.000 files.

Què ens ha ensenyat el servei real

Un mòdul que només s’ha provat amb respostes de prova escrites per nosaltres encara no es considera acabat. Per això, abans de publicar-lo vam provar el client amb el servei real, amb la clau de la nostra pròpia empresa. En fer-ho van aparèixer diverses discrepàncies respecte de les nostres suposicions, que hem corregit:

• Només la informació breu. L’extracte només es pot consultar amb aquesta clau en l’abast informació breu. El servei rebutja les sol·licituds amb informació completa. A la versió 1.0.0, l’execució diària ho sol·licitava encara de manera incorrecta; la versió 1.1.0 ho corregeix. De les persones, el mòdul només n’extreu els noms dels gerents amb poder de representació; els socis i les adreces de persones no es llegeixen.
• Carrer i número de porta per separat. L’adreça arriba com a STRASSE i HAUSNUMMER en elements separats, no com un sol text. El mòdul ajunta tots dos.
• Tribunal a l’execució. El tribunal competent no consta a la part de l’empresa, sinó a l’últim bloc VOLLZ de l’extracte.
• Empreses cancel·lades. Una empresa cancel·lada es reconeix per un atribut (MIT_FIRMA_GELOESCHT_DURCH_VNR) i no per un text. El mòdul en fa la constatació Empresa cancel·lada, que desencadena un avís.
• El nom de l’empresa no és la paraula de cerca. La cerca compara l’inici del nom. «Muster GmbH» no troba res si el registre escriu «Muster Gesellschaft m.b.H.»; les empreses en liquidació porten «in Liqu.» al nom, i al nom del contacte a vegades encara hi ha &. Per això el mòdul repeteix la cerca sense forma jurídica i compara noms sense variants d’escriptura de la forma jurídica, sense caràcters HTML i sense l’afegit «in Liqu.». Una coincidència única només s’adopta si el seu nom comença igual que el del contacte.
• Canvis de documents sense número del Firmenbuch. La llista de documents canviats només conté una clau. El número del Firmenbuch (sense lletres de verificació) es troba al començament d’aquesta clau. El mòdul hi assigna els canvis als clients.

Per a cadascun d’aquests punts hi ha ara una prova automatitzada amb una resposta simulada.

La prova amb la nostra pròpia base de clients

Després de la versió 1.1.0, vam provar el mòdul amb la nostra pròpia base de clients. Primer es va executar només una cerca de noms en mode de lectura, després l’assignació de les coincidències unívoques. No es va canviar res sense tenir en compte els valors existents: es van completar camps buits, les discrepàncies queden preparades com a suggeriments per validar i no va sortir ni un sol correu electrònic. El resultat, sense esmentar empreses concretes:

• Es van cercar 438 contactes d’empresa amb estat de client a Àustria o sense país.
• 138 d’aquests es van assignar de manera unívoca al Firmenbuch. Altres 18 tenien una coincidència de nom unívoca, però una altra adreça al registre (trasllat o empresa homònima), i per això es van deixar intactes. 2 noms són ambigus.
• Uns 280 no els vam trobar o només com a coincidència parcial. Són particulars, empreses individuals, empreses estrangeres, contactes que només esmenten una marca o un lloc, i empreses el nom de les quals al contacte difereix de la inscripció, per exemple perquè hi consta una altra forma jurídica. Per a aquests queda la Cerca al Firmenbuch manual.
• Es van generar 63 suggeriments de canvi, sobretot per al carrer i el número de porta (grafia) i per al país.
• 66 avisos, cap nivell crític. 36 empreses consten al registre com a cancel·lades (9 d’elles també en liquidació), 2 havien tingut un procediment d’insolvència ja aixecat i en 42 van cridar l’atenció els comptes anuals: ràtio de fons propis baixa, pèrdua o caiguda de la facturació. Una empresa cancel·lada no és automàticament un client perdut, però sí un motiu per revisar l’adreça i el destinatari de les factures.

Dues lliçons: una base de clients d’una activitat real és una prova molt millor que qualsevol resposta simulada. Hi vam trobar errors a la cerca de noms, que s’han corregit a la versió 1.1.1 (vegeu més amunt). I la taxa d’encerts depèn molt de com de curosament s’hagin anomenat els contactes: qui escriu la raó social tal com la porta el registre és trobat de manera fiable.

Instal·lació i configuració

Requisits: Odoo 19.0 amb les aplicacions estàndard Contactes i Discuss, el paquet Python requests (present a qualsevol instal·lació d’Odoo) i accés HTTPS sortint a justizonline.gv.at i data.bev.gv.at. El mòdul no té dependències fora de les aplicacions estàndard, de manera que no arrossega cap altre mòdul.

1. Col·locar la carpeta partner_firmenbuch_at a l’addons_path, actualitzar la llista d’aplicacions i instal·lar el mòdul; en sistemes de producció, millor primer en una base de dades de prova.
2. El mòdul crea el canal de Discuss Firmenbuch (usuaris interns) i hi afegeix tots els administradors. A més, es creen les tres accions planificades.
3. Sol·licitar la clau d’API: JustizOnline (ID Austria), Informationsweiterverwendung, API FBW.
4. Configuració → Firmenbuch: introduir la clau i Prova la connexió. Després, triar el canal, les opcions, les paraules clau i els codis de posició.

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

Important en sistemes de producció: La primera execució de l’actualització del registre d’adreces s’inicia automàticament la nit després de la instal·lació, a les 03:15, i baixa uns 120 MB. Després es comproven tots els contactes austríacs; les anomalies apareixen com a suggeriments i com a un missatge al canal. Qui no ho vulgui, desactiva abans l’acció planificada Registre d’adreces (BEV): actualitzar o desactiva Comprova les adreces austríaques a la configuració.

Importacions massives: Importeu amb les claus de context fb_no_lookup=True i bev_no_check=True. En cas contrari, cada empresa austríaca importada es reservaria per a una consulta al registre (20 cada deu minuts) i cada adreça es comprovaria en crear-la.

Protecció de dades: què envia el mòdul i a qui

• Dades personals: Els noms dels gerents són dades personals, tot i que siguin públics al registre. El mòdul només els desa per mantenir la relació comercial. Qui no ho vulgui, esborra el camp o no l’utilitza.
• Firmenbuch: Només el nom o el número del Firmenbuch dels contactes marcats com a empresa (sense empresa superior, país Àustria o buit) s’envia a justizonline.gv.at, juntament amb la clau d’API. Els particulars i les persones de contacte d’una empresa no s’envien mai.
• Registre d’adreces: Només es baixa l’extracte públic. Les adreces dels clients no surten del sistema.
• Cap correu als clients: Els avisos van al canal intern, al chatter i com a activitat als empleats.
• Clau: La clau d’API només és visible per als administradors.

El Firmenbuch és un registre públic. La reutilització de les dades està subjecta a les condicions de la Informationsweiterverwendung de JustizOnline.

Proves

El mòdul inclou 18 proves automatitzades. Treballen amb respostes de registre simulades i un extracte d’adreces en miniatura, i per això no necessiten ni clau d’API ni xarxa:

• Normalització del número del Firmenbuch
• Interpretació de l’extracte (nom, adreça, tribunal, gerent, empresa cancel·lada, s’ignoren les inscripcions no vàlides)
• Comparació de noms: variants d’escriptura de la forma jurídica, «in Liqu.», caràcters HTML, cap coincidència amb una empresa aliena
• Comptes anuals: fons propis, resultat, total del balanç
• Es troba una empresa nova, es completen camps buits, es proposen les discrepàncies, el suggeriment s’aplica parcialment
• Vigilància: un procediment d’insolvència obert fixa el nivell a crític i genera l’activitat, un procediment aixecat dona lloc a un avís, les persones de contacte no es comproven expressament
• Els canvis de documents s’assignen mitjançant la clau
• Sense clau d’API no es consulta res
• Verificació d’adreces amb l’extracte en miniatura

odoo-bin -d <testdatenbank> -i partner_firmenbuch_at \
         --test-enable --test-tags=/partner_firmenbuch_at --stop-after-init

La traducció alemanya es troba a i18n/de.po.

Límits i avís legal

• Una coincidència és un indici, no una informació jurídica. L’estat es deriva de paraules clau en inscripcions vàlides del registre. Comproveu el registre vosaltres mateixos abans de decidir sobre crèdit o condicions de lliurament.
• Detecció d’insolvència només provada amb casos simulats. El mòdul reconeix els procediments per paraules al text lliure dels fets jurídics (obertura, aixecament, pla de sanejament confirmat, per manca de patrimoni). Vam simular-ne el format a partir d’un extracte real del registre, però durant el desenvolupament no vam tenir a mà cap cas real d’insolvència. Per això, una formulació inusual pot passar desapercebuda. El mòdul no substitueix l’Ediktsdatei oficial.
• Comptes anuals només en XML. Les presentacions només en PDF s’ometen. En societats molt petites, el balanç es pot haver presentat abreujat, sense les xifres que llegeix el mòdul.
• Només Àustria. Les empreses estrangeres no es consulten. Els llocs web de les empreses no consten al registre i no es completen.
• Assignació automàtica només amb coincidència unívoca. Si hi ha diverses empreses amb el mateix nom, un missatge al canal remet a la Cerca al Firmenbuch manual.
• Les interfícies poden canviar. El mòdul depèn dels serveis del BMJ i del BEV. Si canvien el punt final, l’esquema o el feed ATOM, pot ser necessària una actualització.
• Provat per a Odoo 19. Desenvolupat i provat per a Odoo 19.0 Community. No l’hem comprovat per a altres versions. L’article no constitueix assessorament jurídic.

Preguntes freqüents

L’accés al registre costa alguna cosa?

Segons la nostra informació, no: els FBW-WebServices per a la Informationsweiterverwendung són gratuïts, però necessiten una clau d’API que se sol·licita a través de JustizOnline. Són determinants les condicions vigents del Ministeri de Justícia.

Se sobreescriuen les dades de contacte existents?

No. El mòdul només escriu en camps buits. Els valors diferents es creen com a suggeriment que un empleat valida camp per camp.

Els meus clients s’assabenten de la comprovació?

No. Tots els avisos van al canal intern, al chatter del contacte i com a activitat als empleats. El mòdul no envia cap correu electrònic als clients.

Es desen gerents o socis?

Els noms dels gerents amb poder de representació sí (camp Geschäftsführer a la pestanya Firmenbuch); els socis i les adreces de persones, no. Tracteu els noms com a dades personals.

Quants dels nostres clients troba el mòdul?

Depèn de la base de clients. A nosaltres en van ser 138 de 438 contactes d’empresa (aproximadament un terç). La resta són particulars, empreses individuals, empreses estrangeres i contactes el nom dels quals no coincideix amb la raó social. Les xifres consten a la secció La prova amb la nostra pròpia base de clients.

Puc trobar un client sense número del Firmenbuch?

Sí. La pestanya Firmenbuch té el botó Cerca al Firmenbuch amb cerca per nom. El mòdul només registra automàticament si coincideix exactament una empresa. En cas contrari, trieu vosaltres mateixos la coincidència.

Què passa amb les empreses d’Alemanya o de Suïssa?

No es consulten. El mòdul només mira contactes amb país Àustria o sense país.

Quanta memòria necessita la verificació d’adreces?

Amb números de porta, uns 400 MB a la base de dades i, durant la importació, uns 120 MB d’espai temporal al disc. Sense la comprovació de números de porta, n’hi ha prou amb unes 150.000 files.

Què passa si només vull el Firmenbuch i no la verificació d’adreces?

Desactiveu Comprova les adreces austríaques a la configuració i desactiveu l’acció planificada del registre d’adreces. Aleshores no es baixa res.

Sota quina llicència es troba el mòdul?

Sota la LGPL-3. Podeu utilitzar-lo, adaptar-lo i distribuir-lo. Els errors i els suggeriments de millora són benvinguts com a issue al repositori de GitHub .

Suport de Biricon IT Services

Gestionem instal·lacions d’Odoo per a petites i mitjanes empreses: des de la implantació, passant per les adaptacions i les migracions, fins a l’explotació contínua. Si voleu mantenir netes les dades mestres dels clients a Odoo, detectar abans els riscos de solvència o revisar un mòdul com aquest i posar-lo amb seguretat a la vostra instància de producció, us ajudarem amb gust. Trobareu més desenvolupaments propis al nostre blog, per exemple Conjunts de productes al pressupost com a secció i Web RBL, la llista de bloqueig per al trànsit d’atac.

Poseu-vos en contacte amb nosaltres

Data: 3 de novembre de 2026. Versió del mòdul 19.0.1.1.1. Les dades d’exemple de les il·lustracions són d’elecció lliure i no són empreses reals.