API - Interaktionen Admin

📕 Für Administratoren und Entwickler

Interaktionen dokumentieren Kontaktpunkte mit Kunden — etwa Telefonate, E-Mails oder Meetings. Über die spiritflow Public API können Interaktionen programmatisch erfasst und abgerufen werden. Die Endpunkte sind unter dem jeweiligen Kunden verschachtelt: /api/v1/customers/{customerId}/interactions. Alle Endpunkte erfordern einen gültigen API-Key mit dem entsprechenden Scope.

Referenzwerte: Interaktionstypen

Wert	Beschreibung
`PHONE_CALL`	Telefonat
`EMAIL_IN`	Eingehende E-Mail
`EMAIL_OUT`	Ausgehende E-Mail
`MEETING`	Besprechung
`VISIT`	Vor-Ort-Besuch
`NOTE`	Notiz / Vermerk

Interaktionen auflisten

GET /api/v1/customers/{customerId}/interactions

Erforderlicher Scope: interactions:read

Pfad-Parameter:

Parameter	Typ	Beschreibung
`customerId`	Long	ID des Kunden

Query-Parameter:

Parameter	Typ	Standard	Beschreibung
`page`	number	`0`	Seitennummer (0-basiert)
`size`	number	`20`	Einträge pro Seite (max. 100)

Antwort-Felder:

Feld	Typ	Beschreibung
`id`	number	Eindeutige ID der Interaktion
`customerId`	number	ID des zugehoerigen Kunden
`interactionType`	string	Art der Interaktion (siehe Referenzwerte)
`subject`	string	Betreff der Interaktion
`content`	string?	Inhalt / Notizen
`interactionDate`	string	Zeitpunkt der Interaktion (ISO 8601, UTC)
`durationMinutes`	number?	Dauer in Minuten
`outcome`	string?	Ergebnis der Interaktion
`contactPersonId`	number?	ID der Kontaktperson beim Kunden
`contactPersonName`	string?	Name der Kontaktperson
`followUpDate`	string?	Wiedervorlage-Zeitpunkt (ISO 8601, UTC)
`createdBy`	string	Anzeigename des Erstellers
`createdAt`	string	Erstellungszeitpunkt (ISO 8601, UTC)

Antwort (200 OK):

{
  "data": [
    {
      "id": 1,
      "customerId": 42,
      "interactionType": "PHONE_CALL",
      "subject": "Rueckruf wegen Angebot",
      "content": "Kunde hat Interesse an Enterprise-Paket bestaetigt.",
      "interactionDate": "2025-03-01T14:30:00Z",
      "durationMinutes": 15,
      "outcome": "Angebot wird per E-Mail nachgesendet",
      "contactPersonId": 5,
      "contactPersonName": "Anna Müller",
      "followUpDate": "2025-03-08T09:00:00Z",
      "createdBy": "Florian Cremer",
      "createdAt": "2025-03-01T14:45:00Z"
    }
  ],
  "pagination": {
    "page": 0,
    "size": 20,
    "totalElements": 1,
    "totalPages": 1
  },
  "meta": {
    "requestId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "timestamp": "2025-03-01T15:00:00Z"
  }
}

cURL-Beispiel:

curl -X GET "https://app.spiritflow.team/api/v1/customers/42/interactions?page=0&size=20" \
  -H "X-API-Key: sf_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Interaktion erstellen

POST /api/v1/customers/{customerId}/interactions

Erforderlicher Scope: interactions:write

Pfad-Parameter:

Parameter	Typ	Beschreibung
`customerId`	Long	ID des Kunden

Request-Body:

Feld	Typ	Pflicht	Beschreibung
`interactionType`	string	Ja	Art der Interaktion (siehe Referenzwerte oben)
`subject`	string	Ja	Betreff (max. 255 Zeichen)
`content`	string	Nein	Inhalt / Notizen (max. 5.000 Zeichen)
`interactionDate`	string	Nein	ISO 8601 Zeitstempel. Standard: aktuelle Zeit
`durationMinutes`	number	Nein	Dauer in Minuten
`outcome`	string	Nein	Ergebnis der Interaktion (max. 500 Zeichen)
`contactPersonId`	number	Nein	ID der Kontaktperson beim Kunden
`followUpDate`	string	Nein	ISO 8601 Zeitstempel für Wiedervorlage

Antwort (201 Created): Erstellte Interaktion im data-Feld (gleiche Struktur wie in der Liste).

Fehler-Codes:

HTTP-Status	Code	Beschreibung
400	`VALIDATION_ERROR`	Pflichtfeld fehlt, Wert ungültig oder Feldlimit überschritten
404	`NOT_FOUND`	Kunde oder Kontaktperson nicht gefunden

cURL-Beispiel:

curl -X POST "https://app.spiritflow.team/api/v1/customers/42/interactions" \
  -H "X-API-Key: sf_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "interactionType": "PHONE_CALL",
    "subject": "Rueckruf wegen Angebot",
    "content": "Kunde hat Interesse an Enterprise-Paket bestaetigt.",
    "interactionDate": "2025-03-01T14:30:00Z",
    "durationMinutes": 15,
    "outcome": "Angebot wird per E-Mail nachgesendet",
    "contactPersonId": 5,
    "followUpDate": "2025-03-08T09:00:00Z"
  }'

Nebeneffekte beim Erstellen einer Interaktion

Das Anlegen einer Interaktion aktualisiert automatisch zwei Felder des zugehoerigen Kunden:

lastContactDate wird auf den Zeitpunkt der Interaktion (interactionDate) gesetzt.
nextContactDate wird aktualisiert, wenn im Request ein followUpDate angegeben wurde.

Dadurch bleibt die Kontakthistorie im Kundenprofil stets aktuell, ohne dass ein separater API-Aufruf noetig ist.