Documentazione API

Introduzione

I tribunali fallimentari tedeschi pubblicano ogni fase di una procedura sul portale ufficiale insolvenzbekanntmachungen.de: misure cautelari, apertura, rigetto per mancanza di attivo, piani di riparto, esdebitazione. Il portale è pensato per consultare singoli casi, non per elaborare dati: non ha un’interfaccia programmatica, non offre esportazioni e cancella gli avvisi allo scadere dei termini di legge.

L’API colma questa lacuna. Raccogliamo ogni nuovo avviso nel giorno stesso della pubblicazione, normalizziamo tribunale, Land, numero di registro e tipo di pubblicazione, lo colleghiamo a un profilo aziendale e lo rendiamo disponibile in JSON o CSV. Assicuratori del credito, società di recupero crediti, studi legali, uffici crediti commerciali e giornalisti dei dati la usano per alimentare i propri sistemi.

Tutte le richieste vanno a https://germanyinsolvencies.com/api/v1. L’API funziona solo via HTTPS, accetta JSON e risponde in JSON. Non è richiesto alcun SDK: basta qualsiasi linguaggio in grado di inviare una richiesta HTTP. Gli esempi di questa pagina usano curl, Python e Node.

Accesso

Non esiste di proposito una registrazione self-service. Abilitiamo le chiavi a mano perché i dati sulle insolvenze contengono dati personali e vogliamo sapere a cosa serve un’integrazione. In pratica basta un breve messaggio e un giorno lavorativo.

Usa il modulo di contatto oppure scrivi a [email protected] indicando quattro cose:

• Cosa vuoi realizzare, in due o tre frasi.
• Di quali tipi di pubblicazione e regioni hai bisogno.
• Circa quante richieste o aziende verificate al mese.
• Se puoi ricevere webhook o preferisci fare polling.

Riceverai quindi una chiave personale, subito valida su tutti gli endpoint previsti dal tuo contratto. Un account può avere più chiavi attive, così una chiave può essere sostituita senza interruzioni.

Autenticazione

Ogni richiesta trasporta la chiave nell’header X-API-Key. In alternativa l’API accetta la stessa chiave come bearer token nell’header Authorization, utile per gli strumenti che conoscono solo quell’header.

X-API-Key: YOUR_API_KEY

# equivalent
Authorization: Bearer YOUR_API_KEY

Senza chiave l’API risponde 401 missing_api_key. Una chiave sconosciuta o disattivata restituisce 403 invalid_api_key, un abbonamento scaduto restituisce 403 subscription_expired. Il motivo si trova sempre nel campo error della risposta.

Tratta la chiave come una password: usala solo lato server, mai nel codice frontend, mai in un repository pubblico. Se una chiave viene esposta, comunicacelo: la revochiamo subito e ne emettiamo una nuova.

Quickstart

La richiesta più comune è anche la più semplice: tutte le aperture, misure cautelari e rigetti di un giorno. Una sola chiamata, nessuna paginazione, risposta entro un secondo.

curl -H "X-API-Key: $INSOLVENCY_API_KEY" \
  "https://germanyinsolvencies.com/api/v1/filings?date=2026-09-28&types=eroeffnung,sicherung,abweisung"

Senza data l’API restituisce il giorno precedente. Questo rende banale un job giornaliero: una voce cron poco dopo le 6 recupera le pubblicazioni di ieri e le scrive nel tuo sistema. I tribunali pubblicano nei giorni lavorativi, quindi di domenica e nei giorni festivi il risultato è di solito vuoto o molto breve.

Per un backfill storico si percorre il periodo a finestre di al massimo 31 giorni:

import os, datetime, requests

API = "https://germanyinsolvencies.com/api/v1"
HEAD = {"X-API-Key": os.environ["INSOLVENCY_API_KEY"]}

