Odoo 19 Community: Firmenbuch e verificação de moradas para clientes austríacos – o nosso módulo open source partner_firmenbuch_at

Quem faz negócios na Áustria conhece as perguntas: a denominação social e a morada do meu novo cliente estão corretas? A empresa ainda consta do Firmenbuch ou está em liquidação? Foi aberto um processo de insolvência contra o cliente a quem forneço há dois anos? As respostas constam do Firmenbuch do Ministério da Justiça, mas quase ninguém consulta regularmente. No Odoo, o contacto é criado uma vez e depois envelhece.

Para isso desenvolvemos o módulo Firmenbuch para parceiros (partner_firmenbuch_at). Liga os contactos do Odoo ao Firmenbuch e ao registo oficial de moradas do BEV. Está escrito para o Odoo 19 e está disponível gratuitamente no GitHub como software livre sob a licença LGPL-3:

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

O problema: dados mestre que ninguém mantém

Um contacto no Odoo surge, regra geral, sob pressão de tempo: nome, morada aproximada, talvez um NIF. Isso chega para o primeiro orçamento. Não chega para faturas, que têm de estar corretamente endereçadas do ponto de vista jurídico, e muito menos para dar conta de que algo mudou no cliente. Na prática, surgem quatro lacunas:

• Dados mestre incompletos. O número do Firmenbuch, o tribunal e a forma jurídica faltam quase sempre, porque a consulta é trabalho manual.
• Grafias incorretas. Denominação social sem forma jurídica, erros de digitação na rua ou na localidade, código postal trocado. Só se nota quando o correio volta devolvido.
• Nenhuma monitorização. Se um tribunal abre um processo de insolvência ou um cliente dissolve a sua sociedade, o Odoo não fica a saber. A equipa comercial continua a fornecer a crédito.
• Fontes dispersas. O Firmenbuch, as contas anuais e o registo de moradas estão em locais diferentes. Quem os quer verificar copia dados à mão entre janelas do navegador.

O que o módulo faz

1. As novas empresas são pesquisadas. Quando alguém cria um contacto como empresa (país Áustria ou vazio), o módulo pesquisa no Firmenbuch em poucos minutos. Se houver exatamente um resultado, os campos vazios são preenchidos: rua, código postal, localidade, país, número do Firmenbuch, tribunal e forma jurídica.
2. As divergências são propostas, nunca substituídas. Se no contacto consta algo diferente do que está no registo, é criada uma proposta de alteração que um colaborador aprova campo a campo.
3. Pesquisa no Firmenbuch no contacto. No separador Firmenbuch, a pesquisa encontra empresas pelo nome, mesmo que a correspondência automática não tenha sido inequívoca.
4. Monitorização diária. O módulo consulta diariamente que empresas e documentos sofreram alterações no registo e verifica os clientes afetados. Além disso, cada empresa é integralmente reverificada em intervalos configuráveis.
5. Níveis de alerta. Processos de insolvência e de recuperação abertos (a partir dos factos jurídicos do registo), liquidação, cancelamento, capital próprio negativo e um baixo rácio de capital próprio são detetados e tornados visíveis no contacto.
6. Verificação de moradas. As moradas austríacas são verificadas localmente em relação ao registo oficial de moradas do Bundesamt für Eich- und Vermessungswesen (BEV).
7. Dados do registo no contacto. Tribunal, forma jurídica, gerentes e factos jurídicos constam do separador Firmenbuch. Refletem o registo e são atualizados diretamente.
8. Notificações apenas internas. Todas as mensagens vão para o canal interno do Discuss Firmenbuch e para o chatter do contacto. Uma verificação sobre muitas empresas gera uma mensagem coletiva em vez de uma por empresa. O módulo nunca envia nada a clientes.

Sugestões em vez de substituir

