Der Support-Assistent ist auch ohne Web-Oberfläche per REST erreichbar – z. B. aus Ticketsystemen, Skripten oder anderen Anwendungen. Basis-URL ist dein Jarvis-Host (https://DEIN-JARVIS-HOST). Alle Bodies sind JSON (Content-Type: application/json).

Authentifizierung

• Angemeldeter Benutzer (Browser/Sitzung): Header Authorization: Bearer <token>
• Externe Anwendung: Header X-API-Key: <API-Key> – API-Keys werden in den Einstellungen verwaltet. /query, /summarize sowie die CRM-Lookups (/api/jira/phonenumber, /api/jira/crm-number) akzeptieren API-Keys; die übrigen Endpunkte erfordern ein Benutzer-Token.

Endpunkte

Beispiel 1 – Suche mit KI-Zusammenfassung

Durchsucht Wissensdatenbank und (nur offene) Jira-Tickets, holt bis zu 10 Tickets und lässt eine KI-Gesamtzusammenfassung erstellen.

curl -sk https://DEIN-JARVIS-HOST/api/support/query \
  -H "X-API-Key: DEIN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "text": "Drucker im 2. OG offline",
        "rag": true,
        "confluence": false,
        "ai": true,
        "jira_all": false,
        "jira_open": true,
        "jira_limit": 10,
        "summary_lines": 5,
        "prompt": "Antworte in Stichpunkten mit konkreten Lösungsschritten.",
        "lang": "de"
      }'

Antwort (gekürzt):

{
  "ok": true,
  "query": "Drucker im 2. OG offline",
  "ai_summary": "Mögliche Ursache ist ein Netzwerk-Timeout des Druckers …",
  "jira_total": 7,
  "blocks": [
    { "source": "JIRA",   "key": "SUP-1234", "title": "SUP-1234",
      "score": 92, "summary": "Drucker reagiert nicht …" },
    { "source": "WISSEN", "title": "Drucker-Reset Anleitung",
      "score": 80, "summary": "Schritt 1: …" }
  ]
}

Request-Felder /api/support/query

Alle Felder außer text sind optional. Die Maxima (*_max) stammen aus der Skill-Konfiguration und lassen sich über GET /api/support/status abfragen.

Antwort-Felder /api/support/query

Jedes Element in blocks[] hat: source (WISSEN | JIRA | CONFLUENCE), title, summary (Kurzfassung), score (Relevanz in %), source_label und link (URL bzw. interner Abruf-Link). Quellenspezifisch zusätzlich: key, created (Erstellungsdatum) und updated (letzte Änderung) – jeweils nur JIRA, ISO-8601, doc + doc_name (nur WISSEN – Quelldokument), full_text (nur CONFLUENCE – gekappter Volltext).

Beispiel 2 – Einzelnes Ticket zusammenfassen

Lädt ein konkretes Jira-Ticket (Beschreibung + Kommentare) und fasst es in wenigen Sätzen zusammen.

curl -sk https://DEIN-JARVIS-HOST/api/support/summarize \
  -H "X-API-Key: DEIN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "source": "JIRA", "key": "SUP-1234", "lang": "de" }'

Antwort:

{
  "ok": true,
  "key": "SUP-1234",
  "summary": "Das Ticket beschreibt einen Druckerausfall im 2. OG …"
}

Request-Felder /api/support/summarize

Modus A – Einzel-Ticket (key gesetzt, kein Ticket-Key im Freitext):

Antwort: { "ok": true, "key": "…", "summary": "…", "jira_base": "…" }.

Modus B – Freitext mit Ticket-Key: Enthält text/query einen Vorgangs-/CRM-Key (z. B. { "text": "Status zu CRM-10550?" }), wird die Anfrage exakt wie /api/support/query beantwortet – volle Pipeline inkl. KI-Gesamtzusammenfassung, gleiche Antwortstruktur. In diesem Modus gelten alle oben genannten /query-Felder (inkl. prompt, jira_limit, …).

Fehler & Status-Codes