# Backfill a quarter in 31-day windows, then keep running daily.
start, end = datetime.date(2026, 7, 1), datetime.date(2026, 9, 28)
day = start
while day <= end:
    stop = min(day + datetime.timedelta(days=30), end)
    r = requests.get(API + "/filings", headers=HEAD, params={
        "date_from": day.isoformat(),
        "date_to": stop.isoformat(),
        "types": "eroeffnung,abweisung",
    }, timeout=60)
    r.raise_for_status()
    for f in r.json()["filings"]:
        print(f["date"], f["aktenzeichen"], f["name"])
    day = stop + datetime.timedelta(days=1)

Panoramica degli endpoint

I percorsi sono relativi a https://germanyinsolvencies.com/api. L’indirizzo completo del primo endpoint è quindi https://germanyinsolvencies.com/api/v1/filings.

Recuperare le pubblicazioni

GET /v1/filings è il cuore dell’API. Restituisce ogni avviso pubblicato nel periodo richiesto, ordinato per data di pubblicazione e, all’interno di uno stesso giorno, nell’ordine di pubblicazione.

La risposta contiene il periodo effettivo, i codici di tipo richiesti, il numero di risultati e l’array degli avvisi. Un periodo viene sempre restituito per intero, questo endpoint non prevede paginazione. Anche i giorni più intensi restano ben al di sotto di un megabyte.

{
  "date_from": "2026-09-28",
  "date_to": "2026-09-28",
  "types": ["0", "1", "2"],
  "count": 142,
  "filings": [
    {
      "id": "fil_8Kq2Zp4RwT",
      "date": "2026-09-28",
      "type": "Eröffnungen",
      "type_code": "2",
      "name": "Musterbau GmbH",
      "sitz": "Berlin",
      "court": "Charlottenburg (Berlin)",
      "aktenzeichen": "36a IN 4711/26",
      "bundesland": "Berlin",
      "register": "HRB 123456 B",
      "company_id": "cmp_3n8Kd2ZpQv",
      "text": "Amtsgericht Charlottenburg (Berlin), Aktenzeichen: 36a IN 4711/26 ..."
    }
  ]
}

La stessa richiesta in Node, filtrata sulla Baviera:

const url = new URL("https://germanyinsolvencies.com/api/v1/filings");
url.searchParams.set("types", "eroeffnung");
url.searchParams.set("bundesland", "Bayern");

const res = await fetch(url, {
  headers: { "X-API-Key": process.env.INSOLVENCY_API_KEY },
});
if (!res.ok) throw new Error((await res.json()).error);

const { count, filings } = await res.json();
console.log(count, "openings in Bavaria yesterday");

Un singolo avviso con il testo completo si ottiene con GET /v1/filings/{id}. L’ID resta stabile, quindi puoi salvarlo e usarlo in seguito per verificare se un avviso è già stato elaborato.

curl -H "X-API-Key: $INSOLVENCY_API_KEY" \
  https://germanyinsolvencies.com/api/v1/filings/fil_8Kq2Zp4RwT

Tipi di pubblicazione

I tribunali fallimentari suddividono i loro avvisi in nove materie. Nel parametro types l’API accetta sia il codice numerico sia un alias leggibile. Sono accettati anche i plurali e le grafie con dieresi (eroeffnungen, eröffnung).

La denominazione ufficiale del tipo viene restituita in tedesco nel campo type, esattamente come la pubblica il tribunale. Per l’elaborazione automatica usa type_code, che non cambia mai. Un valore sconosciuto in types restituisce 400 bad_type insieme all’elenco dei codici ammessi.

L’oggetto filing

Tutti i campi di testo sono in UTF-8. Nomi e testi vengono trasmessi esattamente come li ha scritti il tribunale, refusi compresi. Valori normalizzati si trovano solo nei campi normalizzati esplicitamente: type_code, bundesland e company_id.

La combinazione di tribunale e numero di ruolo identifica una procedura. Una procedura produce di norma più avvisi nell’arco di mesi o anni: misure cautelari, apertura, decisioni, elenco di riparto, chiusura. Se vuoi seguire una procedura, raggruppa per court più aktenzeichen.

Esportazione CSV

