Documentation de l’API

Introduction

Les tribunaux allemands de l’insolvabilité publient chaque étape d’une procédure sur le portail officiel insolvenzbekanntmachungen.de : mesures conservatoires, ouverture, rejets pour insuffisance d’actif, états de répartition, remise du solde de dettes. Le portail est conçu pour consulter des dossiers isolés, pas pour traiter des données. Il n’a pas d’interface programmatique, pas d’export, et supprime les annonces à l’expiration des délais légaux.

L’API comble cette lacune. Nous collectons chaque nouvelle annonce le jour de sa publication, normalisons le tribunal, le Land, le numéro de registre et le type d’annonce, la relions à une fiche d’entreprise et la mettons à disposition en JSON ou en CSV. Assureurs-crédit, sociétés de recouvrement, cabinets d’avocats, équipes de crédit clients et journalistes de données s’en servent pour alimenter leurs propres systèmes.

Toutes les requêtes vont à https://germanyinsolvencies.com/api/v1. L’API n’accepte que HTTPS, reçoit du JSON et répond en JSON. Aucun SDK n’est obligatoire : n’importe quel langage capable d’envoyer une requête HTTP suffit. Les exemples de cette page utilisent curl, Python et Node.

Accès

Il n’existe volontairement pas d’inscription en libre-service. Nous activons les clés à la main, car les données d’insolvabilité contiennent des données personnelles et nous voulons savoir à quoi sert une intégration. En pratique, cela représente un court message et un jour ouvré.

Utilisez le formulaire de contact ou écrivez à [email protected] en indiquant quatre points :

• Ce que vous voulez construire, en deux ou trois phrases.
• Les types d’annonces et les régions dont vous avez besoin.
• Le nombre approximatif de requêtes ou d’entreprises contrôlées par mois.
• Si vous pouvez recevoir des webhooks ou préférez interroger l’API à intervalles réguliers.

Vous recevez ensuite une clé personnelle, immédiatement utilisable sur tous les endpoints couverts par votre contrat. Un compte peut détenir plusieurs clés actives, ce qui permet de faire tourner une clé sans interruption de service.

Authentification

Chaque requête transmet la clé dans l’en-tête X-API-Key. L’API accepte aussi la même clé comme jeton bearer dans l’en-tête Authorization, pratique pour les outils qui ne connaissent que cet en-tête.

X-API-Key: YOUR_API_KEY

# equivalent
Authorization: Bearer YOUR_API_KEY

Sans clé, l’API répond 401 missing_api_key. Une clé inconnue ou désactivée renvoie 403 invalid_api_key, un abonnement expiré renvoie 403 subscription_expired. La raison figure toujours dans le champ error de la réponse.

Traitez la clé comme un mot de passe : utilisez-la uniquement côté serveur, jamais dans du code frontend, jamais dans un dépôt public. Si une clé fuite, prévenez-nous : nous la révoquons aussitôt et en émettons une nouvelle.

Démarrage rapide

La requête la plus courante est aussi la plus simple : toutes les ouvertures, mesures conservatoires et rejets d’une journée. Un appel, pas de pagination, la réponse arrive en moins d’une seconde.

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

Sans date, l’API renvoie la veille. Une tâche quotidienne devient triviale : une entrée cron peu après 6 h récupère les annonces de la veille et les écrit dans votre système. Les tribunaux publient les jours ouvrés ; les dimanches et jours fériés, le résultat est donc généralement vide ou très court.

Pour un rattrapage historique, parcourez la période par fenêtres de 31 jours au maximum :

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)

Vue d’ensemble des endpoints

Les chemins sont relatifs à https://germanyinsolvencies.com/api. L’adresse complète du premier endpoint est donc https://germanyinsolvencies.com/api/v1/filings.

Récupérer les annonces

GET /v1/filings est le cœur de l’API. Il renvoie chaque annonce publiée sur la période demandée, triée par date de publication et, au sein d’une journée, dans l’ordre de publication.

La réponse contient la période effective, les codes de type demandés, le nombre de résultats et le tableau des annonces. Une période est toujours renvoyée d’un bloc, ce endpoint n’a pas de pagination. Même les jours chargés restent bien en dessous d’un mégaoctet.

