So erstellen Sie Zendesk-Tickets mithilfe der API: Eine vollständige JSON-Anleitung

Wenn Sie Integrationen mit Zendesk erstellen, müssen Sie wahrscheinlich Tickets programmgesteuert erstellen. Egal, ob Sie ein benutzerdefiniertes Webformular verbinden, Daten von einem anderen System synchronisieren oder Support-Workflows automatisieren, die Zendesk Tickets API ist der Standardweg, um Daten in Zendesk zu bekommen.

Diese Anleitung führt Sie durch alles, was Sie über das Erstellen von Tickets über die API wissen müssen, von der Authentifizierung bis hin zu erweiterten JSON-Payloads.

Was Sie für den Anfang benötigen

Bevor Sie mit dem Erstellen von API-Aufrufen beginnen, stellen Sie sicher, dass Sie diese Grundlagen abgedeckt haben:

• Ein Zendesk Support-Konto mit Administrator- oder Agentenzugriff. Wenn Sie noch keines haben, können Sie ein kostenloses Testkonto für die Entwicklung erhalten.
• API-Token-Zugriff aktiviert im Admin Center unter Apps und Integrationen > APIs > API-Token
• Grundlegende Vertrautheit mit HTTP-Anfragen und JSON-Datenstrukturen
• Ein Tool zum Erstellen von API-Aufrufen: cURL, Python mit der Requests-Bibliothek oder eine JavaScript-Umgebung

Wenn Sie neu in der Arbeit mit REST-APIs sind, bietet die Zendesk-Dokumentation eine hilfreiche Schnellstartanleitung, die die JavaScript-Konsole Ihres Browsers verwendet, um Anfragen ohne Einrichtung zu testen.

Die Zendesk Tickets API Endpunkt verstehen

Der Zendesk API Create Ticket JSON-Endpunkt folgt einem konsistenten Muster über alle Zendesk-Instanzen hinweg:

POST https://{subdomain}.zendesk.com/api/v2/tickets.json

Hier ist, was Sie über den Endpunkt wissen müssen:

• HTTP-Methode: POST zum Erstellen neuer Tickets
• Content-Type Header: Muss auf application/json gesetzt sein
• Authentifizierung: Einfache Authentifizierung mit Ihrer E-Mail-Adresse und Ihrem API-Token
• Ratenbegrenzungen (Rate limits): 700 Anfragen pro Minute für die meisten Endpunkte

Die API gibt bei Erfolg einen 201 Created-Status zurück, zusammen mit dem vollständigen Ticket-Objekt einschließlich der neu zugewiesenen Ticket-ID. Wenn etwas schief geht, erhalten Sie einen 4xx- oder 5xx-Status mit einer Fehlermeldung, die das Problem erklärt.

API-Authentifizierung einrichten

Die Authentifizierung ist der Punkt, an dem die meisten Entwickler auf ihr erstes Problem stoßen. Zendesk verwendet eine einfache Authentifizierung mit einer Besonderheit: Anstelle Ihres Passworts verwenden Sie ein API-Token.

Ein API-Token generieren

1. Melden Sie sich als Administrator bei Zendesk an
2. Gehen Sie zu Admin Center > Apps und Integrationen > APIs > API-Token
3. Klicken Sie auf das Plus-Symbol, um ein Token hinzuzufügen
4. Geben Sie ihm einen beschreibenden Namen (wie "Ticket-Erstellungs-Skript")
5. Kopieren Sie das Token sofort (Sie werden es nicht wieder sehen)

Authentifizierungsformat

Die Anmeldeinformationen folgen diesem Format:

Benutzername: {your_email}/token
Passwort: {your_api_token}

Wenn Ihre E-Mail-Adresse beispielsweise admin@company.com und Ihr Token abc123xyz lautet, verwenden Sie Folgendes:

Benutzername: admin@company.com/token
Passwort: abc123xyz

Sicherheits-Best Practices

Hartcodieren Sie niemals Ihre API-Anmeldeinformationen in Ihren Skripten. Verwenden Sie stattdessen Umgebungsvariablen:

import os

ZENDESK_SUBDOMAIN = os.getenv('ZENDESK_SUBDOMAIN')
ZENDESK_API_TOKEN = os.getenv('ZENDESK_API_TOKEN')
ZENDESK_USER_EMAIL = os.getenv('ZENDESK_USER_EMAIL')

Dies hält Ihre Anmeldeinformationen aus der Versionskontrolle heraus und macht Ihren Code über verschiedene Umgebungen hinweg portabler.

Grundlegende JSON-Struktur für die Ticket-Erstellung

Mindestens benötigt ein Zendesk-Ticket zwei Dinge: einen Betreff und einen Kommentar. Hier ist die einfachste gültige JSON-Payload:

{
  "ticket": {
    "subject": "Mein Drucker brennt!",
    "comment": {
      "body": "Der Rauch ist sehr farbenfroh."
    }
  }
}

Das ticket-Objekt umschließt alles. Darin legen Sie Folgendes fest:

• subject: Der Ticket-Titel (erforderlich)
• comment: Ein Objekt, das mindestens einen body enthält (erforderlich)