Con format=csv l’API restituisce gli stessi dati come file CSV invece di JSON: una riga per avviso, riga di intestazione, virgola come separatore, UTF-8. Il file arriva con Content-Disposition: attachment e un nome che contiene il periodo.

curl -H "X-API-Key: $INSOLVENCY_API_KEY" \
  -o filings.csv \
  "https://germanyinsolvencies.com/api/v1/filings?date_from=2026-09-01&date_to=2026-09-28&format=csv"

date,type,type_code,name,sitz,court,aktenzeichen,bundesland,register,text
2026-09-28,Eröffnungen,2,Musterbau GmbH,Berlin,Charlottenburg (Berlin),36a IN 4711/26,Berlin,HRB 123456 B,"Amtsgericht Charlottenburg ..."
2026-09-28,Sicherungsmaßnahmen,0,Beispiel Logistik UG (haftungsbeschränkt),Hamburg,Hamburg,67c IN 812/26,Hamburg,HRB 98765,"Amtsgericht Hamburg ..."

Il testo completo nella colonna text contiene interruzioni di riga ed è quindi racchiuso tra virgolette. Excel apre correttamente il file tramite «Dati, da testo/CSV» con codifica UTF-8; un semplice doppio clic può rovinare le dieresi a seconda delle impostazioni di sistema.

Aziende

Gli avvisi riguardano procedure, ma la maggior parte dei casi d’uso riguarda le aziende. Per questo ogni avviso viene associato, quando possibile, a un profilo aziendale, in base a numero di registro, nome e sede. GET /v1/companies cerca in questi profili.

curl -G -H "X-API-Key: $INSOLVENCY_API_KEY" \
  https://germanyinsolvencies.com/api/v1/companies \
  --data-urlencode "q=Musterbau" \
  --data-urlencode "bundesland=Berlin" \
  -d limit=20

I parametri di ricerca sono q (nome, almeno tre caratteri), register, city, bundesland, status e industry. Gli elenchi vengono restituiti in pagine di al massimo 100 voci con un cursore:

{
  "object": "list",
  "data": [ { "id": "cmp_3n8Kd2ZpQv", "object": "company", "...": "..." } ],
  "has_more": true,
  "next_cursor": "eyJpZCI6ImNtcF8zbjhLZDJacFF2In0"
}

Finché has_more è true, passa next_cursor come parametro cursor della richiesta successiva. Un cursore resta valido per 24 ore.

L’oggetto company

{
  "id": "cmp_3n8Kd2ZpQv",
  "object": "company",
  "name": "Musterbau GmbH",
  "legal_form": "GmbH",
  "register": "HRB 123456 B",
  "register_court": "Charlottenburg (Berlin)",
  "city": "Berlin",
  "bundesland": "Berlin",
  "industry": "Hochbau",
  "status": "opened",
  "first_filing": "2026-08-14",
  "last_filing": "2026-09-28",
  "filings_count": 3,
  "website": "https://musterbau.example",
  "url": "https://germanyinsolvencies.com/company/musterbau-gmbh-berlin/"
}

Valori di status

Lo status deriva dall’avviso rilevante più recente della procedura. È una sintesi pratica, non una valutazione giuridica: in caso di dubbio fa fede il testo completo dell’avviso.

GET /v1/companies/{id}/filings restituisce tutti gli avvisi di un’azienda, dal più vecchio. Così ottieni l’intera storia di una procedura senza dover cercare tu stesso per numero di ruolo.

Dati di bilancio

Per le società di capitali sono spesso disponibili i bilanci depositati presso il registro delle imprese. GET /v1/companies/{id}/financials restituisce gli indicatori chiave degli ultimi esercizi, dal più recente. Gli importi sono in euro interi.

{
  "company_id": "cmp_3n8Kd2ZpQv",
  "currency": "EUR",
  "statements": [
    {
      "fiscal_year_to": "2024-12-31",
      "bilanzsumme": 4820000,
      "eigenkapital": -310000,
      "verbindlichkeiten": 5130000,
      "jahresueberschuss": -1240000,
      "source": "Unternehmensregister"
    },
    {
      "fiscal_year_to": "2023-12-31",
      "bilanzsumme": 5410000,
      "eigenkapital": 930000,
      "verbindlichkeiten": 4480000,
      "jahresueberschuss": 85000,
      "source": "Unternehmensregister"
    }
  ]
}