{
  "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 même requête en Node, filtrée sur la Bavière :

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");

Une annonce isolée avec son texte intégral est renvoyée par GET /v1/filings/{id}. L’ID reste stable : vous pouvez le stocker et vous en servir plus tard pour vérifier si une annonce a déjà été traitée.

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

Types d’annonces

Les tribunaux de l’insolvabilité classent leurs annonces en neuf rubriques. Le paramètre types accepte aussi bien le code numérique qu’un alias lisible. Les pluriels et les graphies avec trémas sont également acceptés (eroeffnungen, eröffnung).

La dénomination officielle du type est renvoyée en allemand dans le champ type, exactement comme le tribunal la publie. Pour le traitement automatique, utilisez type_code, qui ne change jamais. Une valeur inconnue dans types renvoie 400 bad_type avec la liste des codes autorisés.

L’objet annonce

Tous les champs texte sont en UTF-8. Les noms et les textes sont transmis exactement comme le tribunal les a rédigés, fautes de frappe comprises. Les valeurs normalisées ne se trouvent que dans les champs explicitement normalisés : type_code, bundesland et company_id.

La combinaison du tribunal et du numéro de dossier identifie une procédure. Une procédure produit typiquement plusieurs annonces sur des mois ou des années : mesures conservatoires, ouverture, décisions, état de répartition, clôture. Pour suivre une procédure, regroupez par court et aktenzeichen.

Export CSV

Avec format=csv, l’API renvoie les mêmes données sous forme de fichier CSV au lieu de JSON : une ligne par annonce, ligne d’en-tête, virgule comme séparateur, UTF-8. Le fichier est livré avec Content-Disposition: attachment et un nom de fichier contenant la période.

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 ..."

Le texte intégral de la colonne text contient des retours à la ligne et est donc placé entre guillemets. Excel ouvre correctement le fichier via « Données, À partir d’un fichier texte/CSV » avec l’encodage UTF-8 ; un simple double-clic peut altérer les caractères accentués selon les réglages du système.

Entreprises

Les annonces portent sur des procédures, mais la plupart des cas d’usage portent sur des entreprises. C’est pourquoi chaque annonce est, si possible, rapprochée d’une fiche d’entreprise à l’aide du numéro de registre, du nom et du siège. GET /v1/companies recherche dans ces fiches.

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

Les paramètres de recherche sont q (nom, au moins trois caractères), register, city, bundesland, status et industry. Les listes sont renvoyées par pages de 100 entrées au plus, avec un curseur :

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

Tant que has_more vaut true, passez next_cursor comme paramètre cursor de la requête suivante. Un curseur reste valable 24 heures.

L’objet entreprise

{
  "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/"
}

Valeurs de statut

Le statut est déduit de la dernière annonce pertinente de la procédure. C’est un résumé pratique, pas une appréciation juridique : en cas de doute, le texte intégral de l’annonce fait foi.

GET /v1/companies/{id}/filings renvoie toutes les annonces d’une entreprise, les plus anciennes d’abord. Vous obtenez ainsi l’historique complet d’une procédure sans chercher vous-même par numéro de dossier.

Chiffres de bilan

Pour les sociétés de capitaux, les comptes annuels déposés au registre du commerce sont souvent disponibles. GET /v1/companies/{id}/financials renvoie les chiffres clés des derniers exercices, du plus récent au plus ancien. Les montants sont en euros entiers.

{
  "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"
    }
  ]
}

Les petites entreprises n’ont à publier qu’un bilan abrégé. Les champs absents du dépôt valent null et ne sont jamais estimés. Le résultat net annuel manque souvent pour cette raison.

Usage typique : dans une décision de crédit, l’évolution des capitaux propres sur les deux ou trois derniers exercices en dit plus que la seule annonce d’insolvabilité. Des capitaux propres négatifs associés à une mesure conservatoire donnent un tableau sans ambiguïté.

Contrôle de contreparties

POST /v1/check contrôle toute une liste de clients ou de fournisseurs en un seul appel. Vous envoyez votre propre référence et ce que vous savez de l’entreprise : nom, ville, numéro de registre. L’API renvoie pour chaque entrée une correspondance et le statut de la procédure.

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 }
  ]
}

Un appel accepte jusqu’à 500 entrées. since limite la recherche aux annonces à partir de cette date, par défaut trois ans en arrière. Pour les portefeuilles plus importants, nous recommandons la liste de suivi : contrôler une fois, puis ne recevoir que les changements.

Liste de suivi

La liste de suivi transforme un contrôle ponctuel en surveillance continue. Vous ajoutez des entreprises et, dès qu’une nouvelle annonce paraît pour l’une d’elles, vous recevez un événement watchlist.match par webhook. Les entrées peuvent être identifiées par company_id, par numéro de registre et tribunal, ou par nom et ville.

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
}

On peut aussi suivre des entreprises qui n’ont jamais été en difficulté. L’entrée attend alors la première annonce, et c’est précisément le but. Votre propre référence dans ref revient dans chaque événement : vous rattachez un résultat à votre numéro de client sans recherche supplémentaire.

GET /v1/watchlist liste toutes les entrées avec la date du dernier résultat, DELETE /v1/watchlist/{id} en supprime une. La même liste de suivi est visible dans votre tableau de bord Germany Insolvencies, les modifications sont synchronisées dans les deux sens.

Webhooks

Au lieu d’interroger l’API, vous pouvez faire pousser les événements. Enregistrez un endpoint HTTPS et choisissez les événements, éventuellement avec les mêmes filtres que pour /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"
    }
  }
}

