Odoo 19 Community: Firmenbuch e verificación de enderezos para clientes austríacos – o noso módulo de código aberto partner_firmenbuch_at

Quen fai negocios en Austria coñece as preguntas: son correctos a razón social e o enderezo do meu novo cliente? Segue a empresa no Firmenbuch ou está en liquidación? Abriuse un procedemento de insolvencia contra un cliente ao que fornezo desde hai dous anos? As respostas están no Firmenbuch do Ministerio de Xustiza, pero case ninguén o consulta con regularidade. En Odoo o contacto créase unha vez e despois envellece.

Por iso desenvolvemos o módulo Firmenbuch para socios (partner_firmenbuch_at). Conecta os contactos de Odoo co Firmenbuch e co rexistro oficial de enderezos do BEV. Está escrito para Odoo 19 e está dispoñible de balde en GitHub como software libre baixo a licenza LGPL-3:

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

O problema: datos mestres que ninguén mantén

Un contacto en Odoo adoita crearse con présa: nome, enderezo aproximado, quizais un UID. Iso abonda para o primeiro orzamento. Non abonda para facturas que deben ir correctamente enderezadas desde o punto de vista legal, e menos aínda para decatarse de que algo cambiou no cliente. Na práctica aparecen catro carencias:

• Datos mestres incompletos. O número do Firmenbuch, o tribunal e a forma xurídica faltan case sempre, porque buscalos é traballo manual.
• Grafías incorrectas. Razón social sen forma xurídica, erros de escritura na rúa ou na localidade, código postal trocado. Só se nota cando volve o correo.
• Ningunha vixilancia. Se un tribunal abre un procedemento de insolvencia ou un cliente disolve a súa sociedade, Odoo non se entera. Vendas segue fornecendo a crédito.
• Fontes dispersas. O Firmenbuch, as contas anuais e o rexistro de enderezos están en lugares diferentes. Quen quere comprobalos copia datos a man entre ventás do navegador.

O que fai o módulo

1. As empresas novas búscanse. Cando alguén crea un contacto como empresa (país Austria ou baleiro), o módulo busca no Firmenbuch en poucos minutos. Se hai exactamente unha coincidencia, énchense os campos baleiros: rúa, código postal, localidade, país, número do Firmenbuch, tribunal e forma xurídica.
2. As diverxencias propóñense, nunca se sobrescriben. Se no contacto figura algo distinto do que hai no rexistro, créase unha proposta de cambio que un empregado aproba campo por campo.
3. Busca no Firmenbuch desde o contacto. Na lapela Firmenbuch a busca atopa empresas polo nome, mesmo cando a coincidencia automática non foi unívoca.
4. Vixilancia diaria. O módulo consulta cada día que empresas e documentos cambiaron no rexistro e comproba os clientes afectados. Ademais, a intervalos axustables, cada empresa revísase por completo de novo.
5. Niveis de aviso. Detéctanse e móstranse no contacto os procedementos de insolvencia e de saneamento abertos (a partir dos feitos xurídicos do rexistro), a liquidación, a cancelación, o capital propio negativo e un ratio de capital propio baixo.
6. Verificación de enderezos. Os enderezos austríacos compróbanse localmente co rexistro oficial de enderezos do Bundesamt für Eich- und Vermessungswesen (BEV).
7. Datos do rexistro no contacto. O tribunal, a forma xurídica, os xerentes e os feitos xurídicos figuran na lapela Firmenbuch. Reflicten o rexistro e actualízanse directamente.
8. Avisos só cara a dentro. Todas as mensaxes van á canle interna de Discuss Firmenbuch e ao chatter do contacto. Unha pasada de verificación sobre moitas empresas xera unha mensaxe conxunta en vez dunha por empresa. O módulo nunca envía nada aos clientes.

Propostas en vez de sobrescribir