Le piccole imprese devono pubblicare solo un bilancio abbreviato. I campi non inclusi nel deposito sono null e non vengono mai stimati. Per questo motivo manca spesso l’utile netto dell’esercizio.

Uso tipico: in una decisione di credito, l’andamento del patrimonio netto negli ultimi due o tre esercizi dice più del solo avviso di insolvenza. Un patrimonio netto negativo insieme a una misura cautelare è un quadro chiaro.

Verifica delle controparti

POST /v1/check verifica un’intera lista di clienti o fornitori in una sola chiamata. Invii il tuo riferimento e ciò che sai dell’azienda: nome, città, numero di registro. L’API restituisce per ogni voce una corrispondenza e lo stato della procedura.

curl https://germanyinsolvencies.com/api/v1/check \
  -H "X-API-Key: $INSOLVENCY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "since": "2025-01-01",
    "items": [
      { "ref": "D-10023", "name": "Musterbau GmbH", "city": "Berlin" },
      { "ref": "D-10024", "register": "HRB 98765", "register_court": "Hamburg" },
      { "ref": "D-10025", "name": "Nordlicht Handels GmbH" }
    ]
  }' 

{
  "checked": 3,
  "hits": 1,
  "results": [
    {
      "ref": "D-10023",
      "match": "exact",
      "company_id": "cmp_3n8Kd2ZpQv",
      "status": "opened",
      "last_filing": { "id": "fil_8Kq2Zp4RwT", "date": "2026-09-28", "type_code": "2" }
    },
    { "ref": "D-10024", "match": "none" },
    { "ref": "D-10025", "match": "ambiguous", "candidates": 2 }
  ]
}

Una chiamata accetta fino a 500 voci. since limita la ricerca agli avvisi a partire da quella data, il valore predefinito è tre anni indietro. Per portafogli più grandi consigliamo la watchlist: verifichi una volta, poi ricevi solo le variazioni.

Watchlist

La watchlist trasforma una verifica una tantum in un monitoraggio continuo. Aggiungi le aziende e, non appena compare un nuovo avviso per una di esse, ricevi un evento watchlist.match via webhook. Le voci si possono identificare tramite company_id, tramite numero di registro e tribunale, oppure tramite nome e città.

curl https://germanyinsolvencies.com/api/v1/watchlist \
  -H "X-API-Key: $INSOLVENCY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "register": "HRB 123456 B", "register_court": "Charlottenburg (Berlin)", "ref": "D-10023" }' 

{
  "id": "wl_Q7m2Lx9Pd",
  "object": "watchlist_entry",
  "ref": "D-10023",
  "company_id": "cmp_3n8Kd2ZpQv",
  "name": "Musterbau GmbH",
  "created_at": "2026-09-29T08:12:44Z",
  "last_match": null
}

Si possono monitorare anche aziende mai state insolventi. La voce resta allora in attesa del primo avviso, ed è proprio questo lo scopo. Il tuo riferimento in ref torna in ogni evento, così puoi associare un riscontro al tuo numero cliente senza ulteriori ricerche.

GET /v1/watchlist elenca tutte le voci con la data dell’ultimo riscontro, DELETE /v1/watchlist/{id} ne rimuove una. La stessa watchlist è visibile nella tua dashboard Germany Insolvencies, le modifiche vengono sincronizzate in entrambe le direzioni.

Webhook

Invece di fare polling puoi far inviare gli eventi. Registra un endpoint HTTPS e scegli gli eventi, se vuoi con gli stessi filtri di /v1/filings.

curl https://germanyinsolvencies.com/api/v1/webhooks \
  -H "X-API-Key: $INSOLVENCY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/hooks/insolvency",
    "events": ["watchlist.match", "filing.published"],
    "filter": { "types": ["eroeffnung", "sicherung"], "bundesland": ["Bayern", "Hessen"] }
  }' 

