Documentación de la API

Introducción

Los juzgados de insolvencias alemanes publican cada paso de un procedimiento en el portal oficial insolvenzbekanntmachungen.de: medidas cautelares, apertura, archivo por insuficiencia de masa, listas de distribución, exoneración del pasivo restante. El portal está pensado para consultar casos concretos, no para procesar datos. No tiene interfaz, no permite exportar y borra los anuncios al vencer los plazos legales.

La API cubre ese hueco. Recogemos cada anuncio nuevo el mismo día de su publicación, normalizamos juzgado, estado federado, número de registro y tipo de anuncio, lo vinculamos a un perfil de empresa y lo ponemos a tu disposición como JSON o CSV. Aseguradoras de crédito, empresas de cobro, despachos de abogados, departamentos de crédito comercial y periodistas de datos la usan para alimentar sus propios sistemas.

Todas las peticiones van a https://germanyinsolvencies.com/api/v1. La API solo habla HTTPS, acepta JSON y responde con JSON. No hay ningún SDK obligatorio: basta cualquier lenguaje capaz de enviar una petición HTTP. Los ejemplos de esta página usan curl, Python y Node.

Acceso

No hay registro automático, y es intencionado. Activamos las claves a mano porque los datos de insolvencia incluyen datos personales y queremos saber para qué sirve una integración. En la práctica son un mensaje breve y un día hábil.

Usa el formulario de contacto o escribe a [email protected] e indica cuatro cosas:

• Qué quieres construir, en dos o tres frases.
• Qué tipos de anuncio y qué regiones necesitas.
• Cuántas peticiones o empresas verificadas al mes, aproximadamente.
• Si puedes recibir webhooks o prefieres consultar periódicamente.

Después recibes una clave personal que funciona de inmediato en todos los endpoints que cubre tu contrato. Una cuenta puede tener varias claves activas, de modo que una clave se puede rotar sin interrupción.

Autenticación

Cada petición lleva la clave en la cabecera X-API-Key. Como alternativa, la API acepta la misma clave como bearer token en la cabecera Authorization, útil para herramientas que solo conocen esa cabecera.

X-API-Key: YOUR_API_KEY

# equivalent
Authorization: Bearer YOUR_API_KEY

Sin clave, la API responde 401 missing_api_key. Una clave desconocida o desactivada devuelve 403 invalid_api_key, y una suscripción caducada devuelve 403 subscription_expired. El motivo figura siempre en el campo error de la respuesta.

Trata la clave como una contraseña: úsala solo en el servidor, nunca en código de frontend ni en un repositorio público. Si una clave se filtra, avísanos: la revocamos de inmediato y emitimos una nueva.

Inicio rápido

La petición más habitual es también la más sencilla: todas las aperturas, medidas cautelares y archivos de un día. Una llamada, sin paginación, y la respuesta llega en menos de un segundo.

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

Sin fecha, la API devuelve el día anterior. Eso hace trivial una tarea diaria: una entrada de cron poco después de las 6 de la mañana obtiene los anuncios de ayer y los escribe en tu sistema. Los juzgados publican en días laborables, así que en domingos y festivos el resultado suele estar vacío o ser muy corto.

Para una carga histórica recorres el periodo en ventanas de 31 días como máximo:

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)

Endpoints de un vistazo

Las rutas son relativas a https://germanyinsolvencies.com/api. La dirección completa del primer endpoint es, por tanto, https://germanyinsolvencies.com/api/v1/filings.

Consultar anuncios

GET /v1/filings es el núcleo de la API. Devuelve todos los anuncios publicados en el periodo solicitado, ordenados por fecha de publicación y, dentro de un mismo día, por orden de publicación.

La respuesta contiene el periodo efectivo, los códigos de tipo solicitados, el número de resultados y el array de anuncios. Un periodo se devuelve siempre de una pieza, este endpoint no tiene paginación. Incluso los días de mucha actividad quedan muy por debajo de 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 misma petición en Node, filtrada por 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 anuncio concreto con el texto completo se obtiene con GET /v1/filings/{id}. El ID es estable, así que puedes guardarlo y usarlo más adelante para comprobar si un anuncio ya se ha procesado.

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

Tipos de anuncio

Los juzgados de insolvencias clasifican sus anuncios en nueve materias. En el parámetro types la API acepta tanto el código numérico como un alias legible. También se admiten plurales y grafías con diéresis (eroeffnungen, eröffnung).

El nombre oficial del tipo se devuelve en alemán en el campo type, tal como lo publica el juzgado. Para el procesamiento automático usa type_code, que nunca cambia. Un valor desconocido en types devuelve 400 bad_type junto con la lista de códigos permitidos.

