Concetti di base

Il parametro q di fetch-organization accetta tre tipi di input. Gli esempi in questa pagina sono richieste per Hetzner Online GmbH, Ansbach HRB 6089:

Il numero di registro da solo non basta, perché ogni tribunale del registro assegna i propri numeri. L’ordine invece è libero: nell’esempio, HRB 6089 Ansbach trova la stessa azienda.

Se l’API non trova alcuna azienda, risponde con 404 e non addebita nulla. Per input imprecisi c’è la Modalità AI (ai_search=on-default): trova l’azienda anche da parti del nome e la ricerca sul web. Costa 20 crediti in più, anche se non trova alcuna azienda. Per ottenere più candidati in una volta usa Ricerca & Export.

Ogni profilo aziendale contiene i dati di base, tra cui nome, forma giuridica, stato, iscrizione nel registro, indirizzo, oggetto sociale, settore, capitale e regole di rappresentanza. Tutto il resto lo richiedi come feature, ad esempio related_persons per gli amministratori o financial_kpi per i KPI finanziari.

Più feature le passi ripetendo feature o come lista: features=related_persons,financial_kpi. Ogni feature compare nella risposta sotto una propria chiave. Solo publications lì si chiama history.

L’API ignora i nomi sconosciuti senza messaggio di errore, quindi controlla l’ortografia. Le feature non incluse nel tuo piano vengono omesse e non addebitate.

Tutte le feature con i loro prezzi sono elencate in fetch-organization, ogni campo nel Catalogo dati.

Le richieste di dati costano crediti. Per un profilo aziendale valgono queste regole:

• Il prezzo base di 5 crediti si applica quando l’API restituisce un’azienda.
• Una feature costa crediti solo se restituisce dati nella risposta. Una feature vuota è gratuita, anche insolvency_publications senza voci.
• Tempo reale e Modalità AI non sono feature ma supplementi con regole proprie:
  • Tempo reale costa 10 crediti in più non appena il recupero in diretta riesce. Vale anche quando non mostra nulla di nuovo.
  • La Modalità AI costa 20 crediti in più, anche se non trova alcuna azienda. Il supplemento decade solo se l’API interrompe la richiesta con 408 perché dura troppo.
• Tutti gli altri errori non costano nulla.

La regola per ogni singola feature è in Fatturazione, i prezzi in fetch-organization.

Un esempio: i dati di base con related_persons e financial_kpi costano 5 + 2 + 1 = 8 crediti se entrambe le feature restituiscono dati.

Prima di ogni richiesta l’API controlla se il tuo saldo copre il prezzo più alto possibile. Se non lo copre, risponde con 402 e non addebita nulla. Quanto è stato effettivamente addebitato è in meta.request_credit_cost, il tuo saldo dopo in meta.credits_remaining.

Ricevi crediti come crediti iniziali, ogni mese con un abbonamento a crediti oppure una tantum come crediti di ricarica. Senza abbonamento a crediti, i crediti iniziali e di ricarica valgono 30 giorni; con un abbonamento attivo non scadono. Tutto il resto è in Fatturazione.

Di norma il profilo aziendale viene dal nostro database. Quanto è aggiornata un’informazione dipende dalla sua fonte.

Dati di base, persone e pubblicazioni del registro li manteniamo aggiornati nel nostro database a partire dal registro. È veloce e basta per la maggior parte degli scopi.

Con Tempo reale (realtime_mode=handelsregister-default) l’API recupera l’Aktueller Abdruck (AD, estratto attuale) in diretta dall’Handelsregister (registro delle imprese) nel momento della tua richiesta e lo restituisce in JSON. Ricevi anche le persone attualmente iscritte in related_persons.current, senza pagare la feature.

Se il recupero in diretta è riuscito lo indica _realtime_mode.status. Addebitiamo i 10 crediti per Tempo reale solo con success.

Se il recupero in diretta fallisce, l’API restituisce i dati salvati nel nostro database. Lo riconosci da _realtime_mode.status, che in quel caso non è success. Tempo reale allora non viene addebitato, come mostra anche meta.request_credit_cost.