Os dados oficiais não são automaticamente os melhores dados para o seu negócio: talvez no contacto conste deliberadamente a morada de entrega, talvez tenha sido adotado um nome abreviado. Por isso, o módulo nunca altera por si só valores existentes. Apenas preenche campos vazios e, em caso de divergência, cria uma proposta.

Em Contactos → Firmenbuch → Propostas do Firmenbuch vê, por campo, o valor atual e o valor do registo. Os campos que não quiser aplicar, deixe-os desmarcados. Com Aplicar selecionados são gravados apenas os campos marcados; com Rejeitar, a proposta caduca. Uma nova proposta substitui as propostas abertas mais antigas do mesmo contacto, para que não sejam aplicados valores desatualizados.

Avisos: insolvência, liquidação, balanço

O módulo distingue três níveis:

• Sem anomalias: não há nada a comunicar.
• Aviso (amarelo): o registo contém entradas válidas sobre liquidação, dissolução, encerramento, cancelamento ou fusão, a empresa está assinalada como cancelada, ou um processo de insolvência anterior foi levantado nos últimos anos (por predefinição três anos, configurável). Ou então as contas anuais mostram capital próprio negativo, um rácio de capital próprio inferior a 8 % (valor por defeito inspirado no § 23 URG, configurável), um prejuízo anual ou uma quebra de volume de negócios de 25 % ou mais.
• Crítico (vermelho): um processo de insolvência, de falência ou de recuperação foi aberto e ainda não foi levantado, ou um pedido foi indeferido por insuficiência de bens para cobrir as custas. Este último caso conta como insolvência.

No contacto aparece uma faixa colorida, na lista de contactos uma indicação e, na pesquisa, existem filtros para Aviso do Firmenbuch e Firmenbuch crítico. Se um cliente passar a crítico, o vendedor responsável (em alternativa, o administrador) recebe uma atividade Firmenbuch: verificar cliente, e o canal Firmenbuch recebe uma mensagem.

Factos jurídicos. Os processos de insolvência não constam do registo no texto da empresa, mas como factos jurídicos com data, número de processo e tribunal. O módulo lê-os, associa a abertura e o levantamento ao mesmo número de processo e apresenta-os no contacto como lista. Assim, um processo levantado passa a ser, ao fim de alguns anos, apenas informação, enquanto um processo em curso fica a vermelho.

Contas anuais. Se as últimas contas anuais estiverem disponíveis em XML, o módulo lê o capital próprio, o resultado do exercício, o total do balanço e o volume de negócios e calcula o rácio de capital próprio, a variação do volume de negócios e a categoria de dimensão nos termos do § 221 UGB (incluindo microentidades). As pequenas sociedades não têm de publicar o seu volume de negócios; nesse caso, o módulo não mostra nenhum. O resultado é deduzido do lucro de balanço menos o lucro transitado e é assinalado como estimativa. Os nomes das posições que são pesquisadas são configuráveis, porque o XML tem estruturas diferentes consoante o formulário.

Verificação de moradas com o registo de moradas do BEV

O BEV disponibiliza o registo de moradas como dados abertos (Adresse Relationale Tabellen – Stichtagsdaten, nova data de referência duas vezes por ano, utilização gratuita com indicação da fonte). O módulo descarrega o extrato através do serviço oficial INSPIRE-ATOM, cerca de 120 MB com aproximadamente 2,5 milhões de moradas, e importa-o para tabelas próprias e leves.

Depois disso, cada morada de empresa austríaca com rua é verificada localmente ao ser criada e a cada alteração: código postal, rua, número de porta, localidade e estado federado. Nenhuma morada é enviada a um serviço. O resultado consta como marcação por baixo da morada:

• Válida: a morada existe assim no registo.
• Número de porta desconhecido: a rua e a localidade estão certas, o número de porta não.
• Correção proposta: erro de digitação na rua ou na localidade, código postal errado. A correção fica disponível como proposta.
• Não encontrada: o registo não conhece esta morada.

