Odoo 19 Community: Registre Mercantil 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 aquestes preguntes: són correctes la denominació social i l'adreça del meu nou client? L'empresa encara consta al registre mercantil o està en liquidació? S'ha obert un procediment d'insolvència contra el client a qui fa dos anys que subministro productes? Les respostes són al registre mercantil del Ministeri de Justícia, però gairebé ningú no el consulta periòdicament. A Odoo, el contacte es crea una vegada i, a partir d'aquí, les dades van quedant desactualitzades.

Per això hem desenvolupat el mòdul Firmenbuch für Partner (partner_firmenbuch_at). Connecta els contactes d'Odoo amb el registre mercantil i amb el registre oficial d'adreces del BEV. Està desenvolupat per a Odoo 19 i es pot obtenir gratuïtament a GitHub com a programari lliure amb la llicència LGPL-3:

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

El problema: dades mestres que ningú no manté

Els contactes d'Odoo se solen crear amb presses: el nom, una adreça aproximada i potser un número d'identificació a efectes de l'IVA. Això és suficient per al primer pressupost. Però no ho és per a les factures, en què les dades del destinatari han de complir els requisits legals, i encara menys per detectar si ha canviat alguna cosa en la situació del client. A la pràctica, hi ha quatre mancances:

• Dades mestres incompletes. Gairebé sempre hi falten el número d'inscripció al registre mercantil, el jutjat i la forma jurídica, perquè cal consultar-los manualment.
• 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.
• Manca de seguiment. Si un jutjat obre un procediment d'insolvència o un client dissol la seva societat, Odoo no se n'assabenta. L'equip comercial continua subministrant a crèdit.
• Fonts disperses. El registre mercantil, els comptes anuals i el registre d'adreces es troben en llocs diferents. Qui els vol comprovar ha de copiar les dades manualment entre finestres del navegador.

Què fa el mòdul

1. Les empreses noves es cerquen al registre. Quan algú crea un contacte com a empresa (amb Àustria com a país o amb el país en blanc), el mòdul el cerca al registre mercantil austríac en qüestió de minuts. Si hi ha una única coincidència, s'emplenen els camps buits: carrer, codi postal, població, país, número del registre mercantil, jutjat i forma jurídica.
2. Les discrepàncies es proposen com a canvis; mai no se sobreescriuen les dades. Si les dades del contacte difereixen de les del registre, es crea una proposta de canvi que un empleat aprova camp per camp.
3. Cerca al registre mercantil des del contacte. A la pestanya Registre mercantil es poden cercar empreses pel nom, encara que la cerca automàtica no hagi donat una coincidència inequívoca.
4. Seguiment diari. El mòdul consulta diàriament quines empreses i quins documents han canviat al registre i comprova els clients afectats. A més, torna a comprovar completament cada empresa a intervals configurables.
5. Nivells d'alerta. Es detecten els procediments d'insolvència i de reestructuració oberts (a partir dels fets jurídics inscrits al registre), la liquidació, la cancel·lació registral, el patrimoni net negatiu i una ràtio de patrimoni net baixa, i es mostren al contacte.
6. Validació d'adreces. Les adreces austríaques es validen localment amb el registre oficial d'adreces de l'Oficina Federal de Metrologia i Topografia (BEV).
7. Dades registrals al contacte. El jutjat, la forma jurídica, els administradors i els fets jurídics es mostren a la pestanya Registre mercantil. Aquestes dades reflecteixen el contingut del registre i s'actualitzen directament.
8. Notificacions només internes. Tots els missatges s'envien al canal intern de Discuss Registre mercantil i al Chatter del contacte. Una execució que comprova moltes empreses genera un únic missatge de resum en lloc d'un per empresa. El mòdul mai no envia res als clients.

Propostes de canvi en lloc de sobreescriure les dades

Les dades oficials no són necessàriament les més adequades per al vostre negoci: potser al contacte hi consta expressament l'adreça de lliurament, o potser feu servir habitualment un nom abreujat. Per això, el mòdul mai no modifica per si sol els valors existents. Només emplena els camps buits i crea una proposta quan hi ha discrepàncies.

A Contactes → Registre mercantil → Propostes del registre mercantil podeu veure el valor actual i el del registre per a cada camp. Deixeu sense seleccionar els camps que no vulgueu aplicar. Amb Aplica els seleccionats només es desen els camps marcats; amb Rebutja es descarta la proposta. Una proposta nova substitueix les propostes anteriors pendents del mateix contacte per evitar que s'apliquin valors obsolets.