Os datos oficiais non son automaticamente os mellores datos para o seu negocio: quizais no contacto figura deliberadamente o enderezo de entrega, quizais se introduciu un nome curto. Por iso o módulo nunca cambia por si mesmo os valores existentes. Só completa os campos baleiros e, se hai diverxencias, crea unha proposta.

En Contactos → Firmenbuch → Propostas do Firmenbuch ve por campo o valor actual e o valor do rexistro. Deixe sen marcar os campos que non queira aplicar. Con Aplicar os seleccionados só se escriben os campos marcados; con Rexeitar a proposta caduca. Unha proposta nova substitúe as propostas abertas máis antigas do mesmo contacto, para que non se apliquen valores obsoletos.

Avisos: insolvencia, liquidación, balance

O módulo distingue tres niveis:

• Sen incidencias: non hai nada que comunicar.
• Aviso (amarelo): no rexistro hai asentos vixentes sobre liquidación, disolución, cese de actividade, cancelación ou fusión, a empresa está marcada como cancelada, ou un procedemento de insolvencia anterior foi levantado nos últimos anos (por defecto tres anos, axustable). Ou ben as contas anuais amosan capital propio negativo, un ratio de capital propio inferior ao 8 % (valor por defecto en referencia ao § 23 URG, axustable), unha perda anual ou unha caída das vendas do 25 % ou máis.
• Crítico (vermello): un procedemento de insolvencia, de quebra ou de saneamento está aberto e aínda non levantado, ou unha solicitude foi rexeitada por falta de patrimonio que cubra os custos. Isto último conta como insolvencia.

No contacto aparece un banner de cor, na lista de contactos un aviso e na busca hai filtros para Aviso do Firmenbuch e Firmenbuch crítico. Se un cliente pasa a crítico, o comercial responsable (se non o hai, o administrador) recibe unha actividade Firmenbuch: revisar clientes e a canle Firmenbuch recibe unha mensaxe.

Feitos xurídicos. Os procedementos de insolvencia non figuran no rexistro no texto da empresa, senón como feitos xurídicos con data, número de expediente e tribunal. O módulo lééos, asigna a apertura e o levantamento ao mesmo número de expediente e móstraos no contacto como lista. Así, un procedemento levantado pasa a ser só información despois duns anos, e un en curso aparece en vermello.

Contas anuais. Se as últimas contas anuais están dispoñibles como XML, o módulo le o capital propio, o resultado do exercicio, o total do balance e as vendas, e calcula o ratio de capital propio, a variación das vendas e a clase de tamaño segundo o § 221 UGB (tamén microsociedades). As sociedades pequenas non teñen que publicar as súas vendas; entón o módulo non amosa ningunha. O seu resultado dedúceo do beneficio do balance menos o beneficio transferido e márcao como estimación. Os nomes das posicións que se buscan son axustables, porque o XML está estruturado de maneira distinta segundo o formulario.

Verificación de enderezos co rexistro de enderezos do BEV

O BEV ofrece o rexistro de enderezos como datos abertos (Adresse Relationale Tabellen – Stichtagsdaten, nova data de referencia dúas veces ao ano, de uso gratuíto citando a fonte). O módulo descarga o extracto a través do servizo oficial INSPIRE-ATOM, uns 120 MB con aproximadamente 2,5 millóns de enderezos, e impórtao en táboas propias e lixeiras.

Despois, cada enderezo de empresa austríaco con rúa compróbase localmente ao crealo e en cada cambio: código postal, rúa, número, localidade e estado federado. Ningún enderezo se envía a un servizo. O resultado figura como indicador baixo o enderezo:

• Válido: o enderezo existe así no rexistro.
• Número descoñecido: a rúa e a localidade coinciden, o número non.
• Corrección proposta: erro de escritura na rúa ou na localidade, código postal incorrecto. A corrección queda preparada como proposta.
• Non atopado: o rexistro non coñece este enderezo.

