Integration of API mit Craftivo: Anleitung für Handwerker

Ein Malerbetrieb mit drei Kolonnen kennt den Ablauf: Im Büro entstehen Angebote, die Stunden kommen später von Zetteln zurück, und die Rechnung wird noch einmal ins Buchhaltungsprogramm übertragen. Bei jedem Wechsel können Angaben fehlen oder doppelt auftauchen. Eine API-Integration soll genau diese Handarbeit verringern, ohne neue Fehlerquellen zu schaffen.

Inhaltsverzeichnis

• Integration in sechs Schritten im Überblick
  • Die sechs Schritte
• Zugang einrichten und Zugangsdaten schützen
• Kundenstammdaten als erste Verbindung übertragen
  • So prüfst Du den ersten Datenfluss
• Rechnungen und Arbeitszeiten korrekt übergeben
• Fehler finden und Wiederholungen sicher abfangen
• Abnahmetest bestehen und die Anbindung live schalten
• Häufige Fragen zur Craftivo-API

Integration in sechs Schritten im Überblick

Eine API ist eine feste Schnittstelle, über die zwei Programme Daten austauschen. Niemand muss dafür Dateien hin- und herschieben oder dieselbe Kundenadresse erneut eintippen. Damit die Verbindung im Alltag hilft, sollte sie mit einem klar abgegrenzten Prozess starten.

Bevor Du loslegst, zählst Du, wie viele Minuten pro Angebot und Rechnung durch doppelte Eingaben verloren gehen. Rechne mit Deinen eigenen Werten. Eine Anbindung lohnt sich vor allem dann, wenn ein Ablauf häufig vorkommt, fehleranfällig ist und sich mit festen Regeln abbilden lässt.

Das Handwerk bewertet Digitalisierung nicht nur positiv, sondern hat auch mit praktischen Hürden zu tun: Laut dem Bitkom-Studienbericht zum Handwerk haben 49 Prozent der befragten Handwerksunternehmen Schwierigkeiten bei der Digitalisierung, während 89 Prozent sie grundsätzlich als Chance sehen. Darum brauchst Du neben der Technik einen verständlichen Ablauf und klare Zuständigkeiten.

Die sechs Schritte

1. Datenflüsse festlegen. Entscheide, welche Geschäftsobjekte zwischen den Programmen laufen sollen: Kunden, Projekte, Angebote, Rechnungen, Termine oder Arbeitszeiten. Lege für jedes Objekt fest, welches System die führenden Daten enthält.

2. Die Schnittstelle beschreiben. Eine versionierte OpenAPI-Spezifikation hält fest, welche Felder übertragen werden, welche Pflichtangaben gelten und welche Fehlercodes auftreten können. So wissen beide Seiten, was eine Anfrage enthalten muss.

3. Klein anfangen. Übertrage zuerst ein risikoarmes Objekt wie Kundenstammdaten nur in eine Richtung. Prüfe die Ergebnisse, bevor ein zweites Programm Daten zurückschreiben darf.

4. Zugriff absichern. Nutze eigene Zugangsdaten, begrenzte Rechte und eine verschlüsselte Verbindung. Die Details findest Du im Abschnitt zum Zugang.

5. Mit Testdaten prüfen. Verwende anonymisierte Daten. Simuliere Last, Fehler und wiederholte Anfragen, damit Du siehst, was bei Netzwerkausfällen oder doppelten Meldungen passiert.

6. Schrittweise erweitern. Erst wenn der erste Datenfluss stabil läuft, kommen bidirektionale Prozesse hinzu, zum Beispiel Rechnungsstatus oder Kalendertermine.

Objekt	Typischer Inhalt	Richtung	Risiko
Kunden	Name, Anschrift, Kontakt, Kundennummer	einseitig, Craftivo liefert	niedrig
Projekte	Projektnummer, Objektadresse, Status	einseitig, Craftivo liefert	niedrig
Angebote	Positionen, Mengen, Einheiten, Preise	einseitig, Craftivo liefert	mittel
Arbeitszeiten	Beginn, Ende, Dauer, Pausen	einseitig, ab Freigabe der Prüfung	mittel bis hoch
Rechnungen	Rechnungsnummer, Betrag, Zahlungsstatus	ab Schritt 6 bidirektional	hoch
Termine	Datum, Uhrzeit, Kolonne, Objekt	ab Schritt 6 bidirektional	hoch

Der Grund für die Reihenfolge ist einfach: Einen falschen Kundeneintrag kannst Du meist schnell korrigieren, eine fehlerhafte Rechnung im Buchhaltungsprogramm nicht so leicht.

Zugang einrichten und Zugangsdaten schützen

