Bodenbericht

Partner API & MCP

Bodenbewegungs-Berichte aus CRM, Bestandssystem oder KI-Agent anlegen und daraus freigeschaltete Objektblätter und Portfolio-Priorisierungen ohne weitere Berichtseinheit ableiten.

Version 1.1 · vertraglich freigeschalteter Partnerzugang

Sie planen einen neuen Anwendungsfall? Partnerschaft besprechen →

Schnellstart

Erzeugen Sie im Unternehmens-Cockpit einen API-Key. Der Klartext wird nur einmal angezeigt. Jeder schreibende Aufruf braucht zusätzlich einen 8-128 Zeichen langen Idempotency-Key.

1. Bericht anlegen

curl -X POST https://bodenbericht.de/api/v1/reports \ -H "X-API-Key: $BODENBERICHT_API_KEY" \ -H "Idempotency-Key: crm-4711-v1" \ -H "Content-Type: application/json" \ -d '{ "address": "Musterstraße 1, 10115 Berlin", "external_reference": "CRM-4711", "product": "bodenbewegung_basis" }'

2. Status und Ergebnis abrufen

curl -H "X-API-Key: $BODENBERICHT_API_KEY" \ https://bodenbericht.de/api/v1/reports/REQUEST_ID curl -H "X-API-Key: $BODENBERICHT_API_KEY" \ https://bodenbericht.de/api/v1/reports/REQUEST_ID/result curl -o bericht.pdf -H "X-API-Key: $BODENBERICHT_API_KEY" \ https://bodenbericht.de/api/v1/reports/REQUEST_ID/pdf

Interaktive API-Dokumentation öffnen

Objektblatt und Portfolio

Die beiden Ausgaben lesen ausschließlich eigene, abgeschlossene, bezahlte und bereits verbuchte Basisvorgänge. Sie starten keine neue Messung, keinen Versand und keine Buchung; additional_units ist immer 0. Die Fähigkeiten objektblatt und portfolio müssen für Ihre Organisation ausdrücklich freigeschaltet sein.

REQUEST_ID ist immer die externe Vorgangs-ID aus POST /api/v1/reports (ReportRequest.id) und niemals eine interne Berichts-UUID.

Objektblatt als JSON oder PDF

curl -H "X-API-Key: $BODENBERICHT_API_KEY" \ https://bodenbericht.de/api/v1/reports/REQUEST_ID/object-sheet curl -o objektblatt.pdf -H "X-API-Key: $BODENBERICHT_API_KEY" \ https://bodenbericht.de/api/v1/reports/REQUEST_ID/object-sheet.pdf

Bis zu 100 Vorgänge priorisieren

curl -X POST https://bodenbericht.de/api/v1/portfolio \ -H "X-API-Key: $BODENBERICHT_API_KEY" \ -H "Content-Type: application/json" \ -d '{"report_request_ids":["REQUEST_ID_1","REQUEST_ID_2"]}'

Die Vorgangs-IDs müssen eindeutig sein und derselben Organisation gehören. Die Gruppen dienen der transparenten fachlichen Reihenfolge; sie sind kein Gesamt-, Schadens- oder Grundstücksrisiko-Score.

Ein Auftrag, drei Zugänge

Portal, REST und MCP nutzen denselben Vorgang, dieselbe Queue und dasselbe Kontingent. Die Annahme ist asynchron; ein HTTP 202 bedeutet „dauerhaft angenommen“, nicht „fertig“.

Status	Bedeutung	Aktion
`accepted`	Vorgang und Einheit sind atomar reserviert.	Nach kurzer Pause erneut prüfen.
`processing`	Queue oder Berichtspipeline arbeitet.	Mit wachsendem Abstand pollen.
`completed`	JSON und Original-PDF sind abrufbar.	Ergebnis übernehmen.
`failed`	Endgültiger technischer Fehler; Einheit wurde freigegeben.	Fehlercode prüfen oder Support nennen.

Empfohlenes Polling: nach 5 Sekunden, dann 15, 30 und höchstens alle 60 Sekunden. Alternativ Webhooks verwenden.