Um estado federado vazio é preenchido diretamente. As moradas de contactos privados (tipo Morada privada) não são verificadas. A indicação da fonte © Österreichisches Adressregister, Stichtagsdaten vom … consta, com a data de referência atual, nas definições. A atualização é semanal, mas só descarrega se o BEV tiver publicado uma data de referência mais recente.

Implementação técnica

O acesso ao registo

O Ministério da Justiça disponibiliza o Firmenbuch através dos FBW-WebServices (HVD) no JustizOnline como interface SOAP. O acesso é gratuito, mas requer uma chave API, que se solicita com a ID Austria em Informationsweiterverwendung (reutilização de informações). A chave segue no cabeçalho HTTP X-API-KEY. O módulo utiliza o serviço diretamente, sem screen scraping.

O cliente models/firmenbuch_client.py é Python puro, sem dependência do Odoo. Conhece as consultas SUCHEFIRMAREQUEST, AUSZUG_V2_REQUEST, SUCHEURKUNDEREQUEST, URKUNDEREQUEST, bem como VERAENDERUNGENFIRMAREQUEST e VERAENDERUNGENURKUNDEREQUEST. Assim, pode ser testado com respostas guardadas. Os pedidos são feitos com intervalo de 0,3 segundos, e as consultas de alterações em blocos de sete dias.

Interpretação do extrato

Do extrato só são utilizadas as entradas que ainda são válidas (atributo AUFRECHT não false). O nome provém do indicador de dados FI_DKZ02, a morada de FI_DKZ03, a sede de FI_DKZ06 e a forma jurídica de FI_DKZ07. Acrescem o tribunal, o endereço web, as pessoas com poderes de representação e os factos jurídicos. Para o nível de alerta, os textos de todas as entradas válidas são pesquisados com base em palavras-chave configuráveis:

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

A vantagem da verificação por palavras-chave: funciona independentemente do campo em que o registo conduz uma ocorrência. A desvantagem consta da secção Limitações.

Monitorização

O módulo cria três ações agendadas:

• Pesquisar novas empresas (de 10 em 10 minutos, até 20 contactos por execução). Além disso, é acionada de imediato na criação.
• Monitorizar empresas (diariamente às 04:30). Consulta as empresas e os documentos alterados desde a última execução (no máximo 30 dias atrás), verifica os clientes afetados e, depois, até 50 clientes cuja última verificação seja anterior ao prazo definido. Cada empresa é guardada numa transação própria, para que um erro não faça perder resultados anteriores. O resultado da execução chega ao canal como uma única mensagem coletiva.
• Atualizar o registo de moradas (semanalmente às 03:15).

Sem chave API, as duas primeiras regressam de imediato. Uma soma de controlo por empresa impede que extratos inalterados sejam avaliados de novo.

O registo de moradas

Os dados do BEV estão em três tabelas (bev.locality, bev.street, bev.address) com um índice sobre o código postal, o código da rua e o número de porta. A importação decorre através de COPY numa transação, pelo que as tabelas são substituídas num único passo. Os números de porta são normalizados na grafia do registo (51-55, 12a). Com números de porta, as tabelas ocupam cerca de 400 MB na base de dados. Quem não o desejar desativa Verificar números de porta e fica com cerca de 150.000 linhas.

O que o serviço real nos ensinou

Um módulo que só foi testado com respostas de teste escritas por nós ainda não se considera concluído. Por isso, verificámos o cliente com o serviço real antes da publicação, com a chave da nossa própria empresa. Daí resultaram várias divergências em relação aos nossos pressupostos, que corrigimos:

• Apenas a informação resumida. Com esta chave, o extrato só pode ser obtido com o âmbito Kurzinformation (informação resumida). O serviço rejeita pedidos com Vollinformation (informação completa). Na versão 1.0.0, a execução diária ainda fazia o pedido de forma errada; a versão 1.1.0 corrige isso. Das pessoas, o módulo só adota os nomes dos gerentes com poderes de representação; os sócios e as moradas das pessoas não são lidos.
• Rua e número de porta em separado. A morada chega como STRASSE e HAUSNUMMER em elementos separados, não como um único texto. O módulo junta ambos.
• Tribunal no averbamento. O tribunal competente não consta da parte da empresa, mas do último bloco VOLLZ do extrato.
• Empresas canceladas. Uma empresa cancelada reconhece-se por um atributo (MIT_FIRMA_GELOESCHT_DURCH_VNR) e não por um texto. O módulo transforma isso no resultado Empresa cancelada, que desencadeia um aviso.
• O nome da empresa não é a palavra de pesquisa. A pesquisa compara o início do nome. «Muster GmbH» não encontra nada se o registo escrever «Muster Gesellschaft m.b.H.»; as empresas em liquidação trazem «in Liqu.» no nome, e no nome do contacto consta por vezes ainda &. Por isso, o módulo repete a pesquisa sem forma jurídica e compara nomes sem variantes de grafia da forma jurídica, sem caracteres HTML e sem o sufixo «in Liqu.». Um único resultado só é adotado se o seu nome começar como o do contacto.
• Alterações de documentos sem número do Firmenbuch. A lista de documentos alterados contém apenas uma chave. O número do Firmenbuch (sem letra de controlo) encontra-se no início dessa chave. O módulo associa as alterações aos clientes através dele.

Para cada um destes pontos existe agora um teste automatizado com uma resposta simulada.

O teste na nossa própria base de clientes

Depois da versão 1.1.0, testámos o módulo na nossa própria base de clientes. Primeiro, correu apenas uma pesquisa de nomes só de leitura e, depois, a associação dos resultados inequívocos. Nada foi alterado sem ter em conta os valores existentes: os campos vazios foram preenchidos, as divergências estão disponíveis como propostas para aprovação e não saiu um único e-mail. O resultado, sem nomear empresas concretas:

• Foram pesquisados 438 contactos de empresas com estatuto de cliente na Áustria ou sem país.
• 138 deles foram associados inequivocamente no Firmenbuch. Outros 18 tinham uma correspondência de nome inequívoca, mas uma morada diferente no registo (mudança de instalações ou empresa homónima), e por isso ficaram intocados. 2 nomes são ambíguos.
• Cerca de 280 não foram encontrados ou apenas parcialmente. Trata-se de pessoas singulares, empresários em nome individual, empresas estrangeiras, contactos que indicam apenas uma marca ou uma localidade e empresas cujo nome no contacto difere do registo, por exemplo porque aí consta outra forma jurídica. Para esses, fica a Pesquisa no Firmenbuch manual.
• Surgiram 63 propostas de alteração, sobretudo para a rua e o número de porta (grafia) e para o país.
• 66 avisos, nenhum de nível crítico. 36 empresas estão assinaladas no registo como canceladas (9 delas também em liquidação), 2 tinham um processo de insolvência entretanto levantado e, em 42, as contas anuais chamaram a atenção: baixo rácio de capital próprio, prejuízo ou quebra do volume de negócios. Uma empresa cancelada não é automaticamente um cliente perdido, mas é motivo para verificar a morada e o destinatário da fatura.

Duas lições daqui: uma base de clientes de operação real é um teste muito melhor do que qualquer resposta simulada. Encontrámos assim erros na pesquisa de nomes, que ficaram corrigidos na versão 1.1.1 (ver acima). E a taxa de acerto depende muito do cuidado com que os contactos são nomeados: quem escreve a denominação social tal como o registo a conduz é encontrado de forma fiável.

Instalação e configuração

Requisitos: Odoo 19.0 com as aplicações padrão Contactos e Discuss, o pacote Python requests (presente em qualquer instalação Odoo) e acesso HTTPS de saída a justizonline.gv.at e data.bev.gv.at. O módulo não tem dependências fora das aplicações padrão, pelo que não arrasta outros módulos.