{
  "id": "evt_5Tg8Nw2Ka",
  "type": "watchlist.match",
  "created_at": "2026-09-29T06:05:11Z",
  "data": {
    "watchlist_entry": { "id": "wl_Q7m2Lx9Pd", "ref": "D-10023" },
    "filing": {
      "id": "fil_8Kq2Zp4RwT",
      "date": "2026-09-28",
      "type": "Eröffnungen",
      "type_code": "2",
      "name": "Musterbau GmbH",
      "court": "Charlottenburg (Berlin)",
      "aktenzeichen": "36a IN 4711/26"
    }
  }
}

Ogni chiamata è firmata. L’header X-Webhook-Signature contiene un timestamp e un HMAC-SHA256 calcolato su timestamp e corpo grezzo, con il secret che ricevi al momento della registrazione.

X-Webhook-Signature: t=1790661911,v1=7f2c1d9a4b6e8035c1f7a29d4e5b0c8371a6d2f94e8b3c07a15d9e2f6b4c8a01

import hashlib, hmac, os, time
from flask import Flask, request, abort

app = Flask(__name__)
SECRET = os.environ["INSOLVENCY_WEBHOOK_SECRET"].encode()

@app.post("/hooks/insolvency")
def hook():
    header = request.headers.get("X-Webhook-Signature", "")
    parts = dict(p.split("=", 1) for p in header.split(",") if "=" in p)
    signed = parts.get("t", "") + "." + request.get_data(as_text=True)
    expected = hmac.new(SECRET, signed.encode(), hashlib.sha256).hexdigest()
    if not hmac.compare_digest(expected, parts.get("v1", "")):
        abort(400)
    if abs(time.time() - int(parts["t"])) > 300:
        abort(400)  # replay protection

    event = request.get_json()
    if event["type"] == "watchlist.match":
        ref = event["data"]["watchlist_entry"]["ref"]
        print("Customer", ref, "has a new insolvency filing")
    return "", 204

Rispondi con uno status 2xx entro dieci secondi. Se non succede, riproviamo a intervalli crescenti nell’arco di 24 ore, otto volte in tutto. Gli eventi possono arrivare due volte, quindi usa l’id dell’evento per scartare i duplicati.

Statistiche

GET /v1/stats restituisce conteggi invece dei singoli avvisi. È l’endpoint per dashboard, report e analisi giornalistiche, perché non richiede di scaricare e contare migliaia di record.

curl -G -H "X-API-Key: $INSOLVENCY_API_KEY" \
  https://germanyinsolvencies.com/api/v1/stats \
  -d date_from=2026-07-01 -d date_to=2026-09-28 \
  -d group_by=month,bundesland -d types=eroeffnung

{
  "date_from": "2026-07-01",
  "date_to": "2026-09-28",
  "group_by": ["month", "bundesland"],
  "rows": [
    { "month": "2026-07", "bundesland": "Bayern",  "count": 318 },
    { "month": "2026-07", "bundesland": "Berlin",  "count": 204 },
    { "month": "2026-08", "bundesland": "Bayern",  "count": 297 }
  ],
  "total": 8412
}

group_by accetta day, week, month, bundesland, court, type e legal_form, fino a due contemporaneamente. Valgono gli stessi filtri di /v1/filings. A differenza delle pubblicazioni, qui il periodo può coprire fino a 24 mesi.

Dati di riferimento

Due piccoli endpoint restituiscono i valori validi per i filtri. Cambiano raramente e possono essere messi in cache per un giorno.

[
  { "code": "0", "alias": "sicherung",   "name": "Sicherungsmaßnahmen" },
  { "code": "1", "alias": "abweisung",   "name": "Abweisungen mangels Masse" },
  { "code": "2", "alias": "eroeffnung",  "name": "Eröffnungen" }
]