Tempo reale conviene quando conta lo stato di oggi. Ad esempio, verifichi nuovi partner commerciali prima di firmare o vedi chi può rappresentare l’azienda in questo momento.

Cerchiamo ogni giorno i bilanci d’esercizio appena pubblicati. Le aziende però hanno fino a dodici mesi dalla chiusura dell’esercizio per pubblicarli (§ 325 HGB), e molte sfruttano tutto il termine. Alcune aziende mancano di proposito il termine di legge e pubblicano ancora più tardi.

L’ultimo bilancio riguarda quindi spesso l’anno precedente a quello scorso. Maggiori dettagli in Aggiornamento.

I tribunali fallimentari pubblicano di solito i loro avvisi il giorno della decisione o poco dopo. Li ricevi tramite la feature insolvency_publications, ciascuno con tribunale, numero di procedimento e data.

La feature news restituisce notizie sull’azienda dal web, con titolo, fonte, data e link. Quanto sono aggiornate dipende da quando si è parlato dell’azienda l’ultima volta. Per le piccole aziende ci sono spesso solo pochi articoli pertinenti.

Molti dati cambiano nel tempo. Per questo l’API restituisce lo stato attuale e lo storico uno accanto all’altro:

• current è lo stato a oggi.
• history elenca ogni stato iscritto con effective_from ed effective_to. Se effective_to è null, lo stato vale ancora oggi.
• Le persone sono in related_persons.current e related_persons.past, ciascuna con start_date ed end_date.

Ogni dato con storico viene dai registri e dalle pubblicazioni, ad esempio dal Chronologischer Abdruck (CD, estratto cronologico) dell’Handelsregister o da tutti i bilanci d’esercizio pubblicati.

Ecco come appare nel nostro esempio per le regole di rappresentanza di Hetzner Online GmbH. Nella risposta di esempio nominano il consiglio di gestione fino al 28 luglio 2015 e da allora gli amministratori:

La maggior parte delle date arriva nel formato YYYY-MM-DD. Fin dove arriva lo storico è descritto in Età e storico.

Non ogni azienda ha un valore per ogni campo. L’API lo indica in due modi:

• null: per questo campo non c’è alcun valore.
• []: la lista non ha voci, ad esempio nessuna pubblicazione sulle insolvenze.

Una feature richiesta senza dati arriva come null o [] e non costa nulla.

Nel tuo codice tratta allo stesso modo una chiave mancante, null e [], perché alcuni oggetti vuoti arrivano come []. Leggi inoltre i campi per nome, perché l’ordine delle chiavi non è fisso.

Se un valore manca, di solito l’azienda non è affatto tenuta a pubblicarlo. Cosa prevede la legge a seconda di forma giuridica e dimensione è descritto in Disponibilità dei dati. Alcuni dati li tratteniamo di proposito; in quel caso riportano redacted: true.

L’API cresce in modo additivo. Nuovi dati e feature arrivano come nuovi campi. Non rimuoviamo mai campi esistenti, non li rinominiamo e non ne cambiamo né il tipo né il significato. Così ogni versione resta retrocompatibile.

Le modifiche che romperebbero il codice esistente arrivano solo in una nuova versione dell’API, ad esempio sotto /v2. La versione attuale gira sotto /v1.

Fai quindi in modo che il tuo client ignori i campi sconosciuti e tratti i valori sconosciuti come caso generico. Nuovi campi e feature sono elencati nel Changelog.

Profilo aziendale, Documenti, Ricerca & Export e Signals li puoi usare con ogni account, anche senza abbonamento a crediti. Un abbonamento a crediti porta nuovi crediti ogni mese e sblocca più dati:

L’API omette senza errore le feature fuori dal tuo piano e non le addebita. Rifiuta con 403 i profili persona e i filtri di ricerca fuori dal tuo piano, anche questo senza costi. Per Signals questo vale per i temi che richiedi esplicitamente; altrimenti ricevi semplicemente tutti i temi del tuo piano.

Prezzi e crediti dei piani li trovi nella pagina prezzi.