Avisos: insolvència, liquidació i balanç

El mòdul distingeix tres nivells:

• Sense incidències: No hi ha res a comunicar.
• Alerta (groc): Al registre hi ha assentaments vigents de liquidació, dissolució, operacions de liquidació, cancel·lació registral o fusió; l'empresa consta com a cancel·lada, o bé s'ha conclòs un procediment d'insolvència anterior en els darrers anys (tres anys per defecte, configurable). També s'activa si els comptes anuals mostren un patrimoni net negatiu, una ràtio de patrimoni net inferior al 8 % (valor predeterminat basat en l'article 23 de la URG, configurable), pèrdues en l'exercici 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 reestructuració que encara no s'ha conclòs, o bé s'ha desestimat una sol·licitud perquè el patrimoni no cobreix les costes. Aquest darrer cas es considera incapacitat de pagament.

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 Alerta del registre mercantil i Registre mercantil crític. Quan un client passa al nivell crític, el comercial responsable (o, si no n'hi ha, l'administrador) rep una activitat Registre mercantil: revisa els clients, i s'envia un missatge al canal Registre mercantil.

Fets jurídics. Els procediments d'insolvència no figuren al text descriptiu de l'empresa del registre, sinó com a fets jurídics amb data, número d'expedient i jutjat. El mòdul els llegeix, associa l'obertura i la conclusió al mateix número d'expedient i els mostra en una llista al contacte. Així, al cap d'uns anys, un procediment conclòs queda com a informació, mentre que un procediment en curs es mostra en vermell.

Comptes anuals. Si els darrers comptes anuals estan disponibles en XML, el mòdul n'extreu el patrimoni net, el resultat de l'exercici, el total del balanç i la facturació, i calcula la ràtio de patrimoni net, la variació de la facturació i la categoria de mida segons l'article 221 de l'UGB (incloses les microempreses). Les societats petites no estan obligades a publicar la facturació; en aquest cas, el mòdul no en mostra cap. El resultat es dedueix del benefici del balanç menys el romanent de beneficis d'exercicis anteriors i s'indica que és una estimació. Els noms de les partides que es cerquen són configurables, ja que l'estructura de l'XML varia segons el formulari.

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

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

A partir d'aleshores, cada adreça d'empresa austríaca que inclou un carrer es valida localment quan es crea i cada vegada que es modifica: codi postal, carrer, número, població i estat federat. No s'envia cap adreça a cap servei. El resultat es mostra com un indicador sota l'adreça:

• Vàlida: L'adreça consta així al registre.
• Número desconegut: El carrer i la població coincideixen, però el número no.
• Correcció proposada: Hi ha un error tipogràfic al carrer o a la població, o el codi postal és incorrecte. La correcció queda disponible com a proposta.
• No s'ha trobat: Aquesta adreça no consta al registre.

Si el camp de l'estat federat és buit, s'emplena directament. Les adreces particulars dels contactes (tipus Adreça particular) no es validen. La indicació de la font © Registre d'adreces austríac, dades amb data de referència del … apareix a la configuració amb la data de referència actual. L'actualització s'executa setmanalment, però només descarrega dades si el BEV n'ha publicat amb una data de referència més recent.

Implementació tècnica

L'accés al registre

El Ministeri de Justícia ofereix accés al registre mercantil mitjançant els FBW-WebServices (HVD) de JustizOnline, amb una 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 extreure dades de les pàgines web.

El client models/firmenbuch_client.py està escrit íntegrament en Python, sense dependències d'Odoo. Admet les consultes SUCHEFIRMAREQUEST, AUSZUG_V2_REQUEST, SUCHEURKUNDEREQUEST, URKUNDEREQUEST, VERAENDERUNGENFIRMAREQUEST i VERAENDERUNGENURKUNDEREQUEST. Això permet provar-lo amb respostes desades. Les peticions s'envien a intervals de 0,3 segons, i les consultes de canvis es fan en blocs de set dies.

Anàlisi de l'extracte

De l'extracte només s'utilitzen els assentaments que continuen vigents (l'atribut AUFRECHT no és false). El nom s'obté del codi de dades FI_DKZ02; l'adreça, de FI_DKZ03; el domicili social, de FI_DKZ06, i la forma jurídica, de FI_DKZ07. També se n'extreuen el jutjat, l'adreça web, les persones amb poder de representació i els fets jurídics. Per determinar el nivell d'alerta, es cerquen les paraules clau configurables als textos de tots els assentaments vigents:

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 és que funciona independentment del camp on el registre reculli cada acte. L'inconvenient s'explica a l'apartat Limitacions.

Seguiment

El mòdul crea tres accions planificades:

• Cerca empreses noves (cada 10 minuts, fins a 20 contactes per execució). A més, la cerca s'activa immediatament en crear el contacte.
• Supervisa les empreses (cada dia a les 04:30). Consulta les empreses i els documents modificats des de la darrera execució (fins a un màxim de 30 dies enrere), comprova els clients afectats i, després, fins a 50 clients que fa més temps que no es comproven que el termini configurat. Cada empresa es desa en una transacció independent perquè un error no faci perdre els resultats anteriors. El resultat de l'execució s'envia al canal en un únic missatge de resum.
• Actualitza el registre d'adreces (setmanalment a les 03:15).

Sense clau d'API, les dues primeres finalitzen immediatament. Una suma de verificació per empresa evita que es tornin a analitzar extractes que no han canviat.

El registre d'adreces

Les dades del BEV es desen en tres taules (bev.locality, bev.street, bev.address) amb un índex sobre el codi postal, el codi del carrer i el número. La importació es fa mitjançant COPY en una sola transacció, de manera que les taules se substitueixen en un únic pas. Els números es normalitzen segons la notació del registre (51-55, 12a). Amb els números, les taules ocupen uns 400 MB a la base de dades. Si preferiu evitar-ho, desactiveu Comprova els números i n'hi haurà prou amb unes 150.000 files.

Què hem après del 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 informació resumida. Amb aquesta clau, l'extracte només es pot obtenir en la modalitat Kurzinformation. El servei rebutja les peticions de Vollinformation. A la versió 1.0.0, l'execució diària encara feia aquesta petició incorrectament; la versió 1.1.0 ho corregeix. De les persones, el mòdul només incorpora els noms dels administradors amb poder de representació; no llegeix els socis ni les adreces personals.
• Carrer i número separats. L'adreça arriba en elements separats, STRASSE i HAUSNUMMER, en lloc d'un únic text. El mòdul els combina.
• Jutjat al bloc de tramitació. El jutjat competent no figura a la secció de l'empresa, sinó al darrer bloc VOLLZ de l'extracte.
• Empreses cancel·lades. Una empresa cancel·lada s'identifica mitjançant un atribut (MIT_FIRMA_GELOESCHT_DURCH_VNR), no pas amb un text. El mòdul el converteix en la indicació Empresa cancel·lada, que activa una alerta.
• El nom de l'empresa no és el terme de cerca. La cerca compara l'inici del nom. «Muster GmbH» no dona cap resultat si al registre hi consta «Muster Gesellschaft m.b.H.»; les empreses en liquidació porten «in Liqu.» al nom, i de vegades al nom del contacte encara hi ha &. Per això, el mòdul repeteix la cerca sense la forma jurídica i compara els noms sense les variants de la forma jurídica, sense caràcters HTML i sense l'afegit «in Liqu.». Una coincidència única només s'accepta si el nom comença amb el del contacte.
• Canvis en documents sense número del registre mercantil. La llista de documents modificats només conté una clau. El número del registre mercantil (sense la lletra de control) figura al principi d'aquesta clau. El mòdul l'utilitza per associar els canvis als clients.

Ara, cadascun d'aquests punts té una prova automatitzada amb una resposta simulada.

La prova amb la nostra cartera de clients

Després de la versió 1.1.0, vam provar el mòdul amb la nostra cartera de clients. Primer vam executar una cerca de noms només de lectura i, després, vam associar les coincidències inequívoques. En tot moment es van respectar els valors existents: es van emplenar els camps buits, les discrepàncies van quedar com a propostes pendents d'aprovació i no es va enviar ni un sol correu electrònic. Aquests són els resultats, sense identificar cap empresa:

• Es van cercar 438 contactes d'empresa amb condició de client, amb Àustria com a país o sense país indicat.
• 138 es van associar de manera inequívoca al registre mercantil. Uns altres 18 tenien una coincidència única pel nom, però una adreça diferent al registre (per un trasllat o perquè es tractava d'una empresa amb el mateix nom) i, per tant, no es van modificar. Hi ha 2 noms ambigus.
• Uns 280 no es van trobar o només van donar coincidències parcials. Es tracta de particulars, empresaris individuals, empreses estrangeres, contactes que només indiquen una marca o una població i empreses amb un nom al contacte que difereix de la denominació inscrita, per exemple perquè hi consta una altra forma jurídica. Per a aquests casos queda la Cerca al registre mercantil manual.
• Es van generar 63 propostes de canvi, sobretot per al carrer i el número (grafia) i el país.
• 66 alertes, cap cas crític. Al registre hi ha 36 empreses marcades com a cancel·lades (9 de les quals també en liquidació), 2 havien tingut un procediment d'insolvència que ja s'ha conclòs i en 42 es van detectar incidències als comptes anuals: ràtio de patrimoni net baixa, pèrdues o caiguda de la facturació. Una empresa cancel·lada no és necessàriament un client perdut, però sí un motiu per comprovar-ne l'adreça i el destinatari de les factures.

En vam extreure dues lliçons: una cartera de clients d'una empresa en funcionament és una prova molt millor que qualsevol resposta simulada. Hi vam detectar errors en la cerca de noms que s'han corregit a la versió 1.1.1 (vegeu més amunt). A més, la taxa de coincidències depèn molt de la cura amb què s'hagin introduït els noms dels contactes: si la denominació de l'empresa s'escriu tal com consta al registre, es troba de manera fiable.

Instal·lació i configuració

Requisits: Odoo 19.0 amb les aplicacions estàndard Contactes i Discuss, el paquet de Python requests (present en qualsevol instal·lació d'Odoo) i accés HTTPS de sortida 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 instal·la cap mòdul addicional.

1. Col·loqueu la carpeta partner_firmenbuch_at a l'addons_path, actualitzeu la llista d'aplicacions i instal·leu el mòdul. En sistemes de producció, és preferible provar-lo primer en una base de dades de prova.
2. El mòdul crea el canal de Discuss Registre mercantil (per a usuaris interns) i hi afegeix tots els administradors. També crea les tres accions planificades.
3. Sol·liciteu una clau d'API: JustizOnline (ID Austria), Informationsweiterverwendung, API FBW.
4. Configuració → Registre mercantil: introduïu la clau i feu clic a Prova la connexió. Després, trieu el canal, les opcions, les paraules clau i els codis de les partides.

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

Important en sistemes de producció: La primera actualització del registre d'adreces s'inicia automàticament la nit posterior a la instal·lació, a les 03:15, i descarrega uns 120 MB. Després es comproven tots els contactes austríacs; les incidències apareixen com a propostes i en un únic missatge al canal. Si no ho voleu, desactiveu abans l'acció planificada Registre d'adreces (BEV): actualitza o l'opció Valida les adreces austríaques de la configuració.

Importacions massives: Feu la importació amb les claus de context fb_no_lookup=True i bev_no_check=True. En cas contrari, cada empresa austríaca importada quedaria pendent d'una consulta al registre (20 cada deu minuts) i cada adreça es validaria en crear-la.

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

• Dades personals: Els noms dels administradors són dades personals, encara que siguin públics al registre. El mòdul només els desa per mantenir la relació comercial. Si no ho voleu, suprimiu el camp o no el feu servir.
• Registre mercantil: Només s'envia a justizonline.gv.at el nom o el número del registre mercantil dels contactes marcats com a empresa (sense empresa matriu, amb Àustria com a país o amb el país en blanc), juntament amb la clau d'API. No s'envien mai dades de particulars ni de persones de contacte d'una empresa.
• Registre d'adreces: Només es descarrega l'extracte públic. Les adreces dels clients no surten del sistema.
• Cap correu als clients: Les notificacions s'envien al canal intern, al Chatter i als empleats en forma d'activitat.
• Clau: La clau d'API només és visible per als administradors.

El registre mercantil austríac és un registre públic. La reutilització de les dades està subjecta a les condicions de reutilització de la informació de JustizOnline.

Proves

El mòdul inclou 18 proves automatitzades. Utilitzen respostes simulades del registre i un extracte reduït d'adreces, de manera que no necessiten ni clau d'API ni connexió de xarxa:

• Normalització del número del registre mercantil
• Anàlisi de l'extracte (nom, adreça, jutjat, administradors, empresa cancel·lada; s'ignoren els assentaments no vigents)
• Comparació de noms: variants de la forma jurídica, «in Liqu.», caràcters HTML i absència de coincidència amb una empresa diferent
• Comptes anuals: patrimoni net, resultat i total del balanç
• Es troba una empresa nova, s'emplenen els camps buits, es proposen canvis per a les discrepàncies i s'aplica parcialment la proposta
• Seguiment: un procediment d'insolvència obert estableix el nivell crític i genera l'activitat; un procediment conclòs genera una alerta; les persones de contacte no es comproven per separat
• Els canvis en documents s'associen mitjançant la clau
• Sense clau d'API no es fa cap consulta
• Validació d'adreces amb l'extracte reduït

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

La traducció a l'alemany és a i18n/de.po.

Limitacions i avís legal

• Una coincidència és un indici, no un dictamen jurídic. L'estat es dedueix de les paraules clau dels assentaments vigents del registre. Consulteu el registre directament abans de decidir sobre el crèdit o les condicions de lliurament.
• Detecció d'insolvències provada només amb casos simulats. El mòdul identifica els procediments a partir de paraules del text lliure dels fets jurídics (obertura, conclusió, pla de reestructuració homologat, manca de patrimoni). N'hem reproduït el format a partir d'un extracte real del registre, però durant el desenvolupament no vam disposar de cap cas real d'insolvència. Per això, una formulació poc habitual pot passar desapercebuda. El mòdul no substitueix la base de dades oficial d'edictes.
• Comptes anuals només en XML. S'ometen els comptes presentats únicament en PDF. Les societats molt petites poden presentar un balanç abreujat sense les xifres que llegeix el mòdul.
• Només Àustria. No es consulten empreses estrangeres. Els llocs web de les empreses no consten al registre i no s'emplenen.
• Associació automàtica només amb una coincidència inequívoca. Si hi ha diverses empreses amb el mateix nom, un missatge al canal demana que es faci servir la Cerca al registre mercantil manual.
• Les interfícies poden canviar. El mòdul depèn dels serveis del BMJ i del BEV. Si canvien el punt d'accés, l'esquema o el canal ATOM, pot caldre una actualització.
• Provat per a Odoo 19. Desenvolupat i provat per a Odoo 19.0 Community. No l'hem provat amb altres versions. Aquest article no constitueix assessorament jurídic.

Preguntes freqüents

L'accés al registre té cap cost?

Segons la informació de què disposem, no: els FBW-WebServices per a la reutilització de la informació són gratuïts, però requereixen una clau d'API que heu de sol·licitar a través de JustizOnline. En tot cas, prevalen les condicions vigents del Ministeri de Justícia.

Se sobreescriuen les dades existents dels contactes?

No. El mòdul només emplena els camps buits. Els valors discrepants es recullen en una proposta que un empleat aprova camp per camp.

Els meus clients s'assabenten de la comprovació?

No. Totes les notificacions s'envien al canal intern, al Chatter del contacte i als empleats en forma d'activitat. El mòdul no envia correus electrònics als clients.

Es desen les dades dels administradors o dels socis?

Els noms dels administradors amb poders de representació, sí (camp Administradors de la pestanya Registre Mercantil); 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 cartera de clients. En el nostre cas, en va trobar 138 de 438 contactes d'empresa (aproximadament un terç). La resta són particulars, empresaris individuals, empreses estrangeres i contactes el nom dels quals no coincideix amb la raó social. Les xifres es troben a l'apartat La prova amb la nostra cartera de clients.

Puc trobar un client sense el número del Registre Mercantil?

Sí. La pestanya Registre Mercantil té el botó Cerca al Registre Mercantil, que permet cercar pel nom. El mòdul només emplena les dades automàticament si hi ha una única empresa coincident. En cas contrari, heu de seleccionar el resultat.

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

No se'n consulten les dades. El mòdul només revisa els contactes que tenen Àustria com a país o que no tenen cap país indicat.

Quant espai d'emmagatzematge necessita la verificació d'adreces?

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

I si només vull el Registre Mercantil, sense la verificació d'adreces?

Desmarqueu Verifica les adreces austríaques a la configuració i desactiveu l'acció programada del registre d'adreces. Així no es descarregarà res.

Quina llicència té el mòdul?

La LGPL-3. Podeu utilitzar-lo, adaptar-lo i redistribuir-lo. Podeu comunicar errors i proposar millores obrint una incidència al repositori de GitHub són benvinguts.

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 com a secció del pressupost i Web RBL, la llista de bloqueig del trànsit d'atac.

Contacteu amb nosaltres ara

Actualitzat el 3 de novembre de 2026. Versió del mòdul: 19.0.1.1.1. Les dades d'exemple de les imatges són fictícies i no corresponen a empreses reals.