ERP- und Kassensystem anbinden — einfache Anleitung

Viele Werkstätten nutzen neben repair.Dspatcha noch ein weiteres Programm — eine Warenwirtschaft, ein Kassensystem oder eine ERP-Software. Ohne Anbindung bedeutet das: jeden Auftrag zweimal eingeben.

Mit dem Integrationen-Tab kannst du dieses Doppel-Tippen abstellen. Du erzeugst einen sogenannten API-Key — einen Zugangsschlüssel, den du einmal in deinem anderen System einträgst. Ab dann holt sich dein ERP oder deine Kasse die Auftragsdaten automatisch aus repair.Dspatcha heraus, ohne dass du etwas tun musst.

Kund:innen melden ihre Aufträge weiterhin wie gewohnt über das Anmeldeformular an. Dein externes System liest diese Daten dann bei Bedarf ab.

Du findest alles unter Team → Einstellungen → Integrationen.

Keine Sorge: Du kannst hier nichts kaputtmachen. Ein Key, der versehentlich angelegt wurde, lässt sich jederzeit mit einem Klick widerrufen — das passiert sofort und kann nicht vom externen System umgangen werden.

1. Einen neuen API-Key erstellen

1. Klicke oben rechts auf das +-Symbol.

2. Trage im Feld Bezeichnung einen Namen ein, an dem du den Key später erkennst — zum Beispiel den Namen deines Systems (Warenwirtschaft Filiale Mitte). Die Bezeichnung ist nur für dich sichtbar.

3. Wähle die Berechtigungen, die das externe System braucht:

   Berechtigung	Was dein externes System damit tun kann
   Aufträge lesen	Aufträge abrufen inkl. aller Kundendaten des Auftrags
   Aufträge schreiben	Kostenrahmen am Auftrag aktualisieren
   Status setzen	Status-Übergänge im Namen des ERP auslösen
   Nachrichten schreiben	Auf Kundenrückfragen antworten

   Aktiviere nur, was wirklich benötigt wird. Ein reines Lese-System braucht nur Aufträge lesen. Eine Warenwirtschaft, die den Workflow übernimmt, braucht zusätzlich Status setzen.

4. Klicke auf „Key erstellen".

Den Key sofort sichern

Direkt nach dem Erstellen zeigt repair.Dspatcha dir den vollständigen Schlüssel — er sieht ungefähr so aus:

dsp_a1b2c3d4e5f6a7b8.0011223344556677889900aabbccddeeff

Wichtig: Dieser Schlüssel wird nur einmal angezeigt. Kopiere ihn mit dem Kopieren-Symbol und trage ihn sofort in dein ERP- oder Kassensystem ein. Danach klicke auf „Verstanden, Key gespeichert", um den Dialog zu schließen.

Wenn du den Key nicht mehr hast, kannst du ihn nicht wiederherstellen — dann musst du ihn widerrufen und einen neuen erstellen.

2. Deine Keys im Überblick

Nach dem Erstellen siehst du alle aktiven Keys in einer Liste. Zu jedem Key sind folgende Informationen sichtbar:

• Die Bezeichnung, die du vergeben hast.
• Die ersten Zeichen des Keys (z. B. dsp_a1b2c3d4e5f6a7b8…) — der Rest bleibt verborgen. So erkennst du den Key, ohne ihn zu gefährden.
• Die Berechtigungen des Keys als kleine Kacheln.
• Zuletzt benutzt: Wann das externe System zuletzt Daten abgerufen hat.
• Erstellt: Wann der Key angelegt wurde.

3. Einen Key widerrufen

Wenn du ein System abklemmen möchtest, oder wenn du befürchtest, dass ein Key in falsche Hände geraten ist:

1. Klicke auf das ⊘-Symbol neben dem Key.
2. Bestätige im Dialog mit „Widerrufen".

