Customer Settings API – Kundenanleitung

Übersicht

Die Customer Settings API ermöglicht die Verwaltung von Kundenstammdaten, Niederlassungen/Adressen, Kontaktinformationen (Rufnummern, E-Mail-Adressen, Webseiten), Organisationsstrukturen, Abteilungen, Benutzer (Mitarbeiter) und Benutzergruppen. Alle Änderungen werden sofort wirksam.

Authentifizierung

Alle API-Aufrufe erfordern einen Bearer-Token im HTTP-Header:

Authorization: Bearer {API_TOKEN}

Token generieren

Der Token wird über die Web-Oberfläche generiert (erfordert eine aktive Session):

POST /customer/api-tokens/generate

Response:

json

{
  "success": true,
  "token": "2|RHej0fNgjGSzvPrEcSuY7nMGI7fldCnOMoBrpl2T173373b5",
  "message": "API Token erfolgreich generiert"
}

Wichtig: Speichern Sie den Token sicher ab. Er wird nur einmal im Klartext angezeigt.

Base-URL

https://platform.passolution.de/api

1. Stammdaten (Master Data)

Firmendaten abrufen

GET /v1/customer/settings

Gibt die vollständigen Kundenstammdaten zurück, inklusive Firmenanschrift, Rechnungsadresse, Kundentyp und Branchentyp.

Beispiel:

bash

curl -X GET https://platform.passolution.de/api/v1/customer/settings \
  -H "Authorization: Bearer {TOKEN}" \
  -H "Accept: application/json"

Response (200 OK):

json

{
  "success": true,
  "data": {
    "company_name": "Musterfirma GmbH",
    "customer_type": "business",
    "business_type": "travel_agency",
    "company_address": {
      "name": "Musterfirma GmbH",
      "street": "Musterstraße",
      "house_number": "1",
      "postal_code": "80331",
      "city": "München",
      "country": "DE"
    },
    "billing_address": {
      "name": "Musterfirma GmbH – Buchhaltung",
      "street": "Musterstraße",
      "house_number": "1",
      "postal_code": "80331",
      "city": "München",
      "country": "DE"
    }
  }
}

Firmenanschrift aktualisieren

PUT /v1/customer/settings/company-address

Feld	Typ	Pflicht	Beschreibung
`name`	string	Ja	Firmenname
`additional`	string	Nein	Adresszusatz
`street`	string	Ja	Straße
`house_number`	string	Nein	Hausnummer
`postal_code`	string	Ja	Postleitzahl
`city`	string	Ja	Stadt
`country`	string	Ja	Ländercode (ISO alpha-2, z.B. `DE`)

Beispiel:

bash

curl -X PUT https://platform.passolution.de/api/v1/customer/settings/company-address \
  -H "Authorization: Bearer {TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Musterfirma GmbH",
    "street": "Neue Straße",
    "house_number": "42",
    "postal_code": "80333",
    "city": "München",
    "country": "DE"
  }'

Response (200 OK):

json

{
  "success": true,
  "message": "Firmenanschrift erfolgreich aktualisiert"
}

Hinweis: Die Firmenanschrift kann über die API aktualisiert, aber nicht gelöscht werden.

Rechnungsadresse aktualisieren

PUT /v1/customer/settings/billing-address

Die Felder sind identisch zur Firmenanschrift (siehe oben).

Hinweis: Die Rechnungsadresse kann über die API aktualisiert, aber nicht gelöscht werden.

Kundentyp ändern

PUT /v1/customer/settings/customer-type

Feld	Typ	Pflicht	Beschreibung
`customer_type`	string	Ja	`private` oder `business`

Branchentyp ändern

PUT /v1/customer/settings/business-type

Feld	Typ	Pflicht	Beschreibung
`business_type`	string	Ja	Branchentyp (z.B. `travel_agency`, `corporate`, `insurance`)

2. Adressen (Branches)

Alle Adressen auflisten

GET /v1/customer/branches

Query-Parameter:

Parameter	Typ	Beschreibung
`search`	string	Volltextsuche über Name, Straße, Stadt
`city`	string	Filterung nach Stadt