Fehler, Idempotenz und Limits

Fehler haben immer einen stabilen Code und eine Request-ID. Dieselbe Request-ID steht außerdem im Response-Header X-Request-ID.

{ "error": { "code": "quota_exhausted", "message": "Das Berichtskontingent ... ist ausgeschöpft.", "request_id": "7e0c..." } }

HTTP	Code	Bedeutung
401	`missing_api_key`	Der Header `X-API-Key` fehlt.
401	`invalid_api_key`	Key ist ungültig, abgelaufen oder gesperrt.
402	`quota_exhausted`	Keine freie Vertragseinheit.
403	`product_not_enabled`	Die angeforderte Partnerfähigkeit ist nicht freigeschaltet.
404	`report_request_not_found`	Vorgang fehlt oder gehört nicht zur eigenen Organisation.
409	`idempotency_conflict`	Key wurde schon mit anderem Body verwendet.
409	`report_not_ready` / `report_data_unavailable`	Ausgangsbericht ist noch nicht verwendbar oder nicht sicher lesbar.
422	`validation_error`	Request passt nicht zum Vertrag.
429	`rate_limit_exceeded`	Nach `Retry-After` erneut versuchen.

Signierte Webhooks

HTTPS-Ziele konfigurieren Sie im Cockpit. Zustellungen werden bei Fehlern mit Backoff wiederholt. HTTP 410 deaktiviert den Endpoint. Redirects werden nicht verfolgt.

Zu verifizieren sind der unveränderte Body und timestamp + "." + body mit HMAC-SHA256. Akzeptieren Sie nur frische Timestamps, zum Beispiel maximal fünf Minuten alt.

import hashlib, hmac, time timestamp = request.headers["X-Bodenbericht-Timestamp"] received = request.headers["X-Bodenbericht-Signature"].removeprefix("v1=") body = request.body # rohe Bytes, nicht neu serialisieren assert abs(time.time() - int(timestamp)) <= 300 expected = hmac.new( WEBHOOK_SECRET.encode(), timestamp.encode() + b"." + body, hashlib.sha256 ).hexdigest() assert hmac.compare_digest(received, expected)

Eventtypen: report.completed und report.failed. Die Delivery-ID in X-Bodenbericht-Delivery ist der Deduplizierungsschlüssel des Empfängers.

MCP v2

Der offizielle Bodenbericht-Adapter läuft lokal per stdio im MCP-Host und ruft ausschließlich die Partner-API auf. Er erhält keinen Datenbank- oder Adminzugriff. Das Installationspaket wird im Onboarding bereitgestellt.

{ "mcpServers": { "bodenbericht": { "command": "bodenbericht-mcp", "env": { "BODENBERICHT_API_KEY": "bbp_...", "BODENBERICHT_API_BASE_URL": "https://bodenbericht.de", "BODENBERICHT_MCP_DOWNLOAD_DIR": "./bodenbericht-downloads" } } } }

Werkzeuge: create_report, get_report_status, get_report_result, list_reports, get_report_download, get_usage, get_object_sheet, get_object_sheet_download und prioritize_portfolio.

Sicherer Betrieb

Keys pro Umgebung und Anwendung trennen, regelmäßig rotieren und nie in Prompts oder Quellcode einfügen.
Nur notwendige Scopes vergeben; alte Keys erst nach erfolgreichem Wechsel sperren.
Partner- und persönliche Berichte sind mandantengetrennt. Fremde UUIDs liefern 404.
Das JSON ist kuratiert; Rohpunkte werden nicht über die Partner-API ausgegeben.
Webhook-Secrets werden verschlüsselt gespeichert und ebenfalls nur einmal angezeigt.

Support und Onboarding

Nennen Sie bei technischen Rückfragen immer Request-ID, Zeitpunkt und eigene Referenz, niemals den API-Key. Kontingent, zulässige Nutzung, Supportfenster und Datenaufbewahrung richten sich nach Ihrem Vertrag.

team@bodenbericht.de · Unternehmens-Cockpit