Der Key ist sofort ungültig — das externe System bekommt ab diesem Moment keine Daten mehr. Widerrufene Keys werden ausgegraut angezeigt; du kannst sie nicht reaktivieren. Erstelle stattdessen einen neuen Key und trage ihn im externen System ein.

Empfehlung: Erstelle pro angebundenes System einen eigenen Key. So kannst du einzelne Systeme abklemmen, ohne andere zu beeinflussen.

4. Wie der Import-Zyklus funktioniert

Damit dein ERP jeden Auftrag nur einmal importiert, nutzt es den Status als Markierung:

1. Das ERP fragt alle Aufträge mit Status „Angemeldet" (10) ab — das sind alle noch nicht verarbeiteten Aufträge.
2. Es legt im eigenen System einen Vorgang an und verknüpft ihn mit dem repair.Dspatcha-Auftrag.
3. Es setzt den Auftrag in repair.Dspatcha auf den nächsten Status — typischerweise „Angenommen" (20). Das ist der entscheidende Schritt: der Statuswechsel signalisiert repair.Dspatcha, dass das ERP den Auftrag übernommen hat.
4. Beim nächsten Abruf sind diese Aufträge nicht mehr im Status 10 und tauchen deshalb nicht erneut in der Importliste auf.

Für den Statuswechsel aus dem ERP benötigt der API-Key die Berechtigung „Status setzen".

Tipp: Falls ein Import fehlschlägt, bevor der Statuswechsel ausgelöst wurde, wird der Auftrag beim nächsten Lauf erneut geliefert — der Zyklus ist idempotent. Stellt dein ERP-System sicher, dass der Statuswechsel erst nach erfolgreichem Import ausgelöst wird.

