API-Zugriff erhalten
Nutzen Sie diese Funktion, um ein externes System über die GraphQL-API mit KORONA Event zu integrieren, beispielsweise um Bestellungen von einer Partnerplattform aus zu erstellen oder Kunden- und Bestelldaten abzurufen. In diesem Artikel wird die API-Terminologie verwendet; im übrigen Teil der Dokumentation werden dieselben Konzepte in Produktsprache beschrieben.
Bevor Sie beginnen
Bestätigen Sie:
- Sie wissen, auf welches Konto (Tenant) sich die Integration beziehen soll
- Ein Kontoadministrator kann die Integration und deren Umfang genehmigen
- Ihr Client kann HTTPS-POST-Anfragen mit benutzerdefinierten Headern senden
Anmeldeinformationen anfordern
Im Backoffice gibt es keine Seite zur Selbstausstellung von Tokens. API-Schlüssel werden von KORONA Event ausgestellt und sind an einen Mitarbeiter-Benutzer gebunden, sodass der Schlüssel die Rolle und die Berechtigungen dieses Benutzers übernimmt.
- Wenden Sie sich an den KORONA Event-Support und beschreiben Sie die Integration: um welches Konto es sich handelt, welche Daten Sie lesen oder schreiben und welches Anfragevolumen zu erwarten ist.
- Bitten Sie den Support, einen API-Schlüssel für einen speziellen Integrationsbenutzer anstelle eines persönlichen Kontos auszustellen, damit der Schlüssel auch bei Personalwechseln erhalten bleibt und seine Berechtigungen gezielt festgelegt werden können.
- Speichern Sie den Schlüssel in einem Schlüsselmanager. Jeder, der über den Schlüssel verfügt, kann mit den Berechtigungen dieses Benutzers handeln.
Bei Abläufen im Shop-Stil verhält es sich anders: Für die Suche nach öffentlichen Angeboten sind keine Anmeldedaten des Nutzers erforderlich, und bei Änderungen am Warenkorb wird das kurzlebige Zugriffstoken verwendet, das die API bei der Erstellung eines Warenkorbs oder bei der Anmeldung eines Kunden zurückgibt.
Anfragen authentifizieren
Die API basiert auf GraphQL über HTTPS mit einem einzigen Endpunkt pro Umgebung; der Support stellt Ihnen die Endpunkt-URL sowie den Link zur API-Referenz für Ihre Plattform zur Verfügung. Für jede Anfrage sind folgende Angaben erforderlich:
- `Authorization: Bearer <token>` – Ihr API-Schlüssel oder ein kurzlebiges Token für Shop-Abläufe. Öffentliche Abfragen zur Shop-Suche funktionieren auch ohne diesen Header.
- `X-Tenant-Domain` – die Domäne des Kontos oder Shops, an den die Anfrage gerichtet ist. Anfragen ohne gültigen Wert werden mit einer Fehlermeldung wie „Der HTTP-Header X-Tenant-Domain muss auf einen gültigen Shop verweisen“ abgelehnt.
- `Accept-Language` (optional) – die Sprachumgebung für übersetzte Inhalte.
Beispiel für die erste Anfrage:
```bash curl -X POST https://<api-endpoint>/graphql \ -H "Content-Type: application/json" \ -H "Authorization: Bearer <your-api-key>" \ -H "X-Tenant-Domain: <your-shop-domain>" \ -d '{"query": "{ tenant { name } }"}' ```
Eine erfolgreiche Antwort gibt den Kontonamen zurück, was bestätigt, dass das Token, der Mandanten-Header und der Endpunkt miteinander übereinstimmen.
Entdecken Sie das Schema
Das GraphQL-Schema ist selbstbeschreibend: Mit gültigen Anmeldedaten können Sie die Introspektion nutzen, sodass GraphQL-IDEs und Codegeneratoren mit dem Live-Endpunkt arbeiten können. KORONA Event veröffentlicht zudem eine generierte API-Referenz mit den Schematypen, Beispielabfragen und dem typischen Kaufablauf (Angebote entdecken, Warenkorb zusammenstellen, Kunden zuordnen, Bestellung abschließen, bezahlen); wenden Sie sich bitte an den Support, wenn Sie den Link zur Referenz noch nicht haben.
Geldbeträge überweisen
Argumente des GraphQL-Typs `Money` akzeptieren ein Objekt mit einer Ganzzahl `amount` in der kleinsten Einheit der Währung sowie einen gültigen ISO-Währungscode. Beispielsweise entspricht 12,34 EUR:
```json { "amount": 1234, "currency": "EUR" } ```
Senden Sie stets beide Felder und leiten Sie die Währung aus dem zu bearbeitenden Konto oder Angebot ab. Ein Nicht-Objekt-Wert, ein fehlerhaft serialisiertes Objekt, ein ungültiger Betrag oder eine unbekannte Währung werden als GraphQL-Eingabefehler zurückgewiesen. Die Mutation wird nicht verarbeitet; überprüfen Sie das `errors`-Array der Antwort, bevor Sie den Vorgang mit korrigierten Variablen erneut versuchen.
Für Ereignisse, die aus KORONA Event stammen (z. B. abgewickelte Bestellungen oder Kundenänderungen), verwenden Sie Webhooks anstelle von Polling; siehe Webhooks einrichten.
Nutzungsgrenzen
KORONA Event veröffentlicht keine festen Ratenbegrenzungen. Halten Sie das Anfragevolumen im Verhältnis zur tatsächlichen Nutzeraktivität, speichern Sie stabile Daten wie Angebotslisten im Cache und stimmen Sie das erwartete Volumen vor dem Start einer hochfrequenten Synchronisierung mit dem Support ab. Der Support kann Ihnen bei Anmeldedaten, Headern und dokumentierten Arbeitsabläufen behilflich sein; der Integrationscode selbst liegt in der Verantwortung Ihres Teams.
Erwartetes Ergebnis
Sie verfügen über einen API-Schlüssel für einen dedizierten Integrationsbenutzer, einen verifizierten Endpunkt und eine verifizierte Mandantendomäne sowie eine erste erfolgreiche GraphQL-Antwort.
Fehlerbehebung
| Problem | Was Sie überprüfen sollten |
|---|---|
| In der Antwort wird der „tenant“-Header beanstandet | „`X-Tenant-Domain`“ ist vorhanden und verweist auf eine gültige Shop- oder Kontodomäne für Ihre Plattform. |
| Anfragen werden als nicht autorisiert abgelehnt | Der `Authorization`-Header verwendet das `Bearer`-Schema, der Schlüssel ist unverändert, und der verknüpfte Benutzer ist weiterhin vorhanden und verfügt über die erforderlichen Berechtigungen. |
| Ein Feld gibt „null“ zurück oder wird abgelehnt | Die Rolle des Integrationsbenutzers; die API erzwingt dieselben Berechtigungen wie das Backoffice. |
| Die Selbstreflexion schlägt fehl | Ob Sie den richtigen Endpunkt für Ihre Plattform mit gültigen Anmeldedaten aufrufen. |
| Ein Geldwert wird abgelehnt | `amount` ist eine Ganzzahl in der kleinsten Währungseinheit, `currency` ist ein gültiger Code, und beide Felder befinden sich innerhalb eines Objekts. |