El objeto de anuncio

Todos los campos de texto son UTF-8. Los nombres y textos se transmiten exactamente como los escribió el juzgado, incluidas las erratas. Solo encontrarás valores normalizados en los campos que se normalizan de forma explícita: type_code, bundesland y company_id.

La combinación de juzgado y número de expediente identifica un procedimiento. Un procedimiento suele generar varios anuncios a lo largo de meses o años: medidas cautelares, apertura, resoluciones, lista de distribución, conclusión. Si quieres seguir un procedimiento, agrupa por court más aktenzeichen.

Exportación CSV

Con format=csv la API devuelve los mismos datos como archivo CSV en lugar de JSON: una línea por anuncio, fila de encabezado, coma como separador, UTF-8. El archivo llega con Content-Disposition: attachment y un nombre que incluye el 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 ..."

El texto completo de la columna text contiene saltos de línea y por eso va entre comillas. Excel abre el archivo correctamente mediante «Datos, desde texto/CSV» con codificación UTF-8; con un simple doble clic, según la configuración del sistema, los caracteres especiales pueden corromperse.

Empresas

Los anuncios tratan de procedimientos, pero la mayoría de los casos de uso tratan de empresas. Por eso cada anuncio se asocia, cuando es posible, a un perfil de empresa mediante el número de registro, el nombre y el domicilio social. GET /v1/companies busca en esos perfiles.

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

Los parámetros de búsqueda son q (nombre, mínimo tres caracteres), register, city, bundesland, status e industry. Las listas se devuelven en páginas de 100 entradas como máximo, con un cursor:

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

Mientras has_more sea true, pasa next_cursor como parámetro cursor de la siguiente petición. Un cursor sigue siendo válido durante 24 horas.

El objeto de empresa

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

Valores de estado

El estado se deriva del anuncio relevante más reciente del procedimiento. Es un resumen práctico, no una valoración jurídica: en caso de duda prevalece el texto completo del anuncio.

GET /v1/companies/{id}/filings devuelve todos los anuncios de una empresa, del más antiguo al más reciente. Así obtienes el historial completo de un procedimiento sin buscar tú mismo por número de expediente.

Cifras de balance

Para las sociedades de capital suelen estar disponibles las cuentas anuales depositadas en el registro mercantil. GET /v1/companies/{id}/financials devuelve las cifras clave de los últimos ejercicios, del más reciente al más antiguo. Los importes están en euros enteros.

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

Las empresas pequeñas solo están obligadas a publicar un balance abreviado. Los campos que no figuran en el depósito valen null y nunca se estiman. Por eso a menudo falta el resultado neto anual.

Uso típico: en una decisión de crédito, la evolución del patrimonio neto en los últimos dos o tres ejercicios dice más que el anuncio de insolvencia por sí solo. Un patrimonio neto negativo junto con una medida cautelar es un cuadro inequívoco.

Verificación de contrapartes

POST /v1/check verifica en una sola llamada una lista completa de clientes o proveedores. Envías tu propia referencia y lo que sepas de la empresa: nombre, ciudad, número de registro. La API devuelve para cada entrada la coincidencia y el estado del procedimiento.

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 llamada admite hasta 500 entradas. since limita la búsqueda a los anuncios desde esa fecha; por defecto son tres años atrás. Para carteras más grandes recomendamos la lista de seguimiento: se verifica una vez y después solo se reciben los cambios.

Lista de seguimiento

La lista de seguimiento convierte una verificación puntual en una vigilancia continua. Añades empresas y, en cuanto aparece un anuncio nuevo sobre alguna de ellas, recibes un evento watchlist.match por webhook. Las entradas se pueden identificar por company_id, por número de registro y juzgado, o por nombre y ciudad.

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
}

También se pueden vigilar empresas que nunca han estado en insolvencia. La entrada espera entonces hasta que aparece el primer anuncio, que es justo el objetivo. Tu propia referencia en ref vuelve en cada evento, así que puedes asignar un resultado a tu número de cliente sin una consulta adicional.

GET /v1/watchlist lista todas las entradas con la fecha del último resultado, y DELETE /v1/watchlist/{id} elimina una. La misma lista de seguimiento es visible en tu panel de Germany Insolvencies, y los cambios se sincronizan en ambos sentidos.

Webhooks

En lugar de consultar periódicamente, puedes recibir los eventos por push. Registra un endpoint HTTPS y elige los eventos, opcionalmente con los mismos filtros que en /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"
    }
  }
}

