Zu Content springen
  • Es gibt keine Vorschläge, da das Suchfeld leer ist.

Wie binde ich die Craftboxx per REST-API oder Webhook an?

Die Craftboxx per REST-API oder Webhook anbinden

Verbinde dein ERP-System oder Buchhaltungstool über die kostenlose REST-API oder Webhooks mit der Craftboxx. Du kannst damit Daten in der Craftboxx ändern, importieren oder exportieren.

Kurze Zusammenfassung für den Chatbot

  • Die REST-API verbindet ERP- oder Buchhaltungssysteme mit der Craftboxx – kostenlos, aber IT-Kenntnisse erforderlich
  • Über die API können u. a. Kunden-, Auftrags-, Mitarbeiter-, Abwesenheits-, Artikel-, Dokument- und Zeiterfassungsdaten gelesen oder geschrieben werden
  • Das API-Token holt man sich im Adminbereich unter Schnittstellen → API → „Selber bauen"; Authentifizierung per POST an /auth/create-token, danach als Bearer-Token im Authorization-Header
  • Der API-Zugriff folgt denselben Berechtigungen wie im Craftboxx Planner
  • Den Token nur einmal anfordern und für alle weiteren Anfragen wiederverwenden – wer je Anfrage einen neuen Token holt, bekommt 401 Unauthorized; dasselbe passiert bei ungültigem oder abgelaufenem Token
  • Mehrere with-Angaben immer als Array schreiben: with[]=tags&with[]=employees (URL-kodiert with%5B%5D=) – steht with= zweimal in der URL, gewinnt der letzte Wert
  • Mitarbeitende eines Termins abfragen: assignments/:appointmentId?with=employees
  • Labels heißen in der API tags
  • Die Projekt-ID ist der Wert hinter project= in der Planer-URL
  • site_notes = interne Planer-Notiz; internal_info = wichtiger Hinweis
  • Telefonnummern werden über die öffentliche Bibliothek libphonenumber geprüft (kein fester Regex); Ländercode muss korrekt gefüllt sein und die Ziffernanzahl zur Vorwahl passen
  • Arbeitszeiten: /timesheets, /timesheets/activities und /assignments bleiben verfügbar; sichere Felder sind duration_seconds (aus /timesheets/activities) und recorded_working_time_sum (aus /assignments) – von working_time und break_time aus /timesheets wird langfristig abgeraten, da sie die gesamte Arbeitszeit liefern, unabhängig von der Abrechenbarkeit
  • Webhooks benachrichtigen andere Systeme live über Änderungen in der Craftboxx (z. B. Status „fertig") und lösen dort automatisch Aktionen aus (z. B. Rechnungserstellung); eine eigene Doku gibt es dafür nicht, der Beispielrequest liegt unter Adminbereich → Schnittstellen → Webhook
  • Faustregel: REST-API zum aktiven Schreiben oder regelmäßigen Abfragen von Daten, Webhooks für sofortige Benachrichtigungen bei Ereignissen
  • Das Abnahme-PDF kann über die API erzeugt und abgerufen werden
  • Vor dem Start klären: Automatisierungsziel, Datenrichtung, zuständige Person/Dienstleister und Testumgebung
  • Vollständige technische Dokumentation unter https://api.craftboxx.de/

Was ist die REST-API?

Die REST-API ist eine webbasierte Schnittstelle der Cloudsoftware. Du kannst damit sämtliche Informationen in der Craftboxx ändern, importieren oder exportieren.

Du kannst folgende Daten ändern:

  • Kundendaten (Adressen, Namen etc.)
  • Aufträge und Termine
  • Mitarbeiter/in
  • Zugänge, Rollen und Lizenzen
  • Abwesenheiten
  • Artikel / Materialien
  • Dokumente (z. B. PDFs)
  • Fotos, Zeiteinträge etc. von der Baustelle
  • Stundenzettel / Lohnzeiten
  • Ressourcen, wie Werkzeuge oder Fahrzeuge

Was ist der Webhook?

Ein Webhook benachrichtigt ein anderes System über Änderungen in der Craftboxx (z. B. Status auf "fertig" gesetzt). Dadurch löst die andere Software ein Ereignis aus (z. B. Rechnungserstellung).

Webhook: Beispielrequest im Adminbereich

Eine eigene, ausführliche Webhook-Dokumentation gibt es nicht. Den Beispielrequest findest du direkt im Planer: Adminbereich → Schnittstellen → Webhook. Zusätzlich kannst du die vollständige API-Dokumentation unter api.craftboxx.de nutzen.

Für wen eignen sich REST-API oder Webhooks?

Die Schnittstellen sind für Firmen geeignet, die ihr ERP- oder Buchhaltungstool individuell an die Craftboxx anschließen wollen. Die Anbindung ist kostenlos, setzt jedoch IT-Kenntnisse voraus. Beispiele für bereits angeschlossene Systeme sind SAP, Microsoft Navision oder intern entwickelte ERPs.

Wie funktioniert es?

Die REST-API ist komplett dokumentiert. Du kannst die Dokumentation über diesen Link einsehen: https://api.craftboxx.de/.

Welche Daten kann ich mit der REST-API lesen oder schreiben?

Über die REST-API kannst du u. a. folgende Daten automatisiert verarbeiten:

  • Kunden- und Adressdaten
  • Aufträge und Termine
  • Mitarbeitende und Zugänge
  • Abwesenheiten
  • Artikel / Materialien
  • Dokumente (z. B. PDFs), Fotos und Zeiteinträge von der Baustelle
  • Stundenzettel / Lohnzeiten
  • Ressourcen (Fahrzeuge, Werkzeuge, Geräte)

💡 HINWEIS: Welche konkreten Endpunkte zur Verfügung stehen und welche Felder jeweils unterstützt werden, findest du in der technischen API-Dokumentation (z. B. für deine Entwickler:innen). Diese Dokumentation sollte immer als Referenz für Implementierungen genutzt werden.

REST-API oder Webhook – was ist wofür besser geeignet?

  • REST-API nutzen, wenn du …

    • Daten aktiv aus einem externen System in die Craftboxx schreiben möchtest (z. B. Kunden, Aufträge, Termine).
    • Daten regelmäßig aus der Craftboxx abfragen willst (z. B. für ein Reporting oder Data Warehouse).

  • Webhooks nutzen, wenn du …

    • andere Systeme „live“ informieren willst, sobald sich in der Craftboxx etwas ändert (z. B. Auftragsstatus „fertig“, neuer Zeiteintrag, neuer Auftrag).
    • in anderen Systemen automatisch Aktionen auslösen möchtest (z. B. Rechnung erstellen, Ticket anlegen), sobald ein Ereignis in der Craftboxx passiert.

Was sollte ich vor dem Start mit der API klären?

  1. Ziel definieren:
    • Was soll automatisiert werden (z. B. Kundenimport, Auftragsanlage, Status-Rückmeldung)?
  2. Richtung der Daten:
    • Sollen Daten nur in die Craftboxx, nur aus der Craftboxx oder in beide Richtungen laufen?
  3. Verantwortliche Person / Dienstleister:
    • Wer setzt die technische Anbindung um (interne IT, externer Dienstleister, Softwareanbieter)?
  4. Testumgebung:
    • Wenn möglich, zunächst mit Testdaten oder in einer Testumgebung starten, um falsche oder doppelte Einträge zu vermeiden.

💡 HINWEIS: Eine fehlerhafte API-Implementierung kann zu doppelten Datensätzen, falschen Status oder unvollständigen Auftragsdaten führen. Lass die Anbindung deshalb immer von technisch versierten Personen (Developer, IT, Anbieter des anderen Systems) durchführen und prüfe die Ergebnisse zu Beginn stichprobenartig.

Wie bekomme ich Zugangsdaten (API-Token) zur REST-API?

  1. Im Adminbereich anmelden: Melde dich in der Craftboxx Webversion mit einem Admin-Zugang an.
  2. Zu den Einstellungen wechseln: Klicke oben rechts auf Adminbereich -> Schnittstellen.
  3. API Dokumentation öffnen: Klicke bei API auf den Button "Selber bauen" und die Dokumentation öffnet sich.
  4. Unter "Authentication" Schritte folgen:
    Token abrufen: Sende eine POST-Anfrage mit deinen Mitarbeiter-Anmeldedaten (E-Mail-Adresse und Passwort) an den Endpunkt: /auth/create-token.

    Anfragen autorisieren: Füge das erhaltene Token bei jedem nachfolgenden API-Aufruf in den Authorization-Header ein. Der Header sollte wie folgt formatiert sein: Authorization: Bearer <YOUR_ACCESS_TOKEN>

    Dein API-Zugriff unterliegt denselben Berechtigungen, die du im Craftboxx Planner hast.
    Wenn dein Token ungültig oder abgelaufen ist, gibt die API den Statuscode 401 Unauthorized zurück.

Token nur einmal anfordern – sonst kommt ein 401

Fordere den Token einmal über die Authentication-Anfrage an und hänge ihn dann an alle weiteren Anfragen als Authorization: Bearer <YOUR_ACCESS_TOKEN>. Der Token muss nur einmal angefordert werden.

Wenn dein Skript für jede einzelne Anfrage einen neuen Token holt, laufen die Anfragen irgendwann auf 401 Unauthorized – typischerweise mitten in einer Paginierung, also zum Beispiel erst bei Seite 21 von /customers. Wenn dein Sync also nach vielen erfolgreichen Seiten abbricht, prüf zuerst, ob du pro Seite einen neuen Token anforderst.

Mehrere „with“-Parameter richtig schreiben

Über with forderst du zugeordnete Informationen mit an. Wenn du mehrere Angaben brauchst, musst du sie als Array schreiben:

Bei nur einer Angabe reicht die einfache Form, zum Beispiel für die Mitarbeitenden eines Termins: assignments/:appointmentId?with=employees. Die Information, wer einem Termin zugewiesen ist, kommt aus dem Termin selbst – nicht aus den Timesheet-Activities: dort steht nur, wer welche Zeit erfasst hat.

Wichtig für die Benennung: Labels heißen in der API „tags“. Wie du Labels anlegst und aktualisierst und welche Schemata es dafür gibt, steht in der API-Dokumentation.

Die Projekt-ID finden

Öffne den Auftrag im Planer und schau in die Browser-URL. Der Wert hinter project= ist die Projekt-ID, die du auch in der API verwendest.

site_notes und internal_info nicht verwechseln

Die beiden Notizfelder werden häufig vertauscht:

    • site_notes ist die Interne Planer-Notiz.
    • internal_info ist der Wichtige Hinweis.

Wenn Hinweise aus deinem Vorsystem in der Craftboxx im falschen Feld landen, ändere entsprechend den Request.

Telefonnummern: Prüfung über libphonenumber

Telefonnummern, die du über die API mitschickst, werden validiert. Schlägt die Validierung fehl, lässt sich der Auftrag nicht anlegen.

Die API nimmt eine normale Telefonnummer an und konvertiert sie automatisch in das Format mit „+“. Geprüft wird mit der öffentlichen Bibliothek libphonenumber. Einen festen Regex, den wir dir geben könnten, gibt es deshalb nicht. Zwei Dinge müssen stimmen:

    • Der Ländercode beim Kunden muss korrekt gefüllt sein.
    • Die Anzahl der Ziffern muss zur Vorwahl passen. Beispiele: hinter 0151 sind 7 oder 8 Ziffern zulässig, hinter 0171 sechs oder sieben. Steht dort eine Ziffer zu viel, gilt die Nummer als ungültig.

Am besten baust du dieselbe Prüfung in dein System ein, indem du libphonenumber dort ebenfalls einsetzt. Dann fällt eine fehlerhafte Nummer schon bei dir auf und nicht erst beim Anlegen des Auftrags.

Arbeitszeiten: welche Endpunkte und Felder dauerhaft nutzbar sind

Diese drei Endpunkte bleiben erhalten:

  1. GET /timesheets – einzelne Zeiterfassungseinträge (unter anderem working_time und break_time)
  2. GET /timesheets/activities – einzelne Tätigkeiten mit duration_seconds und dem Flag „abrechenbar“
  3. GET /assignments – enthält bereits recorded_working_time_sum

Unsere Empfehlung: Greife langfristig nicht auf working_time und break_time aus Punkt 1 zu. Diese Felder geben die gesamte Arbeitszeit zurück, unabhängig davon, ob sie abrechenbar ist. Am sichersten fährst du mit den Punkten 2 und 3.

Abnahme-PDF über die API erzeugen

Das PDF der Abnahme, das du in der Webansicht generieren kannst, lässt sich auch über die API erzeugen und abrufen – zum Beispiel, um es in deinem eigenen System an eine Rechnung anzuhängen.

Häufig gestellte Fragen - FAQ

  • Warum bekomme ich mitten in der Paginierung plötzlich einen 401? Meistens, weil pro Anfrage ein neuer Token angefordert wird. Fordere den Token einmal an und verwende ihn für alle weiteren Anfragen.
  • Warum liefert with=tags&with=employees keine Tags zurück? Weil bei zweimal with= nur der letzte Wert greift. Schreib es als Array: with[]=tags&with[]=employees.
  • Wie heißen Labels in der API? tags.
  • Wo sehe ich, wer einem Termin zugewiesen ist? Über assignments/:appointmentId?with=employees. Die Timesheet-Activities zeigen nur, wer Zeit erfasst hat.
  • Wo finde ich die Projekt-ID? In der Planer-URL hinter project=.
  • In welches Feld schreibe ich den Wichtigen Hinweis? In internal_info. site_notes ist die Interne Planer-Notiz.
  • Gibt es einen Regex für die Telefonnummer-Prüfung? Nein. Geprüft wird über libphonenumber; dieselbe Bibliothek kannst du in deinem System einsetzen.
  • Werden /timesheets und /timesheets/activities abgeschaltet? Nein, die Endpunkte bleiben. Von working_time und break_time wird langfristig abgeraten.
  • Gibt es eine Webhook-Dokumentation? Keine eigene. Der Beispielrequest steht unter Adminbereich → Schnittstellen → Webhook.
  • Kann ich das Abnahme-PDF über die API holen? Ja, das PDF kann über die API erzeugt und abgerufen werden.