Rezept: SevDesk-Kontakte synchronisieren

Dieses Rezept legt neue Kontakte aus Centrics automatisch in SevDesk an und hält ihren Namen aktuell. Es besteht aus zwei Arten von Webhooks:

1. Anlegen: ein Webhook pro Kontakttyp, der den Kontakt in SevDesk anlegt und die SevDesk-ID am Kontakt speichert.
2. Aktualisieren: ein Webhook, der verknüpfte Kontakte in SevDesk aktualisiert.

Voraussetzungen

• Du hast die Rolle Manager, und Webhooks sind für Deinen Account freigeschaltet (siehe Überblick).
• Du hast einen API-Token für SevDesk.
• Du kennst die IDs der SevDesk-Kategorien, die Deinen Kontakttypen in Centrics entsprechen (siehe unten).

Grenze von fünf Webhooks

Ein Account hat höchstens fünf Webhooks. Mit drei Kontakttypen brauchst Du vier: drei zum Anlegen und einen zum Aktualisieren. Hast Du mehr als vier Kontakttypen, reicht die Grenze nicht aus – wende Dich dann an das Centrics-Team.

Warum ein Anlege-Webhook pro Kontakttyp?

SevDesk ordnet jeden Kontakt einer Kategorie zu, z. B. Kunde, Lieferant oder Partner. Die Kategorie-ID steht fest im Inhalt des Webhooks. Damit jeder Kontakt die richtige Kategorie bekommt, legst Du pro Kontakttyp einen eigenen Anlege-Webhook an und schränkst ihn über Typen auf diesen Typ ein.

Kategorie-IDs in SevDesk prüfen

Die Kategorie-IDs in diesem Rezept (Kunde 3, Lieferant 2, Partner 4) sind nur Beispiele und nicht geprüft. Schlage die tatsächlichen IDs in Deinem SevDesk nach, bevor Du speicherst. Ein neuer Webhook ist sofort aktiv.

Schritt 1: Anlege-Webhook für Kunden

Öffne Management → Webhooks → Neuer Webhook und fülle die Abschnitte so aus:

Ziel

Feld	Wert
Name	SevDesk – Kunden anlegen
Methode	POST
URL	https://my.sevdesk.de/api/v1/Contact
Header	Name Authorization, Wert: Dein SevDesk-API-Token

Kein „Bearer“

SevDesk erwartet den Token direkt im Header Authorization, ohne vorangestelltes Bearer.

Auslöser

Feld	Wert
Ressource	Kontakt
Ereignisse	nur Erstellt (Aktualisiert und Gelöscht abwählen)
Typen	Dein Kontakttyp für Kunden, z. B. „Kunde“

Verknüpfung

Feld	Wert
Angelegten Datensatz verknüpfen	eingeschaltet
Referenz	SevDesk
Pfad der ID in der Antwort	objects.id

Inhalt

Wähle als Format Benutzerdefiniert und trage diese Vorlage ein:

{
  "name": "{{ contact.name }}",
  "customerNumber": "{{ contact.number }}",
  "category": { "id": 3, "objectName": "Category" }
}

Passe die Kategorie-ID an Deinen SevDesk an. Ob SevDesk die Felder in dieser Form erwartet, prüfst Du am besten mit dem Test in Schritt 2.

Schritt 2: Testen und speichern

1. Wähle in der Vorschau unter Beispiel die Option Echte Ressource und such einen Kontakt aus, den es in SevDesk noch nicht gibt.
2. Klicke auf Test senden.
3. Prüfe den HTTP-Status und die Antwort. Steht die ID nicht unter objects.id, klicke in der Antwort auf die ID, um ihren Pfad zu übernehmen.
4. Klicke auf Speichern.

Der Test legt einen echten Kontakt an

Test senden schickt eine echte Anfrage an SevDesk – der Kontakt wird dort wirklich angelegt. Verknüpft wird beim Test aber nicht. Der von Test senden angelegte SevDesk-Kontakt ist nicht mit dem Centrics-Kontakt verknüpft. Lösche ihn danach in SevDesk – oder teste mit einem frisch angelegten Kontakt bzw. mit Beispieldaten.

Schritt 3: Weitere Kontakttypen

Öffne in der Liste das Menü … des Kunden-Webhooks und wähle Duplizieren. Die Kopie übernimmt alle Einstellungen samt Token und ist zunächst inaktiv. Ändere in der Kopie:

• Name, z. B. SevDesk – Lieferanten anlegen,
• Typen auf den passenden Kontakttyp,
• die Kategorie-ID in der Vorlage.

Speichere die Kopie und schalte sie über Aktivieren ein. Wiederhole das für jeden weiteren Kontakttyp.

Schritt 4: Update-Webhook

Lege einen weiteren Webhook an:

Feld	Wert
Name	SevDesk – Kontakte aktualisieren
Methode	PUT
URL	https://my.sevdesk.de/api/v1/Contact/{{ contact.external_refs.sevdesk }}
Header	Name Authorization, Wert: Dein SevDesk-API-Token
Ressource	Kontakt
Ereignisse	nur Aktualisiert
Typen	leer (alle Typen)
Beobachtete Felder	z. B. nur Name
Verknüpfung	ausgeschaltet
Format	Benutzerdefiniert

Vorlage:

{
  "name": "{{ contact.name }}"
}

Die Vorlage enthält bewusst nur den Namen. Die Kundennummer sendet nur der Anlege-Webhook: Centrics vergibt beim Import teilweise eigene Nummern, und ein Update würde sonst die Nummer in SevDesk bei jeder Namensänderung überschreiben.

Der Platzhalter {{ contact.external_refs.sevdesk }} in der URL setzt die SevDesk-ID ein, die der Anlege-Webhook gespeichert hat.

Verknüpfung im Update-Webhook ausschalten

Lass Angelegten Datensatz verknüpfen im Update-Webhook aus. Ein Webhook mit Verknüpfung überspringt bereits verknüpfte Kontakte – und genau die willst Du hier aktualisieren.

Kontakte ohne SevDesk-ID

Ändert sich ein Kontakt, der noch keine SevDesk-ID hat, kann die URL nicht gebildet werden. Die Zustellung endet dann als Fehlgeschlagen mit dem Hinweis, dass contact.external_refs.sevdesk leer ist – ohne Wiederholung und ohne Folgen für den Webhook. Kontakte, die Du mit dem Kontakt-Import aus SevDesk übernommen hast, sind bereits verknüpft.

Was dieses Rezept nicht abdeckt

• Adressen, E-Mail-Adressen und Telefonnummern: In SevDesk sind das eigene Objekte neben dem Kontakt. Die Webhooks oben übertragen sie nicht.
• Bestehende Kontakte: Kontakte, die schon vor dem Webhook existieren, werden nicht nachträglich nach SevDesk übertragen. Der Anlege-Webhook reagiert nur auf Erstellt. Ändert sich ein solcher Kontakt, scheitert der Update-Webhook mit einem Vorlagenfehler, weil die SevDesk-ID fehlt (siehe oben). Das ist harmlos, der Kontakt bleibt aber unverändert in SevDesk, bis Du ihn dort anlegst oder über den Kontakt-Import verknüpfst.
• Typwechsel: Wechselt ein Kontakt den Typ, ändert sich seine Kategorie in SevDesk nicht. Der Anlege-Webhook des neuen Typs überspringt den Kontakt, weil er bereits verknüpft ist.
• Löschen: Gelöschte Kontakte bleiben in SevDesk bestehen.