Gut zu wissen: Die Werkstatt-Mitarbeitenden sehen in repair.Dspatcha den aktuellen Status — auch wenn dieser vom ERP gesetzt wurde. Kunden erhalten automatisch eine Benachrichtigung, wenn der Status einen konfigurierten Übergang auslöst (z. B. „Reparatur abgeschlossen").

5. Feld-Mapping: Datenstruktur ans ERP anpassen

Jede Werkstatt kann ihr Anmeldeformular individuell gestalten. Felder wie „Nachname", „Vorname" oder „Versicherungsnummer" heißen in repair.Dspatcha intern anders als im ERP — und manchmal erwartet das ERP eine ganz andere Struktur.

Mit dem Feld-Mapping legst du pro API-Key fest, wie die Auftragsdaten aufgebaut sein sollen, wenn dein ERP sie abruft. Du definierst die Zielstruktur als JSON und setzt Platzhalter für die Felder aus repair.Dspatcha ein.

Für ERP-Entwickler: Die vollständige technische Dokumentation aller Endpunkte, Parameter und Datenstrukturen findest du in der OpenAPI-Spezifikation (Partner API).

Mapping öffnen

1. Klicke neben dem gewünschten Key auf das Code-Symbol (Terminal-Icon).
2. Der Mapping-Dialog öffnet sich. Ohne Eintrag liefert die API die Standardstruktur.

Wie das Mapping aufgebaut ist

Das JSON beschreibt die gewünschte Ausgabe — die Platzhalter werden beim Abruf durch die echten Werte ersetzt:

{
  "auftrag_nr": "{{order.short_id}}",
  "status": "{{order.status}}",
  "nachname": "{{order.customer_name}}",
  "kundendaten": {
    "vorname": "{{order.custom_fields.vorname}}",
    "email": "{{order.customer_email}}",
    "telefon": "{{order.customer_phone}}"
  },
  "geraet": "{{order.item_name}}",
  "seriennummer": "{{order.custom_fields.seriennummer}}"
}

Das ERP empfängt dann genau diese Struktur mit den eingesetzten Werten — ohne dass es die repair.Dspatcha-Feldnamen kennen muss.

Verfügbare Platzhalter

Die Zusatzfelder deines Anmeldeformulars werden im Mapping-Dialog als klickbare Chips angezeigt — du siehst auf einen Blick, welche Felder verfügbar sind, und fügst sie per Klick ein.

Tipp: Belasse das Mapping leer, wenn dein ERP die Standard-Struktur von repair.Dspatcha direkt verarbeiten kann. Das Mapping ist nur nötig, wenn das ERP eine eigene Feldstruktur erwartet.

6. Mehrere Filialen anbinden

Wenn du mehrere Standorte betreibst, kann dein ERP-System die Aufträge nach Filiale getrennt verarbeiten.

Einen Key pro Filiale

Erstelle für jede Filiale einen eigenen API-Key. Das System stellt dann automatisch sicher, dass dieser Key nur Aufträge der jeweiligen Filiale sieht — kein weiterer Filter nötig.

Vergib sprechende Bezeichnungen wie ERP Filiale Mitte und ERP Filiale Prenzlauer Berg, damit du den Überblick behältst.

Einen Key für alle Filialen

Alternativ kannst du einen einzigen Key für alle Filialen verwenden und im ERP per Filial-ID filtern. Dein ERP-Entwickler kann:

• Mit GET /branches alle Filial-IDs und -Namen abrufen — einmalig beim Start, um eine interne Zuordnung aufzubauen.
• Bei den Auftrags- und Event-Abfragen den Parameter branch_id setzen, um nur Aufträge einer bestimmten Filiale zu erhalten.

Gut zu wissen: Die Filial-IDs (branch_id) sind stabile UUIDs (eine feste interne Kennung) — sie ändern sich nie, auch wenn der Filialname umbenannt wird.

7. Einzelauftrag abrufen: Verlauf und Nachrichten

Wenn dein ERP einen bestimmten Auftrag genauer unter die Lupe nehmen möchte — zum Beispiel um den aktuellen Stand nach einer Statusänderung zu prüfen — gibt es neben der Auftragsliste auch einen Endpunkt für einen einzelnen Auftrag. Dieser liefert deutlich mehr Informationen als die Liste.

Du rufst ihn so ab:

GET /api/v1/{werkstatt-slug}/orders/{order_id}

Zusätzlich zu den Basis-Feldern (Name, Gerät, Status, Kostenrahmen usw.) enthält die Antwort:

Freigabe der Kostenschätzung abfragen

Der häufigste Grund, einen Einzelauftrag gezielt abzurufen: das ERP möchte wissen, ob die Kund:in die Kostenschätzung bereits freigegeben hat, damit die Reparatur gestartet werden kann.

Dafür genügt ein einfacher Vergleich im ERP: Ist confirmed_at gesetzt (also kein null), hat die Kund:in freigegeben. Ist confirmed_at null, wartet der Auftrag noch auf Rückmeldung.

Tipp: Statt in kurzen Abständen immer wieder nachzufragen, lässt sich der aktuelle Status auch über GET /orders?status=50 abfragen (Status 50 = Freigegeben). So holt sich das ERP nur Aufträge, bei denen tatsächlich etwas passiert ist.

Nachrichten der Kund:in lesen

Über das messages-Array bekommt dein ERP alle Textnachrichten zu einem Auftrag — sowohl Nachrichten, die die Kund:in geschickt hat (sender_type: customer), als auch Antworten deines Teams (sender_type: team). So kann das ERP zum Beispiel prüfen, ob eine Kund:in eine Rückfrage gestellt hat, bevor es einen nächsten Schritt auslöst.

Gut zu wissen: Wie du per ERP eine Kostenschätzung sendest und den Auftrag in den Status „Wartet auf Freigabe" versetzt, beschreibt die separate Anleitung [[erp-kostenschaetzung|Kostenschätzung per ERP senden]].

8. Datenschutz-Hinweis (Pflicht nach DSGVO)

Aufträge enthalten Kundendaten — Name, E-Mail-Adresse und Telefonnummer. Wenn du diese Daten über die Schnittstelle an ein externes System überträgst, bist du nach der Datenschutz-Grundverordnung (DSGVO) verpflichtet, mit dem Betreiber dieses Systems einen Auftragsverarbeitungsvertrag (AVV) abzuschließen. Frag den Anbieter deiner Software danach — die meisten stellen diesen Vertrag auf Anfrage bereit.

Häufige Fragen

Mein ERP fragt nach einer „API-Adresse" oder „Endpunkt-URL". Was trage ich ein? Die Basis-URL findest du direkt unter Team → Einstellungen → Integrationen — sie wird dort mit einem Kopieren-Symbol angezeigt. Darunter siehst du auch alle verfügbaren Endpunkte mit den jeweils benötigten Berechtigungen.

Wie bekommt mein ERP-Entwickler die technische Dokumentation? Die vollständige API-Dokumentation ist öffentlich erreichbar — kein Login erforderlich. Du findest die direkte URL unter Team → Einstellungen → Integrationen ganz unten im Abschnitt „API-Endpunkte". Dort gibt es ein Kopieren-Symbol neben der URL. Kopiere sie und schicke sie an den Entwickler deines ERP-Systems. Alternativ: OpenAPI-Spezifikation direkt aufrufen.

Ich sehe den Tab „Integrationen" nicht. Warum? Der Tab ist nur für Werkstatt-Admins sichtbar. Mitarbeiter haben keinen Zugriff. Außerdem muss das Feature für dein Paket freigeschaltet sein — sieh unten.

Kann mein ERP Aufträge anlegen? Nein — Aufträge entstehen ausschließlich über das Anmeldeformular oder werden manuell im Team-Dashboard angelegt. Das ERP kann Aufträge lesen, den Kostenrahmen aktualisieren und Status-Übergänge auslösen — aber keine neuen Aufträge erzeugen.

Muss das ERP nach jedem Import einen Statuswechsel auslösen? Ja, das wird so empfohlen. Ohne Statuswechsel würde der Auftrag bei jedem Abruf erneut geliefert und müsste vom ERP selbst als „bereits importiert" erkannt werden — was fehleranfälliger ist. Mit dem Statuswechsel übernimmt repair.Dspatcha diese Markierung automatisch.

Mein ERP erwartet andere Feldnamen als repair.Dspatcha liefert. Was tun? Richte ein Feld-Mapping für den API-Key ein (Abschnitt 5). Damit legst du fest, wie die Daten strukturiert und benannt sein sollen — ohne Änderungen am ERP.

Wie oft darf mein ERP Daten abrufen? Standardmäßig bis zu 60 Mal pro Minute pro Key. Das reicht für nahezu alle Anwendungsfälle. Bei Bedarf wende dich an repair.Dspatcha.

Was passiert, wenn ich den Key verliere? Widerrufe den alten Key (Abschnitt 3) und erstelle einen neuen (Abschnitt 1). Der alte Key ist danach sofort ungültig.

Wie erkennt mein ERP, ob eine Kund:in die Kostenschätzung freigegeben hat? Rufe den Einzelauftrag über GET /orders/{order_id} ab und prüfe das Feld confirmed_at. Ist es gesetzt, hat die Kund:in freigegeben. Ist es null, wartet der Auftrag noch. Alternativ filtert GET /orders?status=50 direkt alle freigegebenen Aufträge heraus.

Kann mein ERP Nachrichten lesen, die eine Kund:in über die Auftragsseite geschickt hat? Ja — das Feld messages im Einzelauftrag-Response (GET /orders/{order_id}) enthält alle Nachrichten chronologisch. Das Feld sender_type gibt an, ob die Nachricht von der Kund:in (customer) oder vom Team (team) stammt.

Integrationen ist ein Pro-Feature. Sollte der Tab bei dir nicht sichtbar sein oder gesperrt erscheinen, ist das Feature für deinen aktuellen Tarif noch nicht freigeschaltet. Wende dich an repair.Dspatcha, um es zu aktivieren.