Beispiel:

bash

curl -X GET "https://platform.passolution.de/api/v1/customer/branches?city=München" \
  -H "Authorization: Bearer {TOKEN}" \
  -H "Accept: application/json"

Einzelne Adresse abrufen

GET /v1/customer/branches/{id}

Neue Adresse anlegen

POST /v1/customer/branches

Feld	Typ	Pflicht	Beschreibung
`name`	string	Ja	Name der Niederlassung
`additional`	string	Nein	Adresszusatz
`street`	string	Ja	Straße
`house_number`	string	Nein	Hausnummer
`postal_code`	string	Ja	Postleitzahl
`city`	string	Ja	Stadt
`country`	string	Ja	Ländercode (ISO alpha-2, z.B. `DE`)
`org_node_ids`	array	Nein	IDs bestehender Organisationsknoten
`org_node_data`	array	Nein	Daten für neue Organisationsknoten

Beispiel:

bash

curl -X POST https://platform.passolution.de/api/v1/customer/branches \
  -H "Authorization: Bearer {TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Niederlassung Hamburg",
    "street": "Jungfernstieg",
    "house_number": "10",
    "postal_code": "20095",
    "city": "Hamburg",
    "country": "DE"
  }'

Response (201 Created):

json

{
  "success": true,
  "data": {
    "id": "019bef38-a1b2-c3d4-e5f6-789012345678",
    "name": "Niederlassung Hamburg",
    "street": "Jungfernstieg",
    "house_number": "10",
    "postal_code": "20095",
    "city": "Hamburg",
    "country": "DE"
  }
}

Adresse aktualisieren

PUT /v1/customer/branches/{id}

Die Felder sind identisch zur Erstellung (siehe oben).

Adresse löschen

DELETE /v1/customer/branches/{id}

Query-Parameter:

Parameter	Typ	Beschreibung
`scheduled_deletion_at`	datetime	Optionales Datum für geplante Löschung (YYYY-MM-DD HH:MM:SS)

Hinweis: Firmenanschrift und Hauptsitz-Adressen (is_headquarters=true) können nicht gelöscht werden.

Geplante Löschung abbrechen

POST /v1/customer/branches/{id}/cancel-deletion

Bricht eine zuvor geplante Löschung ab.

3. Rufnummern (Phone Numbers)

Alle Rufnummern auflisten

GET /v1/customer/phone-numbers

Query-Parameter:

Parameter	Typ	Beschreibung
`branch_id`	string	Filterung nach Niederlassung

Rufnummer anlegen

POST /v1/customer/phone-numbers

Feld	Typ	Pflicht	Beschreibung
`label`	string	Ja	Bezeichnung (z.B. "Zentrale", "Notfall")
`number`	string	Ja	Rufnummer
`type`	string	Ja	`phone`, `mobile` oder `fax`
`is_primary`	boolean	Nein	Als primäre Rufnummer setzen (Standard: `false`)
`notes`	string	Nein	Notizen
`department_id`	string	Nein	Zugehörige Abteilung
`branch_id`	string	Nein	Zugehörige Niederlassung

Hinweis: Wenn is_primary auf true gesetzt wird, werden alle anderen Rufnummern automatisch auf nicht-primär zurückgesetzt.

Rufnummer aktualisieren

PUT /v1/customer/phone-numbers/{id}

Die Felder sind identisch zur Erstellung.

Rufnummer löschen

DELETE /v1/customer/phone-numbers/{id}

Sortierung ändern

POST /v1/customer/phone-numbers/reorder

Feld	Typ	Pflicht	Beschreibung
`ids`	array	Ja	Geordnete Liste der Rufnummern-IDs

4. E-Mail-Adressen

Alle E-Mail-Adressen auflisten

GET /v1/customer/email-addresses

Query-Parameter:

Parameter	Typ	Beschreibung
`branch_id`	string	Filterung nach Niederlassung

E-Mail-Adresse anlegen

POST /v1/customer/email-addresses