Chaque appel est signé. L’en-tête X-Webhook-Signature contient un horodatage et un HMAC-SHA256 calculé sur l’horodatage et le corps brut, avec le secret que vous recevez lors de l’enregistrement.

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

Répondez par un statut 2xx dans les dix secondes. En cas d’échec, nous réessayons à intervalles croissants sur 24 heures, huit fois au total. Les événements peuvent arriver en double : utilisez l’id de l’événement pour écarter les doublons.

Statistiques

GET /v1/stats renvoie des décomptes plutôt que des annonces individuelles. C’est le endpoint des tableaux de bord, des rapports et des analyses journalistiques, car il évite de télécharger et de compter des milliers d’enregistrements.

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 accepte day, week, month, bundesland, court, type et legal_form, jusqu’à deux à la fois. Les mêmes filtres que pour /v1/filings s’appliquent. Contrairement aux annonces, la période peut ici couvrir jusqu’à 24 mois.

Données de référence

Deux petits endpoints renvoient les valeurs valides pour les filtres. Elles changent rarement et peuvent être mises en cache pendant une journée.

[
  { "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 renvoie tous les tribunaux de l’insolvabilité avec l’orthographe exacte attendue par le filtre court et le Land. GET /v1/account affiche le périmètre de votre contrat, les limites actives et la consommation du mois en cours.

Erreurs

Les erreurs reviennent en JSON avec le statut HTTP correspondant. Le champ error est lisible par machine et stable ; message explique le problème à un humain et peut changer.

{
  "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"]
}

Limites

Chaque réponse porte dans ses en-têtes l’état actuel de la limite de débit. Si vous la dépassez, vous recevez 429 rate_limited et un en-tête Retry-After en secondes.

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

Gestion des versions

La version majeure fait partie du chemin (/v1/). Au sein d’une version majeure, nous n’apportons que des changements additifs : nouveaux endpoints, nouveaux paramètres optionnels, nouveaux champs dans les réponses. Votre client doit donc ignorer les champs inconnus plutôt que d’échouer.

Les changements susceptibles de casser des intégrations existantes n’interviennent que dans une nouvelle version majeure. La version précédente reste alors en service au moins douze mois, et nous prévenons auparavant chaque titulaire de clé par e-mail. La date de version de la réponse figure dans l’en-tête X-API-Version.

X-API-Version: 2026-09-01

Sources de données et actualité

L’unique source des annonces est le portail officiel commun des Länder, insolvenzbekanntmachungen.de, sur lequel tous les tribunaux allemands de l’insolvabilité publient en application du § 9 du Code allemand de l’insolvabilité. Nous n’ajoutons aucune annonce issue d’autres sources et ne modifions pas leur contenu.

Les tribunaux publient les jours ouvrés, surtout la nuit et le matin. Les nouvelles annonces sont en général disponibles dans l’API avant 7 h le lendemain matin. Les fiches d’entreprise et les numéros de registre sont enrichis à partir du registre du commerce ; les chiffres de bilan proviennent des comptes annuels qui y sont publiés.

Le rapprochement des annonces et des entreprises est automatisé. Avec un numéro de registre, il est fiable ; sans (entrepreneurs individuels, noms très courants), des erreurs sont possibles. C’est pourquoi company_id peut valoir null, et pourquoi le contrôle de contreparties distingue exact et probable.

Protection des données et usage autorisé

Les annonces d’insolvabilité sont publiques, mais elles contiennent des données personnelles, surtout dans les procédures de consommateurs. Leur utilisation est soumise au RGPD et aux délais de suppression de l’ordonnance allemande sur les publications d’insolvabilité. Nous supprimons donc les annonces de l’API au plus tard lorsque le portail officiel doit les supprimer, et GET /v1/filings/{id} renvoie alors 404 not_found.

Merci de répercuter cette suppression dans vos propres systèmes. Une comparaison régulière à partir des ID que vous avez stockés suffit : ce que l’API ne connaît plus ne doit plus figurer dans votre base non plus.

Sont autorisés : l’évaluation des risques commerciaux, la gestion des créances, le conseil juridique, la recherche et le journalisme. Ne sont pas autorisés : la publication d’annonces concernant des particuliers, la revente des données brutes et les décisions sur des personnes physiques fondées uniquement sur ces données. Si vous traitez des données personnelles pour notre compte, un contrat de sous-traitance est disponible.

Assistance

Questions sur l’intégration, limites plus élevées ou champs supplémentaires : [email protected] ou le formulaire de contact. En cas de problème technique, indiquez l’heure de la requête et les premiers caractères de votre clé : nous retrouvons alors la requête dans les journaux immédiatement.

Si vous souhaitez connecter des agents IA plutôt qu’écrire des clients HTTP, les mêmes données sont disponibles via un serveur Model Context Protocol, documenté sur la page Serveur MCP. Les deux partagent clés, limites et contrat.