Ein Zugangsschlüssel im Quellcode oder in einem geteilten Chat kann Unbefugten den Weg zu Kunden- und Projektdaten öffnen. Behandle ihn deshalb wie einen Büroschlüssel. Ein Token ist ein befristeter digitaler Schlüssel. Least Privilege bedeutet, dass ein verbundenes Programm nur die Rechte erhält, die es tatsächlich braucht.

Richte die Verbindung in dieser Reihenfolge ein:

1. Eigenes Schnittstellenkonto anlegen. Verwende nicht die Admin-Anmeldung des Büroinhabers. So bleibt die Verbindung getrennt von persönlichen Konten und lässt sich gezielt sperren.

2. Authentifizierung klären. OAuth 2.0 oder kurzlebige Zugriffstoken sind geeignete Verfahren. Welche Methode für Dein Konto verfügbar ist, steht in der Craftivo-Dokumentation zur Authentifizierung.

3. Rechte einschränken. Wenn das Buchhaltungsprogramm nur Kunden lesen soll, gib ihm keine Schreibrechte für Rechnungen oder Arbeitszeiten.

4. Verbindung verschlüsseln. Übertrage Daten ausschließlich über TLS, also eine verschlüsselte HTTPS-Verbindung.

5. Zugangsdaten sicher ablegen. Nutze einen Passwort-Tresor oder Umgebungsvariablen. Speichere Zugangsdaten nie im Quellcode und teile sie nicht über einen normalen Gruppenchat.

6. Protokollierung einschalten. Halte fest, welches System wann Daten gelesen oder geschrieben hat. So kannst Du Änderungen einer Verbindung zuordnen.

Bevor Du Endpunkte freigibst, ordnest Du die Daten nach Zweck und Schutzbedarf. Kontaktdaten, Fotos, Arbeitszeiten und Rechnungsinformationen solltest Du getrennt betrachten und nur die nötigen Felder übertragen. Der BfDI-Leitfaden zu Datenschutz und IT-Sicherheit nennt Vertraulichkeit, Integrität und Verfügbarkeit als zentrale Schutzziele. Dazu passen klare Aufbewahrungsregeln, strenge Eingabeprüfungen und eine Möglichkeit, Daten nach einem Zwischenfall wiederherzustellen.

Praktische Regel: Jede schreibende Anfrage braucht eine stabile externe ID. So erzeugt ein erneuter Versuch nach einem Netzwerkausfall keine zweite Rechnung oder einen doppelten Zeiteintrag.

Ein häufiger Fehler ist ein gemeinsames Passwort, das nach einem Mitarbeiterwechsel aktiv bleibt. Endet die Zusammenarbeit mit einem Dienstleister oder wird ein Zugang nicht mehr gebraucht, widerrufe den Token sofort.

Kundenstammdaten als erste Verbindung übertragen

Kundenstammdaten sind ein guter Anfang: Sie enthalten überschaubare Felder, und ein Fehler lässt sich meist direkt berichtigen. Nimm die Hausverwaltung Weber als Beispiel. Sie braucht eine Rechnung für ein Mehrfamilienhaus in der Gartenstraße. Du legst den Kunden im Büro an und überträgst die Daten ins Buchhaltungsprogramm.

Für die Anfrage brauchst Du die passenden Felder und eine ID, an der das Fremdsystem den Kunden wiedererkennt. Ein mögliches Datenbeispiel sieht so aus: { "kundennummer": "K-1048", "name": "Hausverwaltung Weber", "anschrift": "Gartenstraße 12, 12345 Musterstadt", "e-mail": "buchhaltung@example.de", "telefon": "030 123456", "externe_id": "FREMD-7781" }. Setze den konkreten Endpunkt und die erforderliche Methode aus der Craftivo-Zugangsdokumentation ein, statt einen Pfad zu raten.

Ein Idempotency Key ist ein eindeutiger Schlüssel pro Anfrage. Wenn das Programm dieselbe Anfrage nach einem Netzwerkfehler noch einmal sendet, verhindert der Schlüssel, dass ein zweiter Kunde angelegt wird.

So prüfst Du den ersten Datenfluss

Lege zehn Testkunden an und kontrolliere anschließend drei Dinge:

• Anzahl: Sind im Zielsystem alle Testkunden vorhanden, aber keiner doppelt?
• Felder: Stimmen Name, Anschrift, Kundennummer und Kontaktdaten?
• Zuordnung: Verweist die externe ID auf denselben Kunden wie die Kundennummer?

