Conceitos básicos

O parâmetro q de fetch-organization aceita três tipos de entrada. Os exemplos desta página são requisições para a Hetzner Online GmbH, Ansbach HRB 6089:

Só o número de registro não basta, porque cada tribunal de registro atribui seus próprios números. A ordem, por outro lado, é livre: no exemplo, HRB 6089 Ansbach encontra a mesma empresa.

Se a API não encontra nenhuma empresa, responde com 404 e não cobra nada. Para entradas imprecisas, existe o Modo IA (ai_search=on-default): ele encontra a empresa também a partir de partes do nome e a pesquisa na web. Custa 20 créditos adicionais, mesmo que não encontre nenhuma empresa. Para obter vários candidatos de uma vez, use a Busca & Exportação.

Todo perfil de empresa contém os dados básicos, incluindo nome, forma jurídica, situação, registro, endereço, objeto social, setor, capital e regras de representação. Todo o resto você solicita como recurso, por exemplo related_persons para os diretores ou financial_kpi para os KPIs financeiros.

Você passa vários recursos com feature repetido ou como lista: features=related_persons,financial_kpi. Cada recurso aparece na resposta sob sua própria chave. Só publications se chama history lá.

A API ignora nomes desconhecidos sem mensagem de erro, então confira a grafia. Recursos que o seu plano não inclui são omitidos e não são cobrados.

Todos os recursos com seus preços estão em fetch-organization, cada campo no Catálogo de dados.

Requisições de dados custam créditos. Para um perfil de empresa, valem estas regras:

• O preço base de 5 créditos vale quando a API retorna uma empresa.
• Um recurso só custa créditos quando retorna dados na resposta. Um recurso vazio é grátis, incluindo insolvency_publications sem entradas.
• Tempo real e Modo IA não são recursos, mas acréscimos com regras próprias:
  • O Tempo real custa 10 créditos adicionais assim que a consulta ao vivo é bem-sucedida. Isso vale também quando não mostra nada novo.
  • O Modo IA custa 20 créditos adicionais, mesmo que não encontre nenhuma empresa. O acréscimo só deixa de ser cobrado quando a API interrompe a requisição com 408 por demorar demais.
• Todos os outros erros não custam nada.

A regra de cada recurso está em Cobrança, os preços em fetch-organization.

Um exemplo: os dados básicos com related_persons e financial_kpi custam 5 + 2 + 1 = 8 créditos se os dois recursos retornarem dados.

Antes de cada requisição, a API verifica se o seu saldo cobre o maior preço possível. Se não cobrir, a API responde com 402 e não cobra nada. O que foi realmente cobrado está em meta.request_credit_cost, o seu saldo depois em meta.credits_remaining.

Você recebe créditos como créditos iniciais, todo mês com uma assinatura de créditos, ou uma única vez como créditos de recarga. Sem assinatura de créditos, os créditos iniciais e de recarga valem por 30 dias; com uma assinatura ativa, não expiram. Todo o resto está em Cobrança.

Por padrão, o perfil da empresa vem do nosso banco de dados. Quão atual é uma informação depende da sua fonte.

Mantemos dados básicos, pessoas e publicações do registro atualizados no nosso banco de dados a partir do registro. Isso é rápido e basta para a maioria dos fins.

Com Tempo real (realtime_mode=handelsregister-default), a API busca o Aktueller Abdruck (AD, extrato atual) ao vivo no Handelsregister (registro comercial) no momento da sua requisição e o retorna como JSON. Você também recebe as pessoas registradas no momento em related_persons.current, sem pagar pelo recurso.

Se a consulta ao vivo funcionou, aparece em _realtime_mode.status. Só cobramos os 10 créditos do Tempo real com success.

Se a consulta ao vivo falhar, a API retorna os dados armazenados no nosso banco de dados. Você percebe isso por _realtime_mode.status, que então não é success. O Tempo real então não é cobrado, como meta.request_credit_cost também mostra.

O Tempo real vale a pena quando o estado de hoje importa. Por exemplo, você verifica novos parceiros comerciais antes de assinar ou vê quem pode representar a empresa neste momento.

Procuramos demonstrações financeiras anuais recém-publicadas todos os dias. As empresas, porém, têm até doze meses após o fim do exercício para publicá-las (§ 325 HGB), e muitas usam o prazo inteiro. Algumas empresas perdem o prazo legal de propósito e publicam ainda mais tarde.

Por isso, a demonstração mais recente muitas vezes cobre o ano retrasado. Mais em Atualidade.

Os tribunais de insolvência geralmente publicam seus avisos no dia da decisão ou pouco depois. Você os recebe pelo recurso insolvency_publications, cada um com tribunal, número do processo e data.

O recurso news retorna notícias sobre a empresa na web, com título, fonte, data e link. Quão atuais elas são depende de quando se noticiou algo sobre a empresa pela última vez. Para empresas pequenas, muitas vezes há poucas reportagens correspondentes.

Muitos dados mudam com o tempo. Por isso, a API retorna o estado atual e o histórico lado a lado:

• current é o estado de hoje.
• history lista cada estado registrado com effective_from e effective_to. Se effective_to é null, o estado ainda vale hoje.
• Pessoas estão em related_persons.current e related_persons.past, cada uma com start_date e end_date.

Todo dado com histórico vem dos registros e publicações, por exemplo do Chronologischer Abdruck (CD, extrato cronológico) do Handelsregister ou de todas as demonstrações financeiras anuais publicadas.

Veja como fica no nosso exemplo das regras de representação da Hetzner Online GmbH. Na resposta de exemplo, elas mencionam a diretoria executiva até 28 de julho de 2015 e, desde então, os diretores:

A maioria das datas vem no formato YYYY-MM-DD. Até onde vai o histórico está descrito em Idade e histórico.

Nem toda empresa tem um valor para cada campo. A API mostra isso de duas formas:

• null: não há valor para este campo.
• []: a lista não tem entradas, por exemplo nenhum aviso de insolvência.

Um recurso solicitado sem dados vem como null ou [] e não custa nada.

No seu código, trate uma chave ausente, null e [] da mesma forma, porque alguns objetos vazios vêm como []. Leia também os campos pelos nomes, porque a ordem das chaves não é fixa.

Se falta um valor, a empresa geralmente nem é obrigada a publicá-lo. O que a lei exige conforme a forma jurídica e o porte está descrito em Disponibilidade de dados. Alguns dados retemos de propósito; eles trazem então redacted: true.

A API cresce de forma aditiva. Novos dados e recursos chegam como novos campos. Nunca removemos campos existentes, não os renomeamos e não mudamos nem o tipo nem o significado deles. Assim, toda versão continua retrocompatível.

Mudanças que quebrariam código existente só vêm numa nova versão da API, por exemplo em /v2. A versão atual roda em /v1.

Por isso, faça seu cliente ignorar campos desconhecidos e tratar valores desconhecidos como caso geral. Novos campos e recursos estão listados no Changelog.

Você pode usar Perfil da empresa, Documentos, Busca & Exportação e Signals com qualquer conta, mesmo sem assinatura de créditos. Uma assinatura de créditos traz novos créditos todo mês e libera mais dados:

A API omite recursos fora do seu plano sem erro e não os cobra. Perfis de pessoas e filtros de busca fora do seu plano ela recusa com 403, também sem custo. Para Signals, isso vale para temas que você solicita explicitamente; sem isso, você simplesmente recebe todos os temas do seu plano.

Os preços e créditos dos planos estão na página de preços.