• 200 / 201 – Erfolg. Fehler liefern stets { "ok": false, "error": "…" }.
• 400 – ungültige Eingabe (z. B. leerer text, unbekannte source).
• 401 – nicht authentifiziert (Token/API-Key fehlt oder ungültig).
• 403 – Support-Skill inaktiv oder Konto gesperrt (Antwort dann mit "account_blocked": true).
• 499 – Client hat die Verbindung abgebrochen (z. B. „Abbrechen"); die Anfrage wird serverseitig gestoppt.
• 502 – KI-Zusammenfassung fehlgeschlagen (nur /summarize, Einzel-Ticket).

Hinweis: -k (curl) akzeptiert das selbstsignierte Zertifikat – nur für Tests.

🔎 CRM-Lookups (Jira)

Direkte Nachschlage-Endpunkte für die Anbindung von Telefonanlage/CTI oder Ticketsystem: aus einer Telefonnummer die zugehörige CRM-Kundennummer bestimmen bzw. zu einer CRM-Kundennummer alle Tickets abrufen. Beide sind GET-Aufrufe und akzeptieren Benutzer-Token oder externen API-Key. Setzt einen aktiven, konfigurierten Jira-Skill voraus.

Beispiel 3 – CRM-Kundennummer zu einer Telefonnummer

Sucht die Telefonnummer im Jira-CRM-Objektschema (Insight/Assets, Objektschema CRM, Standard-Schema-ID 21) – konkret in den Telefon-Attributen der CRM-Objekte (Zentrale Rufnummer, Telefonnummer, Mobil Nummer, …). Der Objekt-Key ist die CRM-Kundennummer (CRM-xxxxxx), es werden also ausschließlich CRM-Einträge zurückgegeben.

curl -sk "https://DEIN-JARVIS-HOST/api/jira/phonenumber?phone=%2B4920562611" \
  -H "X-API-Key: DEIN_API_KEY"

Die Nummer +4920562611 wird zu reinen Ziffern-Varianten normalisiert (+ = %2B in der URL): 4920562611 (voll international), 020562611 (national mit 0), 20562611 (ohne Vorwahl). Diese werden – von der längsten (eindeutigsten) zur kürzesten – per IQL like gegen die Telefon-Attribute geprüft; die erste Variante mit Treffern gewinnt. Telefonnummern liegen im CRM-Schema international/zusammenhängend (z. B. +4920562611).

Die Treffer werden nach Objekttyp sortiert: Organisationen zuerst, dann Organisationen-Produktgruppen, dann Personen. Der erste Treffer (Feld crm) ist damit die Organisation selbst. Antwort (Namen hier anonymisiert):

{
  "ok": true,
  "phone": "+4920562611",
  "crm": "CRM-66648",
  "found": true,
  "matches": [
    { "key": "CRM-66648",  "name": "Muster Klinikum GmbH",   "type": "Organisationen" },
    { "key": "CRM-421832", "name": "Muster Produktgruppe",    "type": "Organisationen Produktgruppen" },
    { "key": "CRM-158352", "name": "Muster Ansprechpartner",  "type": "Personen" }
  ],
  "total": 8,
  "variant": "4920562611"
}

Antwort-Felder: crm (erste gefundene CRM-Kundennummer bzw. null, nach Priorisierung die Organisation), found (bool), matches[] (alle Treffer als key + name + type = Objekttyp), total (Anzahl passender CRM-Objekte), variant (die Nummern-Variante, die getroffen hat), iql (ausgeführte IQL-Abfrage). Hinweis: Teilen sich mehrere Kunden dieselbe Rufnummer (z. B. zentrale Nummer), werden alle zugehörigen CRM-Objekte gelistet. Schema-ID, geprüfte Telefon-Attribute und die Typ-Reihenfolge sind über die Jira-Skill-Konfiguration (insight_schema_id / insight_phone_attrs / insight_type_priority) anpassbar.

Beispiel 4 – Alle Tickets zu einer CRM-Kundennummer

Sucht exakt im Insight-Organisationsfeld und liefert damit alle dem Kunden zugeordneten Tickets (nicht nur Volltext-Treffer), neueste zuerst.

curl -sk "https://DEIN-JARVIS-HOST/api/jira/crm-number?crm=CRM-10550&limit=25" \
  -H "X-API-Key: DEIN_API_KEY"

Antwort (gekürzt):

{
  "ok": true,
  "crm": "CRM-10550",
  "total": 7,
  "jql": "Organisation = \"CRM-10550\" ORDER BY updated DESC",
  "results": [
    { "key": "NXCIS-42", "summary": "Störung Drucker", "status": "Offen",
      "type": "Bug", "priority": "Hoch", "assignee": "…", "link": "https://…/browse/NXCIS-42" }
  ]
}

Antwort-Felder: crm (normalisierte Nummer), total (Jira-Gesamttreffer), results[] (Tickets mit key, summary, status, type, priority, assignee, created, updated, link), jql. Das Organisationsfeld ist über die Jira-Skill-Konfiguration (org_field) anpassbar.

Beispiel 5 – Passende Tickets eines CRM-Kunden zu Schlagworten

Kombiniert die exakte CRM-Kundensuche mit 2 bis 5 Schlagworten (Volltext, OR-verknüpft) und liefert offene und abgeschlossene Tickets des Kunden, neueste zuerst.

curl -sk "https://DEIN-JARVIS-HOST/api/jira/passende-tickets?crm=CRM-10550&keywords=drucker,fehler,vpn&limit=25" \
  -H "X-API-Key: DEIN_API_KEY"

Antwort (gekürzt):

{
  "ok": true,
  "crm": "CRM-10550",
  "keywords": ["drucker", "fehler", "vpn"], "match": "all",
  "total": 5, "returned": 5, "open": 2, "closed": 3,
  "jql": "Organisation = \"CRM-10550\" AND (text ~ \"drucker\" AND text ~ \"fehler\" AND text ~ \"vpn\") ORDER BY updated DESC",
  "results": [
    { "key": "NXCIS-42", "summary": "Störung Drucker", "status": "Erledigt",
      "type": "Bug", "priority": "Hoch", "resolved": true, "link": "https://…/browse/NXCIS-42" }
  ]
}

Antwort-Felder: crm, keywords[], total (Jira-Gesamttreffer), returned (Anzahl gelieferter Tickets), open/closed (offen/abgeschlossen, bezogen auf die gelieferte Seite), results[] (Tickets zusätzlich mit resolved = abgeschlossen ja/nein), jql. Es wird KEIN Status-/Resolution-Filter gesetzt → offene wie abgeschlossene Vorgänge kommen zurück.