Miss außerdem, wie viele Synchronisationen fehlerfrei durchlaufen und wie oft Mitarbeitende manuell nacharbeiten müssen. Mit der Zeit erkennst Du daran, ob die Verbindung Arbeit abnimmt oder nur eine zusätzliche Fehlerliste erzeugt.

Die API ordnet Daten typischerweise Ressourcen wie Kunden, Projekte, Angebote, Rechnungen, Terminen und Arbeitszeiten zu. Die genauen Pfade, Methoden und möglichen Webhook-Ereignisse findest Du in der Zugangsdokumentation. Starte mit dem nächsten Objekt erst, wenn der Kundensync eine fehlerfreie Testwoche durchlaufen hat.

Rechnungen und Arbeitszeiten korrekt übergeben

Bei einer Dachsanierung wird die Rechnung RE-2026-0142 an den Auftraggeber übergeben. Damit sie korrekt verarbeitet werden kann, sollten Rechnungsdatum, Nettobetrag, Umsatzsteuer und Zahlungsstatus als strukturierte Daten vorliegen. Eine PDF-Datei allein ist nicht automatisch eine E-Rechnung. Seit dem 1. Januar 2025 gelten bei inländischen B2B-Umsätzen grundsätzlich neue Vorgaben zur E-Rechnung. Das Bundesfinanzministerium erläutert die Regeln zur E-Rechnung.

Prüfe auch, ob für den Rechnungsempfänger eine Leitweg-ID erforderlich ist. Sie dient öffentlichen Stellen als elektronische Adresse für die Zuordnung und Weiterleitung der Rechnung.

Auftraggeber	Beispiel	Leitweg-ID nötig	Was Du tust
Private Kunden	Einfamilienhaus, Eigentümer	nein	Rechnung strukturiert übergeben
Gewerbekunden (B2B)	Bürogebäude einer GmbH	nein	Rechnung strukturiert übergeben
Hausverwaltung	Mehrfamilienhaus	nein	Feld leer lassen oder nur nach der tatsächlichen Vorgabe des Kunden befüllen. Keinen Platzhalter eintragen.
Öffentliche Stelle	Kommunale Schule	ja	Leitweg-ID des Auftraggebers übernehmen

Auch nach der Übergabe müssen Belege vollständig und Änderungen nachvollziehbar bleiben. Diese Anforderungen fasst der Begriff GoBD zusammen. Die Craftivo-API-Referenz zu unterstützten Feldern und Vorgaben hilft bei der Zuordnung der Rechnungsdaten.

Bei Arbeitszeiten sollte die Übergabe Beginn, Ende und Dauer enthalten. Das Bundesministerium für Arbeit und Soziales erläutert die Pflicht zur Arbeitszeiterfassung. Eine bestimmte technische Lösung ist dafür nicht vorgeschrieben.

Die Kolonne Schmitt beginnt um 7:00 Uhr auf der Baustelle und beendet die Arbeit um 16:00 Uhr. Bei 30 Minuten Pause ergibt das 8,5 Stunden Arbeitszeit. Übergib Beginn, Ende, Pause und berechnete Dauer, statt nur einen gerundeten Tageswert wie „8 Stunden“ zu speichern. In Craftivo bleiben erfasste Zeiten und Fortschrittsmeldungen am Projekt. Fotos und Berichte sind dort ebenfalls dem Auftrag zugeordnet, statt in privaten Bildergalerien zu liegen. Wird ein übergebener Eintrag korrigiert, sollte die Änderung mit Protokoll nachvollziehbar bleiben.

Fehler finden und Wiederholungen sicher abfangen

Ein abgelaufenes Token kann dazu führen, dass die API mit 401 antwortet. Das heißt meist, dass die Anfrage nicht gültig authentifiziert ist. Wiederhole sie nicht endlos, sondern prüfe zuerst den Zugang.

Statuscode	Bedeutung	Typische Ursache	Reaktion
400	Anfrage fehlerhaft	Feld fehlt oder Format ist falsch	Eingabedaten korrigieren
401	Nicht authentifiziert	Token fehlt oder ist abgelaufen	Zugang erneuern
403	Zugriff verweigert	Rolle hat nicht die nötigen Rechte	Berechtigungen prüfen
404	Ressource nicht gefunden	Pfad oder ID stimmt nicht	Endpunkt und Kennung prüfen
422	Daten nicht verarbeitbar	Feldinhalt verletzt eine Regel	Inhalt prüfen und berichtigen
429	Zu viele Anfragen	Grenze für Anfragen erreicht	Mit Pause erneut versuchen
500 bis 503	Serverfehler oder vorübergehende Nichtverfügbarkeit	API vorübergehend gestört	Mit Pause erneut versuchen