Standardmäßig sind Kommentare öffentlich. Wenn Sie stattdessen eine interne Notiz erstellen möchten, fügen Sie dem Kommentarobjekt "public": false hinzu.

Antwortformat

Wenn Ihre Anfrage erfolgreich ist, gibt die API das erstellte Ticket zurück:

{
  "ticket": {
    "id": 35436,
    "url": "https://company.zendesk.com/api/v2/tickets/35436.json",
    "subject": "Mein Drucker brennt!",
    "status": "open",
    "created_at": "2026-03-01T22:55:29Z",
    ...
  }
}

Das Feld id ist das, was Sie verwenden, um auf dieses Ticket in zukünftigen API-Aufrufen zu verweisen.

Code-Beispiele zum Erstellen von Tickets

Sehen wir uns funktionierende Beispiele in drei gängigen Sprachen an.

cURL-Beispiel

curl https://yourcompany.zendesk.com/api/v2/tickets.json \
  -d '{"ticket": {"subject": "Test ticket", "comment": {"body": "This is a test"}}}' \
  -H "Content-Type: application/json" \
  -v -u your@email.com/token:your_api_token \
  -X POST

Das Flag -v zeigt eine ausführliche Ausgabe, die beim Debuggen hilft. Entfernen Sie es in der Produktion.

Python-Beispiel

import requests
import os
import json

subdomain = os.getenv('ZENDESK_SUBDOMAIN')
email = os.getenv('ZENDESK_USER_EMAIL')
token = os.getenv('ZENDESK_API_TOKEN')

url = f'https://{subdomain}.zendesk.com/api/v2/tickets.json'
auth = (f'{email}/token', token)
headers = {'Content-Type': 'application/json'}

data = {
    'ticket': {
        'subject': 'Druckerproblem',
        'comment': {
            'body': 'Der Drucker reagiert nicht.',
            'public': True
        }
    }
}

response = requests.post(url, json=data, auth=auth, headers=headers)

if response.status_code == 201:
    ticket = response.json()['ticket']
    print(f"Erstelltes Ticket #{ticket['id']}")
else:
    print(f"Fehler: {response.status_code}")
    print(response.text)

Beachten Sie, dass requests.post() mit dem Parameter json= das Dictionary automatisch in JSON serialisiert und den Content-Type-Header setzt.

JavaScript-Beispiel

Wenn Sie in einem Browser arbeiten, in dem Zendesk bereits geladen ist, können Sie jQuery verwenden:

const ticket = {
  ticket: {
    subject: 'Hilfe beim Login',
    comment: {
      body: 'Ich kann nicht auf mein Konto zugreifen.'
    }
  }
};

$.ajax({
  url: '/api/v2/tickets.json',
  type: 'POST',
  contentType: 'application/json',
  data: JSON.stringify(ticket)
}).done(data => {
  console.log('Erstelltes Ticket:', data.ticket.id);
}).fail(err => {
  console.error('Fehler:', err);
});

Verwenden Sie für Node.js die native fetch API oder eine Bibliothek wie axios:

const response = await fetch('https://company.zendesk.com/api/v2/tickets.json', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Basic ' + Buffer.from(`${email}/token:${token}`).toString('base64')
  },
  body: JSON.stringify(ticket)
});

const data = await response.json();

Erweiterte Ticket-Eigenschaften

Sobald Sie die Grundlagen beherrschen, können Sie zusätzliche Eigenschaften festlegen, um vollständigere Tickets zu erstellen.

Benutzerdefinierte Felder (Custom fields)

Wenn Ihre Zendesk-Instanz über benutzerdefinierte Ticketfelder verfügt, legen Sie diese mithilfe ihrer Feld-IDs fest:

{
  "ticket": {
    "subject": "Bestellanfrage",
    "comment": {"body": "Frage zur letzten Bestellung"},
    "custom_fields": [
      {"id": 25356371, "value": "ORD-12345"},
      {"id": 25356634, "value": "2026-03-01"}
    ]
  }
}

Verwenden Sie für Dropdown-Felder den Tag-Wert (nicht den Anzeigetext). Übergeben Sie für Mehrfachauswahlfelder ein Array von Tag-Werten.

Den Anfragenden festlegen

Sie können ein Ticket im Namen einer anderen Person erstellen:

{
  "ticket": {
    "subject": "Support-Anfrage",
    "comment": {"body": "Hilfe bei der Abrechnung benötigt"},
    "requester": {
      "name": "John Smith",
      "email": "john@example.com",
      "locale_id": 8
    }
  }
}

Wenn die E-Mail-Adresse in Zendesk nicht vorhanden ist, wird automatisch ein neues Benutzerprofil erstellt.

Mitarbeiter und Follower

Fügen Sie Mitarbeiter (Benutzer, die Updates erhalten) oder Follower (Agenten, die das Ticket verfolgen) hinzu:

{
  "ticket": {
    "subject": "Team-Problem",
    "comment": {"body": "Dies betrifft mehrere Abteilungen"},
    "collaborators": ["user1@example.com", "user2@example.com"],
    "followers": [
      {"user_email": "agent@company.com", "action": "put"}
    ]
  }
}

