Zukunftsbetrieb API

Bring geprüfte lokale Betriebe in deinen KI-Agenten oder dein Portal. Zwei Endpunkte, ein kostenloser API-Key, kein Vertrag. Es werden ausschließlich verifizierte „Geprüfte Zukunftsbetriebe" ausgeliefert.

Überblick

Basis-URL:

https://zukunftsbetrieb.de

Authentifizierung: Sende deinen kostenlosen Key bei jedem Call als Header x-api-key: DEIN_KEY. Key holen →

Alles JSON. Die Suche gibt keine Kontaktdaten zurück, der Kontakt entsteht über eine Anfrage, der Betrieb meldet sich dann direkt beim Kunden.

Betriebe finden

# Header: x-api-key: DEIN_KEY GET /api/find?leistung=wallbox&ort=Köln → { "leistung": "Wallbox-Montage", "treffer": 3, "betriebe": [ { "id": 42, "name": "Muster Elektro GmbH", "ort": "Köln", "plz": "50667", "leistungen": ["Wallbox-Montage"], "siegel": "Geprüfter Zukunftsbetrieb" } ] }

leistung (Pflicht): Gewerk/Stichwort. ort (optional): Stadt oder 5-stellige PLZ. Sortiert nach regionaler Passung.

Anfrage senden

# Header: x-api-key: DEIN_KEY POST /api/anfrage { "leistung": "wallbox", "ort": "50667", "name": "Max M.", "email": "max@example.de", "telefon": "0221 …", "beschreibung": "Wallbox 11 kW, Garage" } → { "anfrage_id": 142, "status": "aufgenommen", "passende_betriebe": 3 }

Die Anfrage wird an passende geprüfte Betriebe vermittelt; ein Betrieb nimmt sie an und meldet sich beim Kunden. Keine passenden Betriebe in der Region? Die Anfrage wird trotzdem aufgenommen (Nachfrage-Signal).

Lead-Webhooks & Signatur (für Betriebe)

Als geprüfter Betrieb kannst du im Dashboard → Erweitert eine Webhook-URL hinterlegen. Neue Anfragen schicken wir dann automatisch als POST (JSON) an dein System. Jede Zustellung ist signiert, damit du echte Anfragen verifizieren kannst.

POST https://dein-system.de/leads X-Zukunftsbetrieb-Event: lead.new X-Zukunftsbetrieb-Signature: t=1783300000,v1=9f86d0811764… { "event": "lead.new", "opportunity": { "id": 142, "leistung": "wallbox" } }

So verifizierst du die Signatur (das Signatur-Secret findest du im Dashboard → Erweitert):

import hmac, hashlib, time # t und v1 aus dem Header X-Zukunftsbetrieb-Signature parsen signed = f"{t}.".encode() + raw_body # roher Body, NICHT neu serialisiert expected = hmac.new(SECRET.encode(), signed, hashlib.sha256).hexdigest() assert hmac.compare_digest(expected, v1) # echt? assert abs(time.time() - int(t)) < 300 # frisch? (Replay-Schutz)

Signiert wird der String "<t>.<roher Body>" mit HMAC-SHA256. Nutze den rohen Request-Body (das exakte gesendete Byte-Payload), sonst schlägt die Prüfung fehl. Das kanonische event steht auch im Body.

MCP-Server (für KI-Agenten)

Open-Source-MCP-Server mit zwei Tools, zukunftsbetrieb_finden und anfrage_senden. In claude_desktop_config.json:

{ "mcpServers": { "zukunftsbetrieb": { "command": "python", "args": ["server.py"], "env": { "ZB_API_KEY": "DEIN_KEY" } } } }

OpenAPI / ChatGPT

Die vollständige Spezifikation liegt unter /openapi.yaml, importierbar als Action in einen ChatGPT Custom GPT.

Portal-Partner (Umsatzbeteiligung)

Du betreibst ein Portal und willst an vermittelten Anfragen fair mitverdienen? Das Partnerprogramm startet gerade, mehr & Early Access.

Faire Nutzung: alle Endpunkte erfordern deinen kostenlosen Header x-api-key, so schützen wir das Register vor Massen-Auslesung. Ratenbegrenzt (find ~60/min, anfrage ~8/min pro Key); eine Anfrage braucht eine Kontaktangabe (E-Mail/Telefon). Key holen: portale.html.