Feld	Typ	Pflicht	Beschreibung
`label`	string	Ja	Bezeichnung (z.B. "Allgemein", "Buchhaltung")
`email`	string	Ja	E-Mail-Adresse
`is_primary`	boolean	Nein	Als primäre E-Mail setzen (Standard: `false`)
`notes`	string	Nein	Notizen
`department_id`	string	Nein	Zugehörige Abteilung
`branch_id`	string	Nein	Zugehörige Niederlassung

Hinweis: Wenn is_primary auf true gesetzt wird, werden alle anderen E-Mail-Adressen automatisch auf nicht-primär zurückgesetzt.

E-Mail-Adresse aktualisieren

PUT /v1/customer/email-addresses/{id}

Die Felder sind identisch zur Erstellung.

E-Mail-Adresse löschen

DELETE /v1/customer/email-addresses/{id}

5. Webseiten

Alle Webseiten auflisten

GET /v1/customer/websites

Webseite anlegen

POST /v1/customer/websites

Feld	Typ	Pflicht	Beschreibung
`label`	string	Ja	Bezeichnung (z.B. "Homepage", "Online-Shop")
`url`	string	Ja	URL der Webseite
`is_primary`	boolean	Nein	Als primäre Webseite setzen (Standard: `false`)
`notes`	string	Nein	Notizen
`branch_id`	string	Nein	Zugehörige Niederlassung

Hinweis: Wenn is_primary auf true gesetzt wird, werden alle anderen Webseiten automatisch auf nicht-primär zurückgesetzt.

Webseite aktualisieren

PUT /v1/customer/websites/{id}

Die Felder sind identisch zur Erstellung.

Webseite löschen

DELETE /v1/customer/websites/{id}

6. Ansprechpartner (Branch Contacts)

Ansprechpartner auflisten

GET /v1/customer/branch-contacts

Query-Parameter:

Parameter	Typ	Pflicht	Beschreibung
`branch_id`	string	Ja	Niederlassungs-ID (Pflichtparameter)

Beispiel:

bash

curl -X GET "https://platform.passolution.de/api/v1/customer/branch-contacts?branch_id=019bef38-a1b2-c3d4-e5f6-789012345678" \
  -H "Authorization: Bearer {TOKEN}" \
  -H "Accept: application/json"

Ansprechpartner anlegen

POST /v1/customer/branch-contacts

Feld	Typ	Pflicht	Beschreibung
`branch_id`	string	Ja	Zugehörige Niederlassung
`salutation`	string	Nein	Anrede
`title`	string	Nein	Titel (z.B. "Dr.", "Prof.")
`first_name`	string	Ja	Vorname
`last_name`	string	Ja	Nachname
`function`	string	Nein	Funktion/Position
`department`	string	Nein	Abteilung
`phone`	string	Nein	Telefonnummer
`mobile`	string	Nein	Mobilnummer
`fax`	string	Nein	Faxnummer
`email`	string	Nein	E-Mail-Adresse
`notes`	string	Nein	Notizen

Ansprechpartner aktualisieren

PUT /v1/customer/branch-contacts/{id}

Die Felder sind identisch zur Erstellung (ohne branch_id).

Ansprechpartner löschen

DELETE /v1/customer/branch-contacts/{id}

7. Organisationsstruktur (Org Nodes)

Hierarchische Struktur abrufen

GET /v1/customer/org-nodes

Gibt die gesamte Organisationsstruktur als hierarchischen Baum zurück.

Einzelnen Knoten abrufen

GET /v1/customer/org-nodes/{id}

Knoten erstellen

POST /v1/customer/org-nodes

Feld	Typ	Pflicht	Beschreibung
`name`	string	Ja	Name des Knotens
`code`	string	Nein	Kurzcode (z.B. "DE-MUC")
`relation_label`	string	Nein	Beziehungsbezeichnung
`description`	string	Nein	Beschreibung
`parent_id`	string	Nein	ID des übergeordneten Knotens
`after_id`	string	Nein	ID des vorhergehenden Geschwisterknotens (für Sortierung)
`color`	string	Nein	Farbcode (z.B. `#FF5733`)

Beispiel:

bash