1. Colocar a pasta partner_firmenbuch_at no addons_path, atualizar a lista de aplicações e instalar o módulo; em sistemas de produção, de preferência primeiro numa base de dados de teste.
2. O módulo cria o canal Discuss Firmenbuch (utilizadores internos) e inscreve todos os administradores. Além disso, são criadas as três ações agendadas.
3. Solicitar a chave API: JustizOnline (ID Austria), Informationsweiterverwendung, API FBW.
4. Definições → Firmenbuch: introduzir a chave e Testar ligação. Depois, escolher o canal, as opções, as palavras-chave e os códigos de posição.

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

Importante em sistemas de produção: a primeira execução da atualização do registo de moradas arranca automaticamente na noite seguinte à instalação, às 03:15, e descarrega cerca de 120 MB. Depois são verificados todos os contactos austríacos; as anomalias surgem como propostas e como uma mensagem no canal. Quem não o desejar desativa previamente a ação agendada Registo de moradas (BEV): atualizar ou desativa Verificar moradas austríacas nas definições.

Importações em massa: importe com as chaves de contexto fb_no_lookup=True e bev_no_check=True. Caso contrário, cada empresa austríaca importada seria registada para uma consulta ao registo (20 de dez em dez minutos) e cada morada seria verificada na criação.

Proteção de dados: o que o módulo envia e a quem

• Dados pessoais: os nomes dos gerentes são dados pessoais, mesmo que sejam públicos no registo. O módulo só os guarda para manter a relação comercial. Quem não o desejar apaga o campo ou não o utiliza.
• Firmenbuch: apenas o nome ou o número do Firmenbuch de contactos marcados como empresa (sem empresa principal, país Áustria ou vazio) vai para justizonline.gv.at, juntamente com a chave API. Pessoas singulares e interlocutores de uma empresa nunca são enviados.
• Registo de moradas: só é descarregado o extrato público. As moradas dos clientes não saem do sistema.
• Sem e-mails a clientes: as mensagens vão para o canal interno, para o chatter e, como atividade, para os colaboradores.
• Chave: a chave API só é visível para os administradores.

O Firmenbuch é um registo público. A reutilização dos dados está sujeita às condições da Informationsweiterverwendung do JustizOnline.

Testes

O módulo inclui 18 testes automatizados. Trabalham com respostas de registo simuladas e um extrato de moradas em miniatura, pelo que não precisam de chave API nem de rede:

• Normalização do número do Firmenbuch
• Interpretação do extrato (nome, morada, tribunal, gerente, empresa cancelada, as entradas inválidas são ignoradas)
• Comparação de nomes: variantes de grafia da forma jurídica, «in Liqu.», caracteres HTML, nenhuma correspondência com uma empresa alheia
• Contas anuais: capital próprio, resultado, total do balanço
• Uma nova empresa é encontrada, os campos vazios são preenchidos, as divergências são propostas, a proposta é aplicada parcialmente
• Monitorização: um processo de insolvência aberto define o nível como crítico e gera a atividade, um processo levantado resulta num aviso, os interlocutores não são verificados em separado
• As alterações de documentos são associadas através da chave
• Sem chave API, nada é consultado
• Verificação de moradas com o extrato em miniatura

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

A tradução alemã encontra-se em i18n/de.po.

Limitações e aviso legal

