Bautagebuch-Daten automatisch ins Controlling: So geht’s mit der docubau-API

Das Problem: Zwei Systeme, doppelte Datenpflege

In vielen Bauunternehmen sieht der Alltag so aus: Projekte, Nachunternehmer und Vergabeeinheiten werden zentral gepflegt – in ClickUp, im ERP, in einer Projektsteuerungs-Software. Die Baustellendokumentation läuft daneben in einem eigenen Tool. Und zwischen beiden Welten sitzt ein Mensch, der abtippt: das neue Projekt anlegen, die Gewerke nachtragen, am Monatsende die Mängelliste exportieren und ins Controlling kopieren.

Das kostet nicht nur Zeit. Es entstehen auch Lücken – ein Mangel, der im Bautagebuch steht, aber im zentralen Reporting fehlt, ist im Streitfall genau der, der zählt.

Die Lösung ist eine Schnittstelle, die in beide Richtungen arbeitet: Stammdaten fließen automatisch in die Baudokumentation, Ergebnisse fließen automatisch zurück. Genau dafür gibt es die docubau REST-API mit Webhooks.

Was die docubau-API kann

Die API ist im Business-Plan enthalten und bewusst klein gehalten – ein Endpunkt, sechs Ressourcen, klare Regeln:

Ressource	Lesen	Schreiben	Wofür
\`projects\`	✅	✅ anlegen / ändern	Projekte aus ClickUp oder ERP übernehmen, Status synchron halten
\`contacts\`	✅	✅ anlegen / ändern	Nachunternehmer und Gewerke pro Projekt
\`defects\`	✅	✅ Status, Frist, Zuständigkeit	Mängel ins Controlling, Erledigung zurückspielen
\`hindrances\`	✅	✅ Status, Ursache	Behinderungsanzeigen für Bauzeit- und Nachtragsmanagement
\`diary-entries\`	✅	–	Tagebucheinträge für Auswertungen und Archivierung
\`time-entries\`	✅	–	Stunden für Lohn und Nachkalkulation

Dazu kommen Webhooks: docubau meldet sich bei Ihrem System, sobald ein Mangel, eine Anzeige oder ein Eintrag entsteht oder sich ändert – signiert, mit Wiederholung bei Fehlern.

Drei Mechanismen machen den Sync robust:

1. \`external_ref\` – Ihre eigene ID auf jedem Objekt. Sie legen ein Projekt mit der ClickUp-Task-ID an; schicken Sie dieselbe ID noch einmal, wird aktualisiert statt dupliziert (Upsert). Kein Mapping-Table, keine doppelten Projekte.
2. \`updated_since\` – Jede Liste lässt sich auf „alles, was sich seit meinem letzten Lauf geändert hat" einschränken. Ein Poll alle fünf Minuten holt nur die Deltas.
3. \`project_id\` + \`source_entry_id\` – Jeder Mangel und jede Anzeige trägt das Projekt und den Tagebucheintrag, aus dem sie stammt. Die Zuordnung im Zielsystem ist damit automatisch.

Schritt für Schritt: Der bidirektionale Workflow

Nehmen wir den typischen Fall: Projekte leben in ClickUp, das Reporting in Power BI (oder Excel), die Baustelle dokumentiert mit docubau per WhatsApp.

Schritt 1: API-Schlüssel anlegen

In docubau unter *Einstellungen → API* einen Schlüssel mit Schreibzugriff erstellen. Der Schlüssel beginnt mit \`dbau_\` und wird als Bearer-Token gesendet. Für reine Auswertungen genügt ein Lese-Schlüssel – das Controlling bekommt so nie versehentlich Schreibrechte.

Schritt 2: Projekte aus ClickUp anlegen

Sobald ein ClickUp-Task den Status „Beauftragt" erreicht, ruft Ihre Automatisierung (ClickUp-Automation, Make, n8n, Zapier oder ein kleines Skript) einen POST auf:

\`\`\`bash curl -X POST "https://www.docubau.com/api/v1?resource=projects" \\ -H "Authorization: Bearer dbau_…" -H "Content-Type: application/json" \\ -d '{ "external_ref": "clickup:86c1x2y3", "name": "Neubau Wohnanlage Musterstraße", "project_number": "2026-014", "city": "München", "client_name": "Muster Immobilien GmbH", "status": "active", "jurisdiction": "vob_b" }' \`\`\`

Wechselt der Status in ClickUp auf „Abgeschlossen", schicken Sie denselben Aufruf mit \`"status": "completed"\` – die \`external_ref\` sorgt dafür, dass das bestehende Projekt aktualisiert wird.

Schritt 3: Gewerke und Nachunternehmer synchronisieren

Pro Vergabeeinheit ein Kontakt im Projekt:

\`\`\`bash curl -X POST "https://www.docubau.com/api/v1?resource=contacts" \\ -H "Authorization: Bearer dbau_…" -H "Content-Type: application/json" \\ -d '{ "project_id": "", "external_ref": "clickup:sub-4711", "role": "subcontractor", "company_name": "Elektro Huber GmbH", "trade": "Elektro" }' \`\`\`

Ab jetzt kann die Bauleitung auf der Baustelle Mängel direkt dem richtigen Nachunternehmer zuordnen – ohne dass jemand die Firma in docubau eintippen musste.

Schritt 4: Mängel und Anzeigen zurück ins Controlling

Zwei Wege, je nach Bedarf:

Polling – alle fünf Minuten die Deltas holen:

\`\`\`bash curl "https://www.docubau.com/api/v1?resource=defects&updated_since=2026-08-19T06:00:00Z&limit=100" \\ -H "Authorization: Bearer dbau_…" \`\`\`

Webhook – docubau meldet sich selbst:

\`\`\`bash curl -X POST "https://www.docubau.com/api/v1?resource=webhooks" \\ -H "Authorization: Bearer dbau_…" -H "Content-Type: application/json" \\ -d '{ "url": "https://hooks.ihre-firma.de/docubau", "events": ["defect.created", "defect.updated", "hindrance.created", "hindrance.updated"] }' \`\`\`

Jede Zustellung trägt eine HMAC-SHA256-Signatur im Header \`X-Docubau-Signature\`, sodass Ihr Empfänger prüfen kann, dass die Nachricht wirklich von docubau stammt. Im Payload stehen \`project_id\` (→ Ihr ClickUp-Projekt über dessen \`external_ref\`) und \`source_entry_id\` (→ der Tagebucheintrag) – Power BI oder ClickUp können den Mangel sofort richtig einsortieren.

Schritt 5: Der Rückkanal

Wird der Mangel in ClickUp erledigt, spielt Ihre Automatisierung das zurück:

\`\`\`bash curl -X PATCH "https://www.docubau.com/api/v1?resource=defects&id=" \\ -H "Authorization: Bearer dbau_…" -H "Content-Type: application/json" \\ -d '{ "status": "fixed", "external_ref": "clickup:task-9981" }' \`\`\`

Damit kennen sich beide Seiten, die Baustelle sieht den aktuellen Stand, und das Bautagebuch bleibt die eine, rechtssichere Quelle der Wahrheit.

Was das im Alltag bringt

• Keine doppelte Datenpflege: Projekte und Gewerke existieren genau einmal – dort, wo sie ohnehin gepflegt werden.
• Lückenloses Reporting: Jeder Mangel, jede Behinderungsanzeige erreicht das Controlling – automatisch, mit Zeitstempel und Zuordnung.
• Schnellere Reaktion: Webhooks bringen eine Behinderungsanzeige innerhalb von Sekunden zur Projektleitung, nicht erst mit dem Monatsexport.
• Nachvollziehbar: Jeder Schreibzugriff per API landet im Audit-Log des docubau-Kontos – mit Schlüssel-ID.

Für wen lohnt sich das?

Für Bauunternehmen, Generalunternehmer und größere Architekturbüros, die mehr als eine Handvoll Projekte parallel führen und bereits ein zentrales System für Projekte oder Controlling haben. Die Einrichtung ist eine Sache von Stunden, nicht Wochen – die Dokumentation mit allen Feldern, Statuswerten und Beispielen finden Sie unter docubau.com/de/api-docs, eine Übersicht der Integrationsszenarien unter docubau.com/de/integrationen.

Fazit

Ein digitales Bautagebuch spart auf der Baustelle Zeit. Richtig wertvoll wird es, wenn seine Daten auch im Büro ohne Umweg ankommen. Mit REST-API, \`external_ref\`, \`updated_since\` und Webhooks schließt docubau die Lücke zwischen Baustelle und Controlling – in beide Richtungen.

Business-Plan ansehen →