curl -X POST https://platform.passolution.de/api/v1/customer/org-nodes \
  -H "Authorization: Bearer {TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Region Süd",
    "code": "REG-SUED",
    "description": "Alle Niederlassungen in Süddeutschland",
    "parent_id": "019bef38-0000-0000-0000-000000000001",
    "color": "#2196F3"
  }'

Response (201 Created):

json

{
  "success": true,
  "data": {
    "id": "019bef38-a1b2-c3d4-e5f6-000000000099",
    "name": "Region Süd",
    "code": "REG-SUED",
    "description": "Alle Niederlassungen in Süddeutschland",
    "parent_id": "019bef38-0000-0000-0000-000000000001",
    "color": "#2196F3"
  }
}

Knoten aktualisieren

PUT /v1/customer/org-nodes/{id}

Die Felder sind identisch zur Erstellung.

Knoten löschen

DELETE /v1/customer/org-nodes/{id}

Hinweis: Beim Löschen eines Knotens werden alle Unterknoten ebenfalls gelöscht.

Sortierung ändern

POST /v1/customer/org-nodes/reorder

Feld	Typ	Pflicht	Beschreibung
`ids`	array	Ja	Geordnete Liste der Knoten-IDs

Knoten verschieben

POST /v1/customer/org-nodes/{id}/move

Feld	Typ	Pflicht	Beschreibung
`parent_id`	string	Nein	Neue übergeordnete Knoten-ID (`null` für Wurzelebene)
`after_id`	string	Nein	ID des vorhergehenden Geschwisterknotens

8. Abteilungen (Departments)

Alle Abteilungen auflisten

GET /v1/customer/departments

Query-Parameter:

Parameter	Typ	Beschreibung
`is_active`	boolean	Filterung nach Status (`true`/`false`)

Abteilung anlegen

POST /v1/customer/departments

Feld	Typ	Pflicht	Beschreibung
`name`	string	Ja	Name der Abteilung
`description`	string	Nein	Beschreibung
`code`	string	Nein	Kurzcode
`is_active`	boolean	Nein	Aktiv-Status (Standard: `true`)

Abteilung aktualisieren

PUT /v1/customer/departments/{id}

Die Felder sind identisch zur Erstellung.

Abteilung löschen

DELETE /v1/customer/departments/{id}

Sortierung ändern

POST /v1/customer/departments/reorder

Feld	Typ	Pflicht	Beschreibung
`ids`	array	Ja	Geordnete Liste der Abteilungs-IDs

9. Benutzer (Employees)

Alle Benutzer auflisten

GET /v1/customer/employees

Query-Parameter:

Parameter	Typ	Beschreibung
`search`	string	Volltextsuche über Name, E-Mail, Personalnummer
`branch_id`	string	Filterung nach Niederlassung
`department_id`	string	Filterung nach Abteilung
`group_id`	string	Filterung nach Benutzergruppe
`is_active`	boolean	Filterung nach Status (`true`/`false`)
`per_page`	integer	Einträge pro Seite (Standard: 50, Maximum: 200, `0` = alle)

Beispiel:

bash

curl -X GET "https://platform.passolution.de/api/v1/customer/employees?search=Müller&is_active=true&per_page=25" \
  -H "Authorization: Bearer {TOKEN}" \
  -H "Accept: application/json"

Response (200 OK):

json

{
  "success": true,
  "data": [
    {
      "id": "019bef38-a1b2-c3d4-e5f6-789012345678",
      "salutation": "herr",
      "first_name": "Thomas",
      "last_name": "Müller",
      "email": "t.mueller@musterfirma.de",
      "phone": "+49 89 12345678",
      "position": "Reiseberater",
      "department": "Vertrieb",
      "personnel_number": "P-1001",
      "is_active": true,
      "branch_id": "019bef38-0000-0000-0000-000000000001",
      "group_ids": [
        "019bef38-0000-0000-0000-000000000010"
      ]
    }
  ],
  "meta": {
    "current_page": 1,
    "per_page": 25,
    "total": 1
  }
}

Einzelnen Benutzer abrufen

GET /v1/customer/employees/{id}

Benutzer anlegen

POST /v1/customer/employees