• Uma correspondência é uma indicação, não uma informação jurídica. O estado é deduzido de palavras-chave em entradas válidas do registo. Verifique o próprio registo antes de decidir sobre crédito ou condições de fornecimento.
• Deteção de insolvência testada apenas com casos simulados. O módulo reconhece processos por palavras no texto livre dos factos jurídicos (abertura, levantamento, plano de recuperação homologado, por insuficiência de bens). O seu formato reproduzimo-lo a partir de um extrato de registo real, mas durante o desenvolvimento não tivemos à mão um caso real de insolvência. Uma formulação invulgar pode, por isso, passar despercebida. O módulo não substitui o Ediktsdatei oficial.
• Contas anuais apenas em XML. As entregas apenas em PDF são ignoradas. No caso de sociedades muito pequenas, o balanço pode ter sido entregue de forma abreviada, sem os valores que o módulo lê.
• Apenas Áustria. As empresas estrangeiras não são consultadas. Os sítios web das empresas não constam do registo e não são acrescentados.
• Associação automática apenas com correspondência inequívoca. Se houver várias empresas com o mesmo nome, uma mensagem no canal pede a Pesquisa no Firmenbuch manual.
• As interfaces podem mudar. O módulo depende dos serviços do BMJ e do BEV. Se o endpoint, o esquema ou o feed ATOM mudarem, pode ser necessária uma atualização.
• Testado para o Odoo 19. Desenvolvido e testado para o Odoo 19.0 Community. Não o verificámos para outras versões. O artigo não constitui aconselhamento jurídico.

Perguntas frequentes

O acesso ao registo tem algum custo?

Segundo o nosso conhecimento, não: os FBW-WebServices para a reutilização de informações são gratuitos, mas requerem uma chave API, que pode solicitar através do JustizOnline. São determinantes as condições atuais do Ministério da Justiça.

Os dados de contacto existentes são substituídos?

Não. O módulo só preenche campos vazios. Os valores divergentes são criados como proposta, que um colaborador aprova campo a campo.

Os meus clientes apercebem-se da verificação?

Não. Todas as mensagens vão para o canal interno, para o chatter do contacto e, como atividade, para os colaboradores. O módulo não envia e-mails a clientes.

São guardados gerentes ou sócios?

Os nomes dos gerentes com poderes de representação sim (campo Gerente no separador Firmenbuch); sócios e moradas de pessoas não. Trate os nomes como dados pessoais.

Quantos dos nossos clientes o módulo encontra?

Depende da base de clientes. Connosco foram 138 de 438 contactos de empresas (cerca de um terço). O restante são pessoas singulares, empresários em nome individual, empresas estrangeiras e contactos cujo nome não corresponde à denominação social. Os números constam da secção O teste na nossa própria base de clientes.

Posso encontrar um cliente sem número do Firmenbuch?

Sim. O separador Firmenbuch tem o botão Pesquisa no Firmenbuch, com pesquisa por nome. O módulo só preenche automaticamente quando corresponde exatamente uma empresa. Caso contrário, escolhe o resultado você mesmo.

E as empresas na Alemanha ou na Suíça?

Não são consultadas. O módulo só analisa contactos com país Áustria ou sem país.

Quanto espaço de armazenamento ocupa a verificação de moradas?

Com números de porta, cerca de 400 MB na base de dados e, na importação, cerca de 120 MB de espaço temporário em disco. Sem verificação de números de porta, bastam cerca de 150.000 linhas.

E se eu só quiser o Firmenbuch e nenhuma verificação de moradas?

Desative Verificar moradas austríacas nas definições e desative a ação agendada do registo de moradas. Assim, nada é descarregado.

Sob que licença está o módulo?

Sob a LGPL-3. Pode utilizá-lo, adaptá-lo e distribuí-lo. Erros e sugestões de melhoria são bem-vindos como issue no repositório GitHub .

Apoio da Biricon IT Services

Damos assistência a instalações Odoo para pequenas e médias empresas: da implementação, passando por adaptações e migrações, até à operação corrente. Se quer manter os dados mestre de clientes limpos no Odoo, detetar mais cedo os riscos de solvabilidade ou verificar um módulo como este e colocá-lo em segurança na sua instância de produção, teremos todo o gosto em apoiá-lo. Pode encontrar outros desenvolvimentos próprios no nosso blogue, por exemplo Conjuntos de produtos no orçamento como secção e Web RBL, a lista de bloqueio para tráfego de ataque.

Contacte-nos agora

Situação em: 3 de novembro de 2026. Versão do módulo 19.0.1.1.1. Os dados de exemplo nas figuras são de livre escolha e não são empresas reais.