Ticket-Endpunkt

Beispiel: Ticket erstellen

POST /Import/JSON/tickets
Authorization: Bearer {token}
Content-Type: application/json

{
  "type": "tickets",
  "data": [{
    "ticket_subject": "API-Test-Ticket",
    "ticket_customers_email": "kunde@example.com",
    "ticket_customers_name": "Max Mustermann",
    "ticket_priority_id": 2,
    "ticket_department_id": 1,
    "ticket_comments": "Erstellt via xoPort API",
    "admin_id": 0,
    "attachments": [
      { "name": "bestellung.pdf", "content_base64": "JVBERi0xLjQKJcfs…" }
    ],
    "assigned_admins": [1, 3]
  }]
}

Kommentar-Format

"ticket_comments": "Interner Vermerk via API",
"admin_id": 1

ticket_comments ist der Kommentartext, admin_id sein Urheber (0 = System, >0 = Admin-ID, wird validiert).

Beispiel: Ticket updaten mit Kommentar

PUT /Import/JSON/tickets
Authorization: Bearer {token}
Content-Type: application/json

{
  "type": "tickets",
  "data": [{
    "ticket_id": 42,
    "ticket_status_id": 3,
    "ticket_priority_id": 1,
    "ticket_comments": "Status auf Erledigt gesetzt",
    "admin_id": 1,
    "assigned_admins": [1, 5]
  }]
}

Im Export enthält jedes Ticket ein linked_appointments[] Array mit verknüpften CRM-Terminen:

"linked_appointments": [
  {
    "appointment_id": 15,
    "startdate": "2026-04-14 10:00:00",
    "enddate": "2026-04-14 11:00:00",
    "allday": 0,
    "done": 0,
    "status_id": 1,
    "title": "Rückruf Kunde",
    "description": "Bezüglich offener Rückfrage",
    "location": ""
  }
]

Termine werden über xocrm_appointments_relationships (target_type = ticket_id) verknüpft. Die Löschung eines Tickets entfernt nur die Verknüpfung, nicht den Termin selbst.

Korrigiert in v2.118.1: linked_appointments an POST/PUT /Import/JSON/tickets meldete zusätzlich die Warnung UNKNOWN_FIELD, obwohl die Termine angelegt wurden. Die Warnung entfällt; die Verarbeitung ist unverändert.

Dateianhänge werden über die Ticket-ID addressiert:

Listing: GET /ticket_attachments/{id}

{
  "success": true,
  "ticket_id": 42,
  "ticket_link_id": "8i1c5O8g7w8b5c",
  "files": [
    {
      "name": "screenshot.png",
      "size": 245760,
      "mime_type": "image/png",
      "last_modified": "2026-03-15 14:30:22"
    }
  ]
}

Download: GET /ticket_attachment/{id}?file=screenshot.png

Binary-Download mit korrektem Content-Type und Content-Disposition: attachment Header. Path-Traversal-Schutz via basename() + realpath()-Validierung.

Upload: attachments[] an POST/PUT NEU v2.60.0

Bis v2.59.0 ließen sich Anhänge nur lesen — geschrieben wurden sie ausschließlich über das Backend-Formular. Ein per API angelegtes Ticket blieb damit ohne Beleg (PDF, .eml, Screenshot). Seit v2.60.0 nimmt POST/PUT /Import/JSON/tickets das optionale Feld attachments[] entgegen:

"ticket_comments": "Beleg zur Reklamation",
"admin_id": 1,
"attachments": [
  {
    "name": "rechnung.pdf",
    "content_base64": "JVBERi0xLjQKJcfs…"
  }
]

Die Ablage erfolgt über dieselbe Mechanik wie der Backend-Upload — gleiche Endungs-Allowlist, Namenskonvention <ticket>_<verlaufs-id>_<name> und Hash-Dedup gegen Doppelablage. Der tatsächlich vergebene Dateiname steht je Datensatz in der Antwort unter attachments. Die Obergrenze je Datei entspricht dem /media-Endpunkt (XOPORT_MEDIA_MAX_FILESIZE, Standard 10 MB).

Fehlerhafte Einträge (unerlaubte Endung, ungültiges Base64, Überschreitung der Größe) erzeugen einen Fehler je Datei; das Ticket-Update selbst bleibt erfolgreich. Bei is_public_reply: true zusammen mit notify_customer: true gehen die Dateien mit der Kundenmail hinaus — sie werden vor dem Versand geschrieben.

Ein Claim zeigt an, dass gerade jemand an einem Ticket arbeitet, zum Beispiel ein KI-Agent im Auftrag eines Mitarbeiters. Weitere Bearbeiter sehen ihn im Export und im Backend (Ticketliste und Ticketansicht) und beginnen nicht parallel. Der Claim ist ein Hinweis, keine Sperre: Kein Schreibzugriff prüft ihn, das Ticket bleibt für alle bearbeitbar.

PUT /Import/JSON/ticket_claims
{
  "type": "ticket_claims",
  "data": [
    { "ticket_id": 33999, "admin_id": 12, "state": "claimed", "ttl_minutes": 60, "label": "KI-Agent" }
  ]
}

Ergebnis je Datensatz

records[].status nennt das Ergebnis, records[].claim den Stand nach dem Aufruf:

Antwort (HTTP 200), wenn ein anderer Administrator anfragt, während Max Mustermann den Claim hält:

{
  "success": false,
  "outcome": "failed",
  "api_version": "2.118.1",
  "type": "ticket_claims",
  "stats": { "total": 1, "claimed": 0, "refreshed": 0, "taken_over": 0, "released": 0, "unchanged": 0, "failed": 1 },
  "errors": [
    { "record": 1, "error": "Ticket 33999 is claimed by Max Mustermann (admin_id 12) until 2026-09-17 14:05:10. Send force=true to take it over." }
  ],
  "timestamp": "2026-09-17 13:20:02",
  "records": [
    {
      "index": 1,
      "ticket_id": 33999,
      "status": "conflict",
      "claim": {
        "admin_id": 12,
        "admin_name": "Max Mustermann",
        "label": "KI-Agent",
        "claimed_at": "2026-09-17 13:05:10",
        "expires_at": "2026-09-17 14:05:10",
        "expires_in_seconds": 2708
      }
    }
  ]
}

Automatische Freigabe

• Öffentliche Antwort an den Kunden, per API (PUT /Import/JSON/tickets) oder im Backend. Wer antwortet, spielt keine Rolle.
• Wechsel auf einen Schließ-Status. Wer ein bereits geschlossenes Ticket erneut speichert, gibt keinen Claim frei.
• Ablauf der Laufzeit.

Eine interne Notiz gibt den Claim nicht frei. Setzen und Freigeben ändern weder ticket_date_last_modified noch den Verlauf und lösen keine Ereignisse aus; Sortierung und Delta-Export (?last_modified=) bleiben unberührt. Je Ticket gibt es höchstens einen Claim: Von zwei gleichzeitigen Anfragen erhält genau eine conflict.

Ab Shop 4.9.73. Fehlt die Tabelle ticket_claims noch, antwortet der Endpunkt mit HTTP 503 TICKET_CLAIMS_UNAVAILABLE; der Shop legt sie beim nächsten Schema-Abgleich an (beim Öffnen einer xoCRM-Seite oder des HealthChecks).