Feld	Typ	Pflicht	Beschreibung
`salutation`	string	Nein	`herr`, `frau` oder `divers`
`title`	string	Nein	Titel (z.B. "Dr.", "Prof.")
`first_name`	string	Ja	Vorname
`last_name`	string	Ja	Nachname
`email`	string	Nein	E-Mail-Adresse
`phone`	string	Nein	Telefonnummer
`mobile`	string	Nein	Mobilnummer
`position`	string	Nein	Position/Funktion
`department`	string	Nein	Abteilung (Freitext)
`department_id`	string	Nein	Zugehörige Abteilungs-ID
`personnel_number`	string	Nein	Personalnummer
`branch_id`	string	Nein	Zugehörige Niederlassung
`is_active`	boolean	Nein	Aktiv-Status (Standard: `true`)
`notes`	string	Nein	Notizen
`active_from`	date	Nein	Aktiv ab (YYYY-MM-DD)
`active_until`	date	Nein	Aktiv bis (YYYY-MM-DD)
`group_ids`	array	Nein	Liste von Benutzergruppen-IDs

Benutzer aktualisieren

PUT /v1/customer/employees/{id}

Die Felder sind identisch zur Erstellung.

Benutzer löschen

DELETE /v1/customer/employees/{id}

10. Benutzergruppen (Employee Groups)

Alle Benutzergruppen auflisten

GET /v1/customer/employee-groups

Benutzergruppe anlegen

POST /v1/customer/employee-groups

Feld	Typ	Pflicht	Beschreibung
`name`	string	Ja	Name der Gruppe
`description`	string	Nein	Beschreibung

Benutzergruppe aktualisieren

PUT /v1/customer/employee-groups/{id}

Die Felder sind identisch zur Erstellung.

Hinweis: Systemgruppen (is_system=true) können nicht bearbeitet werden.

Benutzergruppe löschen

DELETE /v1/customer/employee-groups/{id}

Hinweis: Systemgruppen (is_system=true) können nicht gelöscht werden.

Fehlerbehandlung

HTTP-Code	Bedeutung
`200`	Anfrage erfolgreich
`201`	Ressource erfolgreich erstellt
`401`	Nicht authentifiziert (Token fehlt oder ungültig)
`403`	Keine Berechtigung für diese Aktion
`404`	Ressource nicht gefunden
`422`	Validierungsfehler (ungültige Daten)
`429`	Zu viele Anfragen (Rate Limit überschritten)

Beispiel Authentifizierungsfehler (401):

json

{
  "message": "Unauthenticated."
}

Beispiel Validierungsfehler (422):

json

{
  "success": false,
  "errors": {
    "name": ["The name field is required."],
    "street": ["The street field is required."],
    "city": ["The city field is required."]
  }
}

Beispiel Nicht gefunden (404):

json

{
  "success": false,
  "message": "Resource not found."
}

Beispiel Keine Berechtigung (403):

json

{
  "success": false,
  "message": "Systemgruppen können nicht gelöscht werden."
}

Beispiel Rate Limit (429):

json

{
  "message": "Too Many Attempts."
}

Hinweise

Firmenanschrift und Rechnungsadresse können über die API aktualisiert, aber nicht gelöscht werden
Hauptsitz-Adressen (is_headquarters=true) können nicht gelöscht werden
Systemgruppen (is_system=true) können nicht bearbeitet oder gelöscht werden
Primär-Markierung: Bei Rufnummern, E-Mail-Adressen und Webseiten gilt: Wenn is_primary auf true gesetzt wird, werden alle anderen Einträge desselben Typs automatisch auf nicht-primär zurückgesetzt
Geplante Löschung: Adressen können mit scheduled_deletion_at zur Löschung vorgemerkt werden. Die geplante Löschung kann jederzeit über den cancel-deletion-Endpunkt abgebrochen werden
Pagination: Bei Benutzern kann mit per_page=0 die Pagination deaktiviert werden, um alle Einträge auf einmal abzurufen (maximal 200 pro Seite, 0 = alle)

Support

Bei Fragen zur API wenden Sie sich an Ihren Ansprechpartner bei Passolution.