Un estado federado baleiro complétase directamente. Os enderezos de contacto privados (tipo Enderezo privado) non se comproban. A indicación da fonte © Österreichisches Adressregister, Stichtagsdaten vom … figura cos datos de referencia actuais nos axustes. A actualización execútase semanalmente, pero só descarga se o BEV publicou unha data de referencia máis recente.

Implementación técnica

O acceso ao rexistro

O Ministerio de Xustiza ofrece o Firmenbuch a través dos FBW-WebServices (HVD) en JustizOnline como interface SOAP. O acceso é gratuíto, pero precisa unha chave de API que se solicita con ID Austria en Informationsweiterverwendung. A chave vai na cabeceira HTTP X-API-KEY. O módulo usa o servizo directamente, sen screen scraping.

O cliente models/firmenbuch_client.py é Python puro sen dependencia de Odoo. Coñece as consultas SUCHEFIRMAREQUEST, AUSZUG_V2_REQUEST, SUCHEURKUNDEREQUEST, URKUNDEREQUEST así como VERAENDERUNGENFIRMAREQUEST e VERAENDERUNGENURKUNDEREQUEST. Por iso pode probarse con respostas gardadas. As solicitudes fanse cun intervalo de 0,3 segundos e as consultas de cambios en bloques de sete días.

Interpretación do extracto

Do extracto só se usan os asentos que aínda son vixentes (atributo AUFRECHT non false). O nome procede do indicador de datos FI_DKZ02, o enderezo de FI_DKZ03, a sede de FI_DKZ06 e a forma xurídica de FI_DKZ07. A isto engádense o tribunal, o enderezo web, as persoas con poder de representación e os feitos xurídicos. Para o nivel de aviso, os textos de todos os asentos vixentes examínanse buscando as palabras clave axustables:

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

A vantaxe da comprobación por palabras clave: funciona con independencia do campo no que o rexistro leve un trámite. O inconveniente figura na sección Límites.

Vixilancia

O módulo crea tres accións planificadas:

• Buscar empresas novas (cada 10 minutos, ata 20 contactos por execución). Ademais, actívase de inmediato ao crear o contacto.
• Vixiar empresas (diariamente ás 04:30). Consulta as empresas e os documentos cambiados desde a última execución (como máximo 30 días atrás), comproba os clientes afectados e despois ata 50 clientes cuxa última comprobación foi hai máis tempo que o prazo configurado. Cada empresa gárdase nunha transacción propia, para que un erro non faga perder resultados anteriores. O resultado da execución chega á canle como unha mensaxe conxunta.
• Actualizar o rexistro de enderezos (semanalmente ás 03:15).

Sen chave de API, as dúas primeiras volven de inmediato. Unha suma de verificación por empresa impide que se volvan avaliar extractos sen cambios.

O rexistro de enderezos

Os datos do BEV están en tres táboas (bev.locality, bev.street, bev.address) cun índice sobre o código postal, o código de rúa e o número. A importación execútase mediante COPY nunha transacción, polo que as táboas se substitúen nun só paso. Os números normalízanse na grafía do rexistro (51-55, 12a). Cos números, as táboas ocupan uns 400 MB na base de datos. Quen non o queira, desactiva Comprobar números e arranxase con aproximadamente 150.000 filas.

O que nos ensinou o servizo real

Un módulo que só se probou con respostas de proba escritas por un mesmo aínda non se considera rematado. Por iso comprobamos o cliente contra o servizo real antes da publicación, coa chave da nosa propia empresa. Naquel momento xurdiron varias diverxencias respecto das nosas suposicións, que corriximos:

• Só a información resumida. Con esta chave o extracto só se pode obter na extensión Kurzinformation (información resumida). O servizo rexeita as solicitudes con Vollinformation (información completa). Na versión 1.0.0 a execución diaria aínda o solicitaba mal; a versión 1.1.0 corríxeo. Das persoas, o módulo só toma os nomes dos xerentes con poder de representación; non se len os socios nin os enderezos das persoas.
• Rúa e número por separado. O enderezo chega como STRASSE e HAUSNUMMER en elementos separados, non como un só texto. O módulo xunta ambos.
• Tribunal na execución. O tribunal competente non figura na parte da empresa, senón no último bloque VOLLZ do extracto.
• Empresas canceladas. Unha empresa cancelada recoñécese por un atributo (MIT_FIRMA_GELOESCHT_DURCH_VNR) e non por un texto. O módulo convérteo no resultado Empresa cancelada, que activa un aviso.
• O nome da empresa non é a palabra de busca. A busca compara o comezo do nome. “Muster GmbH” non atopa nada se o rexistro escribe “Muster Gesellschaft m.b.H.”; as empresas en liquidación levan “in Liqu.” no nome, e no nome do contacto ás veces aínda figura &. Por iso o módulo repite a busca sen a forma xurídica e compara nomes sen as variantes de grafía da forma xurídica, sen caracteres HTML e sen o engadido “in Liqu.”. Unha única coincidencia só se acepta se o seu nome comeza igual que o do contacto.
• Cambios de documentos sen número do Firmenbuch. A lista de documentos cambiados só contén unha chave. O número do Firmenbuch (sen letra de control) está ao comezo desa chave. O módulo asigna os cambios aos clientes a través dela.

Para cada un destes puntos hai agora unha proba automatizada cunha resposta reconstruída.

A proba coa nosa propia carteira de clientes

Despois da versión 1.1.0 probamos o módulo coa nosa propia carteira de clientes. Primeiro executouse só unha busca de nomes en modo lectura e despois a asignación das coincidencias unívocas. Non se cambiou nada sen ter en conta os valores existentes: completáronse os campos baleiros, as diverxencias están preparadas como propostas para aprobar e non saíu ningún só correo electrónico. O resultado, sen citar empresas concretas:

• Buscáronse 438 contactos de empresa con estado de cliente en Austria ou sen país.
• 138 deles asignáronse sen ambigüidade no Firmenbuch. Outros 18 tiñan unha coincidencia de nome unívoca, pero outro enderezo no rexistro (traslado ou empresa homónima), e por iso quedaron intactos. 2 nomes son ambiguos.
• Preto de 280 non os atopamos ou só como coincidencias parciais. Trátase de particulares, empresarios individuais, empresas estranxeiras, contactos que só citan unha marca ou unha localidade e empresas cuxo nome no contacto difire do asento, por exemplo porque alí figura outra forma xurídica. Para eles queda a Busca no Firmenbuch manual.
• Xeráronse 63 propostas de cambio, sobre todo para a rúa e o número (grafía) e o país.
• 66 avisos, ningún de nivel crítico. 36 empresas figuran no rexistro como canceladas (9 delas tamén en liquidación), 2 tiveran un procedemento de insolvencia xa levantado e en 42 chamaron a atención as contas anuais: ratio de capital propio baixo, perda ou caída das vendas. Unha empresa cancelada non é automaticamente un cliente perdido, pero si un motivo para revisar o enderezo e o destinatario da factura.

Dúas leccións: unha carteira de clientes dunha actividade real é unha proba moito mellor que calquera resposta reconstruída. Atopamos así erros na busca de nomes, corrixidos na versión 1.1.1 (véxase arriba). E a taxa de coincidencias depende moito do coidado con que se nomeen os contactos: quen escribe a razón social tal como a leva o rexistro, atópase de forma fiable.

Instalación e configuración

Requisitos: Odoo 19.0 coas aplicacións estándar Contactos e Discuss, o paquete Python requests (presente en toda instalación de Odoo) e acceso HTTPS saínte a justizonline.gv.at e data.bev.gv.at. O módulo non ten dependencias fóra das aplicacións estándar, polo que non arrastra ningún outro módulo.