Cada llamada va firmada. La cabecera X-Webhook-Signature contiene una marca de tiempo y un HMAC-SHA256 sobre la marca de tiempo y el cuerpo sin procesar, calculado con el secreto que recibes al registrar el endpoint.

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

Responde con un estado 2xx en diez segundos. Si falla, reintentamos con intervalos crecientes a lo largo de 24 horas, ocho veces en total. Los eventos pueden llegar duplicados, así que usa el id del evento para descartar repeticiones.

Estadísticas

GET /v1/stats devuelve recuentos en lugar de anuncios individuales. Es el endpoint para paneles, informes y análisis periodísticos, porque no obliga a descargar y contar miles de registros.

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 acepta day, week, month, bundesland, court, type y legal_form, hasta dos a la vez. Se aplican los mismos filtros que en /v1/filings. A diferencia de los anuncios, aquí el periodo puede abarcar hasta 24 meses.

Datos de referencia

Dos endpoints pequeños devuelven los valores válidos para los filtros. Cambian rara vez y se pueden guardar en caché durante un día.

[
  { "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 devuelve todos los juzgados de insolvencias con la grafía exacta que espera el filtro court y el estado federado. GET /v1/account muestra el alcance de tu contrato, los límites activos y el consumo del mes en curso.

Errores

Los errores llegan como JSON con el estado HTTP correspondiente. El campo error es legible por máquina y estable; message explica el problema a las personas y puede cambiar.

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

Límites

Cada respuesta lleva en sus cabeceras el estado actual del límite de peticiones. Si lo superas, recibes 429 rate_limited y una cabecera Retry-After en segundos.

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

Versionado

La versión mayor forma parte de la ruta (/v1/). Dentro de una versión mayor solo hacemos cambios aditivos: endpoints nuevos, parámetros opcionales nuevos, campos nuevos en las respuestas. Por eso tu cliente debe ignorar los campos desconocidos en lugar de fallar.

Los cambios que podrían romper integraciones existentes solo se producen en una versión mayor nueva. La versión anterior sigue funcionando entonces al menos doce meses, y informamos de antemano por correo a todos los titulares de claves. La fecha de versión de la respuesta figura en la cabecera X-API-Version.

X-API-Version: 2026-09-01

Fuentes de datos y actualidad

La única fuente de los anuncios es el portal oficial conjunto de los estados federados, insolvenzbekanntmachungen.de, en el que todos los juzgados de insolvencias alemanes publican conforme al § 9 de la Ley Concursal alemana (Insolvenzordnung). No añadimos anuncios de otras fuentes ni modificamos su contenido.

Los juzgados publican en días laborables, sobre todo durante la noche y por la mañana. Los anuncios nuevos suelen estar disponibles en la API antes de las 7 de la mañana del día siguiente. Los perfiles de empresa y los números de registro se enriquecen a partir del registro mercantil; las cifras de balance proceden de las cuentas anuales publicadas allí.

La asociación de anuncios a empresas es automática. Con número de registro es fiable; sin él (autónomos, nombres muy comunes) son posibles los errores. Por eso company_id puede ser null, y por eso la verificación de contrapartes distingue entre exact y probable.

Protección de datos y uso permitido

Los anuncios de insolvencia son públicos, pero contienen datos personales, sobre todo en los procedimientos de consumidores. Su uso está sujeto al RGPD y a los plazos de supresión de la Ordenanza sobre Publicaciones Concursales (Insolvenzbekanntmachungsverordnung). Por eso eliminamos los anuncios de la API, como muy tarde, cuando el portal oficial tiene que suprimirlos, y GET /v1/filings/{id} devuelve entonces 404 not_found.

Refleja esa supresión en tus propios sistemas. Basta una comparación periódica mediante los IDs que hayas guardado: lo que la API ya no conoce tampoco debería estar en tu base de datos.

Los usos permitidos son la valoración de riesgos comerciales, la gestión de cobros, el asesoramiento jurídico, la investigación y el periodismo. No están permitidos: publicar anuncios sobre particulares, revender los datos en bruto y tomar decisiones sobre personas físicas basadas únicamente en estos datos. Si tratas datos personales por encargo nuestro, hay disponible un contrato de encargo de tratamiento.

Soporte

Preguntas sobre la integración, límites más altos o campos adicionales: [email protected] o el formulario de contacto. Para problemas técnicos, indica la hora de la petición y los primeros caracteres de tu clave, y así encontramos la petición en los registros enseguida.

Si quieres conectar agentes de IA en lugar de escribir clientes HTTP, los mismos datos están disponibles a través de un servidor de Model Context Protocol, documentado en Servidor MCP. Ambos comparten claves, límites y contrato.