Dateianhänge

Um Dateien anzuhängen, müssen Sie diese zuerst separat hochladen, um ein Upload-Token zu erhalten, und dieses Token dann in Ihre Ticket-Erstellung einfügen:

{
  "ticket": {
    "subject": "Screenshot angehängt",
    "comment": {
      "body": "Siehe angehängte Fehlermeldung",
      "uploads": ["vz7ll9ud8oofowy"]
    }
  }
}

Asynchrone Erstellung

Verwenden Sie für Tickets mit komplexen Geschäftsregeln, deren Verarbeitung einige Zeit dauern kann, die asynchrone Erstellung:

POST /api/v2/tickets.json?async=true

Dies gibt sofort einen 202 Accepted-Status mit einem Jobstatus zurück, den Sie abfragen können, um den Abschluss zu überprüfen.

Idempotenzschlüssel

Um doppelte Tickets zu vermeiden, wenn fehlgeschlagene Anfragen wiederholt werden, fügen Sie einen Idempotenzschlüssel hinzu:

curl ... -H "Idempotency-Key: unique-request-id-123"

Schlüssel verfallen nach 2 Stunden. Die Wiederverwendung desselben Schlüssels mit unterschiedlichen Parametern gibt einen Fehler zurück.

Häufige Fehler und Fehlerbehebung

Hier sind die Fehler, auf die Sie am wahrscheinlichsten stoßen werden, und wie Sie sie beheben können.

422 Unverarbeitbare Entität (Unprocessable Entity)

Dies bedeutet normalerweise, dass Ihr JSON fehlerhaft ist. Häufige Ursachen:

• Fehlende Anführungszeichen um Eigenschaftsnamen oder Zeichenfolgenwerte
• Nachgestellte Kommas in JSON-Objekten
• Verwenden von einfachen Anführungszeichen anstelle von doppelten Anführungszeichen
• Ungültige Escape-Sequenzen in Zeichenfolgen

Wenn Sie JSON-Zeichenfolgen manuell erstellen (insbesondere in VBA oder älteren Sprachen), achten Sie auf zusätzliche Anführungszeichen. Das JSON sollte so aussehen:

{"ticket": {"subject": "Test", "comment": {"body": "Hallo"}}}

Nicht so:

"{"ticket": {"subject": "Test"}}"

401 Nicht autorisiert (Unauthorized)

Ihre Anmeldeinformationen sind falsch. Überprüfen Sie:

• Ist die E-Mail-Adresse korrekt?
• Haben Sie /token nach der E-Mail-Adresse eingefügt?
• Ist das API-Token gültig und nicht abgelaufen?
• Hat der Benutzer die Berechtigung, Tickets zu erstellen?

429 Ratenbegrenzung überschritten (Rate Limit Exceeded)

Sie haben die API-Ratenbegrenzung erreicht. Zendesk erlaubt 700 Anfragen pro Minute für die meisten Endpunkte. Wenn Sie viele Tickets erstellen müssen, fügen Sie Verzögerungen zwischen den Anfragen hinzu oder verwenden Sie den Endpunkt für die Massenerstellung von Tickets.

400 Ungültige Anfrage (Bad Request) mit Feldfehlern

Dies geschieht, wenn Ticketfeldwerte ungültig sind:

• Benutzerdefinierte Feld-IDs existieren nicht
• Dropdown-Werte stimmen nicht mit den verfügbaren Optionen überein
• Erforderliche Felder fehlen
• Datumsformate sind falsch (verwenden Sie ISO 8601: 2026-03-01)

Automatisierung der Ticket-Erstellung ohne Code

Das Erstellen und Warten von API-Integrationen kostet Zeit. Sie müssen die Authentifizierung, die Logik für die Wiederholung von Fehlern, die Ratenbegrenzung und die laufende Wartung bei Änderungen der APIs verwalten.

Wenn Ihr Ziel darin besteht, die Ticket-Erstellung zu automatisieren, anstatt eine benutzerdefinierte Integration zu erstellen, überlegen Sie, ob Sie tatsächlich Code schreiben müssen. Tools wie eesel AI können die Ticket-Erstellung und -Beantwortung ohne Entwicklungsaufwand übernehmen.

Hier ist der Unterschied: Mit dem API-Ansatz schreiben Sie Skripte, um Tickets zu erstellen, auf die Menschen antworten werden. Mit einem KI-Agenten trainieren Sie ein System, um Ihr Unternehmen zu verstehen und den gesamten Ticket-Lebenszyklus von der Erstellung bis zur Lösung zu verwalten. Sie verbinden es mit Ihrem Zendesk-Konto, und es lernt aus Ihren vergangenen Tickets, Hilfeartikel und Makros.

Das progressive Rollout-Modell bedeutet, dass Sie damit beginnen, dass die KI Entwürfe für Antworten zur Überprüfung erstellt, und dann auf die vollständige Automatisierung ausweiten, sobald sie sich bewährt hat. Für Teams, die das Ticketvolumen reduzieren und nicht nur die Erstellung automatisieren möchten, liefert dies oft schnellere Ergebnisse als die benutzerdefinierte API-Entwicklung.