1. Colocar o cartafol partner_firmenbuch_at no addons_path, actualizar a lista de aplicacións e instalar o módulo; en sistemas produtivos, o mellor é facelo primeiro nunha base de datos de proba.
2. O módulo crea a canle de Discuss Firmenbuch (usuarios internos) e inscribe todos os administradores. Ademais, créanse as tres accións planificadas.
3. Solicitar a chave de API: JustizOnline (ID Austria), Informationsweiterverwendung, API FBW.
4. Axustes → Firmenbuch: introducir a chave e Probar a conexión. Despois escoller a canle, as opcións, as palabras clave e os códigos de posición.

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

Importante en sistemas produtivos: a primeira execución da actualización do rexistro de enderezos arranca automaticamente na noite posterior á instalación, ás 03:15, e descarga uns 120 MB. Despois compróbanse todos os contactos austríacos; as incidencias aparecen como propostas e como unha mensaxe na canle. Quen non o queira, desactiva antes a acción planificada Rexistro de enderezos (BEV): actualizar ou desactiva Comprobar enderezos austríacos nos axustes.

Importacións masivas: importe coas claves de contexto fb_no_lookup=True e bev_no_check=True. Se non, cada empresa austríaca importada quedaría anotada para unha consulta ao rexistro (20 cada dez minutos) e cada enderezo comprobaríase ao crealo.

Protección de datos: que envía o módulo e a quen

• Datos persoais: os nomes dos xerentes son datos persoais, aínda que sexan públicos no rexistro. O módulo gárdaos só para coidar a relación comercial. Quen non o queira, borra o campo ou non o usa.
• Firmenbuch: só o nome ou o número do Firmenbuch dos contactos marcados como empresa (sen empresa matriz, país Austria ou baleiro) vai a justizonline.gv.at, xunto coa chave de API. As persoas físicas e as persoas de contacto dunha empresa nunca se envían.
• Rexistro de enderezos: só se descarga o extracto público. Os enderezos dos clientes non saen do sistema.
• Ningún correo a clientes: as mensaxes van á canle interna, ao chatter e, como actividade, aos empregados.
• Chave: a chave de API só é visible para os administradores.

O Firmenbuch é un rexistro público. A reutilización dos datos está suxeita ás condicións da Informationsweiterverwendung de JustizOnline.

Probas

O módulo inclúe 18 probas automatizadas. Traballan con respostas do rexistro reconstruídas e un extracto de enderezos en miniatura, e por iso non precisan nin chave de API nin rede:

• Normalización do número do Firmenbuch
• Interpretación do extracto (nome, enderezo, tribunal, xerentes, empresa cancelada, ignóranse os asentos non vixentes)
• Comparación de nomes: variantes de grafía da forma xurídica, “in Liqu.”, caracteres HTML, ningunha coincidencia cunha empresa allea
• Contas anuais: capital propio, resultado, total do balance
• Atópase unha empresa nova, énchense os campos baleiros, propóñense as diverxencias, a proposta aplícase parcialmente
• Vixilancia: un procedemento de insolvencia aberto sitúa o nivel en crítico e xera a actividade, un procedemento levantado dá un aviso, as persoas de contacto non se comproban por separado
• Os cambios de documentos asígnanse a través da chave
• Sen chave de API non se consulta nada
• Verificación de enderezos contra o extracto en miniatura

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

A tradución ao alemán está en i18n/de.po.

Límites e aviso legal