GET /v1/courts restituisce tutti i tribunali fallimentari con l’esatta grafia attesa dal filtro court e il Land. GET /v1/account mostra l’ambito del tuo contratto, i limiti attivi e il consumo del mese corrente.

Errori

Gli errori tornano come JSON con un HTTP status corrispondente. Il campo error è leggibile dalle macchine e stabile, message spiega il problema alle persone e può cambiare.

{
  "error": "range_too_large",
  "message": "Maximum range is 31 days per request."
}

{
  "error": "bad_type",
  "message": "Unknown type 'eroffnung'.",
  "allowed": ["0", "1", "2", "3", "4", "5", "6", "7", "8"]
}

Limiti

Ogni risposta riporta negli header lo stato attuale del rate limit. Se lo superi ricevi 429 rate_limited e un header Retry-After in secondi.

X-RateLimit-Limit: 120
X-RateLimit-Remaining: 117
X-RateLimit-Reset: 1790661960
Retry-After: 12

Versionamento

La versione principale fa parte del percorso (/v1/). All’interno di una versione principale facciamo solo modifiche additive: nuovi endpoint, nuovi parametri opzionali, nuovi campi nelle risposte. Il tuo client dovrebbe quindi ignorare i campi sconosciuti invece di fallire.

Le modifiche che potrebbero rompere integrazioni esistenti avvengono solo in una nuova versione principale. La versione precedente continua poi a funzionare per almeno dodici mesi e informiamo in anticipo ogni titolare di chiave via email. La data di versione della risposta si trova nell’header X-API-Version.

X-API-Version: 2026-09-01

Fonti dei dati e tempestività

L’unica fonte degli avvisi è il portale ufficiale comune dei Länder, insolvenzbekanntmachungen.de, su cui tutti i tribunali fallimentari tedeschi pubblicano ai sensi del § 9 del codice tedesco dell’insolvenza. Non aggiungiamo avvisi da altre fonti e non ne modifichiamo il contenuto.

I tribunali pubblicano nei giorni lavorativi, per lo più di notte e al mattino. I nuovi avvisi sono di solito disponibili nell’API prima delle 7 del mattino seguente. I profili aziendali e i numeri di registro vengono arricchiti dal registro delle imprese; i dati di bilancio provengono dai bilanci ivi pubblicati.

L’associazione degli avvisi alle aziende è automatica. Con un numero di registro è affidabile; senza (ditte individuali, nomi molto comuni) sono possibili errori. Per questo company_id può essere null, e per questo la verifica delle controparti distingue tra exact e probable.

Protezione dei dati e uso consentito

Gli avvisi di insolvenza sono pubblici, ma contengono dati personali, soprattutto nelle procedure dei consumatori. Il loro utilizzo è soggetto al GDPR e ai termini di cancellazione del regolamento tedesco sugli avvisi di insolvenza. Per questo cancelliamo gli avvisi dall’API al più tardi quando il portale ufficiale deve cancellarli, e GET /v1/filings/{id} restituisce allora 404 not_found.

Ti chiediamo di replicare questa cancellazione nei tuoi sistemi. Basta un confronto periodico tramite gli ID che hai salvato: ciò che l’API non conosce più non dovrebbe più trovarsi nemmeno nel tuo database.

Gli usi consentiti sono la valutazione dei rischi commerciali, la gestione dei crediti, la consulenza legale, la ricerca e il giornalismo. Non sono consentiti: la pubblicazione di avvisi su privati, la rivendita dei dati grezzi e le decisioni su persone fisiche basate esclusivamente su questi dati. Se tratti dati personali per nostro conto, è disponibile un contratto di trattamento dei dati.

Supporto

Domande sull’integrazione, limiti più alti o campi aggiuntivi: [email protected] oppure il modulo di contatto. In caso di problemi tecnici indica l’ora della richiesta e i primi caratteri della tua chiave, così troviamo subito la richiesta nei log.

Se vuoi collegare agenti di IA invece di scrivere client HTTP, gli stessi dati sono disponibili tramite un server Model Context Protocol, documentato in server MCP. Entrambi condividono chiavi, limiti e contratto.