Automatisch wiederholst Du nur 429 und 500 bis 503. Nutze wachsende Pausen, zum Beispiel zwei, vier und acht Sekunden, und setze eine Obergrenze. Bei 400, 403, 404 und 422 prüfst Du Daten oder Rechte. Eine blinde Wiederholung behebt die Ursache nicht.

Ordne jeder Fehlermeldung eine Korrelations-ID zu. Das ist eine eindeutige Kennung, mit der Du die Anfrage im Protokoll wiederfindest. Die Craftivo-Dokumentation zu API-Fehlern hilft dabei, Antworten richtig einzuordnen.

Wenn eine Nachricht nach den vorgesehenen Versuchen weiter fehlschlägt, sollte sie in einer Dead-Letter-Warteschlange landen. Dort kann jemand den Fall prüfen, statt dass die Nachricht verschwindet oder ständig neu verarbeitet wird.

Webhooks sind automatische Meldungen, die ein System bei einem Ereignis an ein anderes schickt, etwa bei einem geänderten Termin. Falls Du sie nutzt, prüfe die Signatur der Meldung und plane ein, dass dieselbe Nachricht mehrfach eintreffen kann. Ob Webhooks und welche Anfragegrenzen für Dein Konto verfügbar sind, steht in der Zugangsdokumentation. Rate keine Grenzwerte.

Abnahmetest bestehen und die Anbindung live schalten

Bevor die Verbindung echte Betriebsdaten verarbeitet, teste gezielt die Fälle, die im Alltag sonst unangenehm auffallen. Craftivo bietet einen API-Zugang für externe Systeme. Nutze zuerst eine Testumgebung oder anonymisierte Daten und hake diese Prüfungen ab:

• Token-Diebstahl simulieren: Sperre den alten Token und prüfe, ob er danach nicht mehr funktioniert.
• Fehlende Berechtigung testen: Versuche einen Zugriff, den die Schnittstelle nicht haben soll. Das System muss ihn ablehnen.
• Manipulierte Anfrage senden: Übermittle fehlende oder ungültige Daten. Die API soll eine verständliche Fehlermeldung liefern.
• Doppelten Request auslösen: Sende dieselbe schreibende Anfrage erneut und prüfe, ob kein zweiter Datensatz entsteht.
• API-Ausfall simulieren: Kontrolliere, ob Wiederholungen begrenzt bleiben und fehlgeschlagene Nachrichten zur Prüfung landen.
• Backup einspielen: Stelle Daten wieder her und dokumentiere, wer den Ablauf ausführt.

Für den Pilotzeitraum setzt Du mindestens 99 Prozent erfolgreich verarbeitete Nachrichten als internes Qualitätsziel an. Das ist keine veröffentlichte Erfolgsquote für deutsche Betriebe. Zusätzlich darf es keine ungeklärten Berechtigungsverstöße geben, und eine dokumentierte Wiederanlaufprozedur muss vorliegen.

Lass den Kundenstamm-Sync zunächst zwei Wochen im Alltag laufen. Wenn die Daten sauber ankommen und die Fehlerfälle geklärt sind, schaltest Du den Rechnungsstatus frei. Einen Überblick über die Abläufe, die Craftivo abdeckt, findest Du unter Craftivos Funktionen. So kannst Du die Anbindung an den tatsächlichen Büro- und Baustellenprozess anpassen, statt alles auf einmal umzustellen.

Häufige Fragen zur Craftivo-API

Brauche ich Programmierkenntnisse? Nein. Eine Entwicklerin oder ein Dienstleister kann die Verbindung einrichten. Du entscheidest, welche Daten fließen und wer Zugriff erhält.

Was passiert bei einem Netzwerkfehler? Die Anbindung wiederholt nur bestimmte vorübergehende Fehler. Ein Idempotency Key verhindert, dass ein wiederholter Schreibvorgang einen doppelten Eintrag erzeugt.

Kann ich Daten zurück in Craftivo schreiben? Erst wenn Du die bidirektionale Verbindung freigibst. Welche Objekte sich dafür eignen, hängt von den verfügbaren Ressourcen und Berechtigungen ab.

Wie viele Anfragen sind erlaubt? Den Grenzwert findest Du in der Dokumentation. Rate ihn nicht, sondern prüfe die Angaben und die Antworten im Testsystem, bevor Du live gehst.

---

Mit Craftivo hältst Du Kunden, Projekte, Angebote, Rechnungen, Termine und Arbeitszeiten in einem gemeinsamen Arbeitsstand und kannst externe Systeme über den API-Zugang anbinden. Prüfe Deinen ersten Datenfluss mit einem Kundenstamm-Sync und teste Craftivo 14 Tage kostenlos.