• Unha coincidencia é unha indicación, non un ditame xurídico. O estado dedúcese de palabras clave en asentos vixentes do rexistro. Consulte vostede mesmo o rexistro antes de decidir sobre crédito ou condicións de entrega.
• Detección de insolvencias só probada con casos reconstruídos. O módulo recoñece os procedementos por palabras no texto libre dos feitos xurídicos (apertura, levantamento, plan de saneamento confirmado, por falta de patrimonio). O seu formato reconstruímolo a partir dun extracto real do rexistro, pero durante o desenvolvemento non tivemos á man ningún caso real de insolvencia. Unha formulación pouco habitual pode polo tanto pasar desapercibida. O módulo non substitúe o Ediktsdatei oficial.
• Contas anuais só como XML. As presentacións só en PDF omítense. Nas sociedades moi pequenas o balance pode presentarse abreviado, sen os números que le o módulo.
• Só Austria. As empresas estranxeiras non se consultan. Os sitios web das empresas non figuran no rexistro e non se completan.
• Asignación automática só con coincidencia unívoca. Se hai varias empresas co mesmo nome, unha mensaxe na canle pide a Busca no Firmenbuch manual.
• As interfaces poden cambiar. O módulo depende dos servizos do BMJ e do BEV. Se cambian o punto final, o esquema ou o feed ATOM, pode ser necesaria unha actualización.
• Probado para Odoo 19. Desenvolvido e probado para Odoo 19.0 Community. Non o comprobamos para outras versións. A publicación non é asesoramento xurídico.

Preguntas frecuentes

Ten algún custo o acceso ao rexistro?

Segundo o noso coñecemento, non: os FBW-WebServices para a Informationsweiterverwendung son gratuítos, pero precisan unha chave de API que se solicita a través de JustizOnline. Son determinantes as condicións vixentes do Ministerio de Xustiza.

Sobrescríbense os datos de contacto existentes?

Non. O módulo só escribe en campos baleiros. Os valores diverxentes créanse como proposta, que un empregado aproba campo por campo.

Notan algo os meus clientes da verificación?

Non. Todas as mensaxes van á canle interna, ao chatter do contacto e, como actividade, aos empregados. O módulo non envía correos electrónicos aos clientes.

Gárdanse xerentes ou socios?

Os nomes dos xerentes con poder de representación si (campo Xerente na lapela Firmenbuch); os socios e os enderezos de persoas non. Trate os nomes como datos persoais.

Cantos dos nosos clientes atopa o módulo?

Depende da carteira de clientes. No noso caso foron 138 de 438 contactos de empresa (preto dun terzo). O resto son particulares, empresarios individuais, empresas estranxeiras e contactos cuxo nome non coincide coa razón social. Os números figuran na sección A proba coa nosa propia carteira de clientes.

Podo atopar un cliente sen número do Firmenbuch?

Si. A lapela Firmenbuch ten o botón Busca no Firmenbuch coa busca polo nome. O módulo só escribe automaticamente cando coincide exactamente unha empresa. Se non, escolla vostede mesmo a coincidencia.

Que pasa coas empresas de Alemaña ou Suíza?

Non se consultan. O módulo só mira contactos con país Austria ou sen país.

Canto almacenamento precisa a verificación de enderezos?

Cos números, uns 400 MB na base de datos e, na importación, uns 120 MB de espazo temporal en disco. Sen a comprobación dos números abonda con aproximadamente 150.000 filas.

E se só quero o Firmenbuch e non a verificación de enderezos?

Desactive Comprobar enderezos austríacos nos axustes e desactive a acción planificada do rexistro de enderezos. Entón non se descarga nada.

Baixo que licenza está o módulo?

Baixo a LGPL-3. Pode usalo, adaptalo e distribuílo. Os erros e as propostas de mellora son benvidos como issue no repositorio de GitHub .

Apoio de Biricon IT Services

Atendemos instalacións de Odoo para pequenas e medianas empresas: desde a implantación, pasando por adaptacións e migracións, ata a operación continua. Se quere manter limpos os datos mestres de clientes en Odoo, detectar antes os riscos de solvencia ou revisar un módulo coma este e levalo con seguridade á súa instancia produtiva, axudarémolo con gusto. Pode atopar máis desenvolvementos propios no noso blog, por exemplo Conxuntos de produtos no orzamento como sección e Web RBL, a lista de bloqueo para o tráfico de ataque.

Póñase en contacto connosco

Data: 3 de novembro de 2026. Versión do módulo 19.0.1.1.1. Os datos de exemplo das ilustracións están elixidos libremente e non son empresas reais.