Kontakt-API Logik
Technische Dokumentation der sevDesk Kontakt-Erstellung fuer Entwickler
sevDesk
API
Kontakte
CommunicationWay
Entwicklung
Kontakt-API Logik
Technische Dokumentation der sevDesk-Integration fuer die Kontakt-Erstellung und -Verwaltung. Diese Logik kann fuer andere sevDesk-Module wiederverwendet werden.
Hauptdatei: includes/class-sevdesk.php
Kontakttypen
sevDesk unterscheidet zwischen Privatpersonen und Organisationen.
Privatperson
Kontakt ohne Firmennamen - nur mit Vor-/Nachname.
| Feld | API-Key | Beispiel |
|---|---|---|
| Vorname | surename |
Max |
| Nachname | familyname |
Mustermann |
Organisation / Firma (B2B)
Kontakt mit Firmennamen - optional mit Ansprechpartner.
| Feld | API-Key | Beispiel |
|---|---|---|
| Firmenname | name |
Musterfirma GmbH |
| Vorname | surename |
Max (Ansprechpartner) |
| Nachname | familyname |
Mustermann |
Automatische Erkennung
Das Plugin erkennt automatisch, ob B2B oder B2C:
| Bedingung | Kontakttyp |
|---|---|
Feld firma/organisation ausgefuellt |
Organisation |
| Nur Name ausgefuellt | Privatperson |
CommunicationWays
Kommunikationskanaele werden separat vom Kontakt erstellt.
CommunicationWayType (Medium)
| ID | Typ | Beschreibung |
|---|---|---|
| 1 | phone | Telefon (Festnetz) |
| 2 | E-Mail-Adresse | |
| 3 | mobile | Mobiltelefon |
| 4 | fax | Faxnummer |
| 7 | web | Website |
CommunicationWayKey (Kategorie)
| ID | Key | Verwendung |
|---|---|---|
| 1 | Privat | Private Kontaktdaten |
| 2 | Arbeit | Geschaeftliche Daten (Telefon) |
| 8 | Rechnungsadresse | E-Mail fuer Rechnungsversand! |
E-Mail fuer Rechnungsversand
Damit sevDesk Rechnungen per E-Mail versenden kann, MUSS die E-Mail mit Key 8 (Rechnungsadresse) erstellt werden!
// RICHTIG: E-Mail mit Key 8
$data = array(
'type' => array(
'id' => 2, // Email
'objectName' => 'CommunicationWayType',
),
'key' => array(
'id' => 8, // Rechnungsadresse!
'objectName' => 'CommunicationWayKey',
),
'value' => 'kunde@example.com',
'main' => true,
);
Adressen
Adress-Kategorien
| ID | Kategorie | Beschreibung |
|---|---|---|
| 47 | Rechnungsadresse | Fuer Rechnungen |
| 48 | Lieferadresse | Fuer Lieferungen |
| 49 | Postadresse | Allgemeine Post |
Laender-IDs (StaticCountry)
| ID | ISO | Land |
|---|---|---|
| 1 | DE | Deutschland |
| 2 | AT | Oesterreich |
| 3 | CH | Schweiz |
| 4 | GB | Grossbritannien |
| 5 | US | USA |
| 6 | FR | Frankreich |
| 7 | IT | Italien |
| 8 | ES | Spanien |
| 9 | NL | Niederlande |
| 10 | BE | Belgien |
Default: Deutschland (ID 1)
Kontakt-Erstellung Workflow
1. Kontakt suchen (per E-Mail)
|
+-- Gefunden?
| |
| +-- Invoice E-Mail (Key 8) vorhanden?
| | +-- Nein: E-Mail mit Key 8 hinzufuegen
| |
| +-- Telefon vorhanden?
| +-- Nein: Telefon hinzufuegen
|
+-- Nicht gefunden?
|
+-- Neuen Kontakt erstellen
+-- CommunicationWays hinzufuegen
+-- Adresse erstellen
Feld-Mappings
Automatische Erkennung aus Formularfeldern
| Kategorie | Erkannte Feldnamen |
|---|---|
| Anrede | anrede, salutation, gender |
| Strasse | adresse, strasse, street |
| PLZ | plz, zip, postleitzahl |
| Ort | ort, stadt, city |
| Land | land, country |
| Firma | firma, organisation, organization, company |
Gender-Mapping
| Eingabe | sevDesk-Wert |
|---|---|
| Herr, Mr, male, m | m |
| Frau, Mrs, Ms, female, f | f |
Wichtige Methoden
| Methode | Beschreibung |
|---|---|
find_contact_by_email() |
Kontakt per E-Mail suchen |
create_contact() |
Neuen Kontakt erstellen |
add_communication_way() |
E-Mail/Telefon hinzufuegen |
has_invoice_email() |
Prueft ob Key 8 E-Mail existiert |
add_communication_way_if_missing() |
Duplikat-sichere Ergaenzung |
create_contact_address() |
Adresse erstellen |
get_or_create_contact_for_booking() |
Haupt-Workflow fuer Buchungen |
Checkliste fuer neue Module
Bei der Implementierung neuer sevDesk-Module beachten:
| Punkt | Beschreibung |
|---|---|
| E-Mail Key 8 | IMMER Key 8 (Rechnungsadresse) verwenden! |
| Land | Aus Formular extrahieren, Default: DE |
| Organisation | Firma-Feld = B2B-Kontakt |
| Existierende Kontakte | has_invoice_email() pruefen |
| Telefon | Mit add_communication_way_if_missing() |
| API-Token | Aus Einstellungen laden |
| Fehlerbehandlung | WP_Error verwenden |
| Logging | Fuer Debugging aktivieren |
Beispiel: Vollstaendige Kontakt-Erstellung
// 1. Kontakt-Daten aufbauen
$contact_data = array(
'category' => array(
'id' => 3, // Kunde
'objectName' => 'Category',
),
'surename' => 'Max',
'familyname' => 'Mustermann',
);
// 2. Bei B2B: Organisation hinzufuegen
if ( ! empty( $firma ) ) {
$contact_data['name'] = $firma;
}
// 3. Kontakt erstellen
$response = self::api_request( '/Contact', 'POST', $contact_data );
$contact_id = (int) $response['objects']['id'];
// 4. E-Mail mit Key 8 hinzufuegen
self::add_communication_way( $contact_id, 'email', $email );
// 5. Telefon hinzufuegen
if ( ! empty( $phone ) ) {
self::add_communication_way( $contact_id, 'phone', $phone );
}
// 6. Adresse hinzufuegen
$address_data = array(
'contact' => array( 'id' => $contact_id, 'objectName' => 'Contact' ),
'category' => array( 'id' => 47, 'objectName' => 'Category' ), // Rechnungsadresse
'street' => 'Musterstrasse 1',
'zip' => '1010',
'city' => 'Wien',
'country' => array( 'id' => 2, 'objectName' => 'StaticCountry' ), // AT
);
self::api_request( '/ContactAddress', 'POST', $address_data );
Aenderungshistorie
| Datum | Aenderung |
|---|---|
| 06.01.2026 | E-Mail Key auf 8 (Rechnungsadresse) geaendert |
| 06.01.2026 | Land-Extraktion aus custom_fields |
| 06.01.2026 | has_invoice_email() fuer existierende Kontakte |
| 06.01.2026 | Organisation/Firma Legacy-Fallback |
Letzte Aktualisierung: 06.01.2026