Support-API, Ereignisse und Massenexport
Alles, was eine Integration vom Supportmodul braucht: die Endpunkte für Fälle, Nachrichtenverläufe, SLA, Warteschlangen, Katalog, Ansprüche und Umfragen; signierte Ereignisabonnements mit Wiederholung und Replay; ein Feed, den Sie per Cursor fortsetzen; Massenexport von Fällen und Nachrichten; und der idempotente Import historischer Fälle aus einem anderen Helpdesk. Zu jedem Endpunkt gibt es ein passendes Werkzeug auf dem MCP-Server.
Der Support war schon immer über die allgemeine Datensatz-API erreichbar: Ein Fall ist ein Datensatz, das Auflisten und Anlegen funktionierte also bereits. Was nicht funktionierte, ist alles, was neben dem Fall liegt und kein Datensatz ist. Der Nachrichtenverlauf, die SLA-Uhr, die Warteschlangen, der Servicekatalog, das Anspruchsguthaben und die Umfragen hatten überhaupt keinen Endpunkt, eine Integration konnte also einen Fall eröffnen und nicht darauf antworten.
Dieser Artikel behandelt die Support-Endpunkte, dieselben Werkzeuge auf dem MCP-Server, die Ereignisabonnements mit Wiederholung und Replay, den fortsetzbaren Ereignis-Feed und wie Sie die Fallhistorie aus einem anderen Helpdesk übernehmen.
Wo Sie anfangen - Legen Sie unter Einstellungen, API und Entwickler einen API-Schlüssel an. Der Schlüssel löst Ihr Konto auf und begrenzt alles darauf. - Jeder Aufruf authentifiziert sich wie im Rest der API: Authorization: Bearer gefolgt von Ihrem Schlüssel. - Alles in diesem Artikel liegt unter /api/v1/service und ist auf das Objekt ticket begrenzt. Ein Schlüssel, der auf andere Objekte beschränkt ist, kommt nicht heran. - Zu jedem Endpunkt gibt es ein passendes Werkzeug auf dem MCP-Server, ein mit SellioCRM verbundener KI-Agent kann also genau dasselbe tun.
Fälle - GET /api/v1/service/tickets listet Fälle als flache Zeilen, gefiltert nach Status, Priorität, Warteschlange, Zuständigkeit oder Freitext. Nutzen Sie updated_since mit einem Zeitstempel, um nur das zu holen, was sich seit Ihrer letzten Synchronisierung geändert hat, und limit und offset zum Blättern. - GET /api/v1/service/tickets/{id} gibt einen Fall samt SLA-Uhr zurück: die Fälligkeit, ob sie pausiert ist, das Ziel für die erste Antwort und das Ziel für die nächste Antwort. Diese Uhr ist der Grund, warum es diesen Endpunkt gibt; der allgemeine Datensatz-Endpunkt liefert die Felder, nicht die Fristen. - POST /api/v1/service/tickets eröffnet einen Fall über denselben Weg wie die Konsole, sodass Vorgangsnummer, SLA-Ziele, Routingregeln und ausgehende Webhooks alle greifen. - PATCH /api/v1/service/tickets/{id} ändert Status, Priorität, Kategorie, Warteschlange und die zuständige Person. Zuweisen ist dasselbe Verb wie Status ändern, es gibt dafür also keinen eigenen Endpunkt. - GET und POST /api/v1/service/tickets/{id}/messages lesen und schreiben den Verlauf. kind public antwortet der Kundenseite und sendet die E-Mail; kind internal hinterlässt eine Notiz, die nur das Team sieht. - POST /api/v1/service/tickets/merge führt zwei Fälle zusammen: Der sekundäre geht im primären auf und seine Nachrichten wandern mit.
Rund um den Fall - GET /api/v1/service/queues listet die Warteschlangen mit Kapazität je Person, Geschäftszeiten und Standardpriorität. Lesen Sie das vor dem Routing: Der Name der Warteschlange ist das, was der Aufruf zum Anlegen erwartet. - GET und POST /api/v1/service/catalog lesen die Auslage des Servicekatalogs und fordern einen Eintrag an. Eine Anfrage eröffnet einen echten Fall mit Warteschlange und Priorität des Eintrags; senden Sie einen eigenen idempotencyKey, damit eine Wiederholung die vorhandene Anfrage zurückgibt, statt einen zweiten Fall zu eröffnen. - GET /api/v1/service/entitlements gibt Supportansprüche je Konto oder Vertrag zurück, mit dem verbleibenden Guthaben. - GET /api/v1/service/surveys gibt Einladungen zu Zufriedenheitsumfragen mit Status und Antwortdatum zurück. Anonyme Umfragen geben nie zurück, wer geantwortet hat.
Ereignisse, in Echtzeit und per Cursor Eine Integration braucht beide Hälften von Echtzeit: sofort zu erfahren, wenn etwas passiert, und nachzuholen, was sie verpasst hat, während sie ausgefallen war. Die erste bekommen Sie über ein Abonnement, die zweite über den Feed.
- POST /api/v1/service/subscriptions registriert eine URL und die Ereignisse, die Sie interessieren. events nimmt genaue Typen oder einen Familienplatzhalter wie ticket.* Ein unbekanntes Ereignis wird beim Namen abgelehnt, denn ein Abonnement, das nie auslöst, ist schlimmer als ein Fehler. Das Geheimnis kommt einmal zurück; kopieren Sie es.
- Jede Zustellung kommt als POST mit drei Kopfzeilen: x-sellio-event mit dem Ereignisnamen, x-sellio-delivery mit der ID dieses Versuchs und x-sellio-signature in der Form sha256 gefolgt von dem Code, der über den exakten Rumpf mit Ihrem Geheimnis berechnet wurde. Berechnen Sie ihn auf Ihrer Seite neu und vergleichen Sie; stimmt er nicht, verwerfen Sie den Aufruf.
- Eine fehlgeschlagene Zustellung wird mit wachsenden Wartezeiten wiederholt, etwa nach einer Minute, fünf, dreißig, zwei Stunden und sechs Stunden. Danach gilt sie als tot und bleibt im Protokoll.
- GET /api/v1/service/deliveries ist die nachschlagbare Antwort auf die Frage, ob dieses Ereignis angekommen ist. Jede Zeile trägt die Versuche, den letzten Statuscode, den Fehler und die nächste geplante Wiederholung.
- POST /api/v1/service/deliveries/{id}/replay sendet eine Zustellung erneut. Es spielt den gespeicherten Rumpf ab, Byte für Byte denselben, der beim ersten Mal hinausging. Die Nutzlast jetzt neu zu bauen würde den heutigen Zustand mit dem Zeitstempel von gestern senden.
- GET /api/v1/service/events ist der Feed. Übergeben Sie den Cursor aus der vorherigen Antwort und Sie bekommen nur, was danach passiert ist. nextCursor kommt auch bei einer leeren Seite zurück, und genau den speichern Sie. Behandeln Sie den Cursor als undurchsichtig: Mit ihm zu rechnen ist der Weg, auf dem eine Integration später still kaputtgeht.
- GET /api/v1/service/event-types listet jedes Ereignis auf, das das Produkt senden kann, welche der drei Webhook-Register es abonnieren können und ob der Weg zu einem Serviceabonnement voraussetzt, dass der Ereignisbus für Ihr Konto eingeschaltet ist. Lesen Sie das, bevor Sie ein Abonnement anlegen.
Fälle und Nachrichten exportieren GET /api/v1/service/export nimmt entity tickets oder messages und format json oder csv. Der Nachrichtenexport ist der Grund, warum es diesen Endpunkt gibt: Der Verlauf ist kein Datensatz, keine andere Oberfläche hat ihn also im Bündel geliefert. Filtern Sie nach since, status, queue, ticketId oder kind und blättern Sie mit limit, bis 500, und offset. Die json-Antwort trägt hasMore, damit Sie wissen, dass noch eine Seite wartet.
Historie aus einem anderen Helpdesk übernehmen POST /api/v1/service/import nimmt bis zu 500 Zeilen pro Aufruf. Jede Zeile braucht externalKey, also die Fallnummer im Werkzeug, das Sie verlassen, und einen Betreff. Sie kann außerdem body, requester email, name und phone, priority, category, queue, channel, status und createdAt tragen.
- Der Import ist über externalKey idempotent. Dieselbe Datei zweimal zu importieren meldet die Zeilen als vorhanden, statt sie zu verdoppeln, Sie können einen fehlgeschlagenen Stapel also ohne Sorge erneut laufen lassen.
- Der Fall entsteht mit Datum und Status aus der Quelle. Ohne das würden fünfzehntausend geschlossene Fälle als neu mit dem heutigen Datum landen, die Warteschlange der Menschen fluten, die gerade arbeiten, und in jedem Bericht nach Zeitraum lügen.
- Senden Sie dryRun true, um zu sehen, was passieren würde, ohne etwas zu schreiben.
- Eine Zeile, die die Prüfung nicht besteht, wird zu einem Eintrag in problems mit ihrer Position im Stapel, und der Rest des Stapels geht durch. Ein falsches Datum in drei Zeilen zwingt Sie nicht, von vorn anzufangen.