Überblick

Die Xsolla-API umfasst die:

• Pay Station API – Zahlungsportal und Tokenisierungsmethoden.
• IGS API – Methoden für die Arbeit mit dem Modul In-Game Store.
• Subscriptions API – Methoden für Abonnements.
• Login API – Methoden für die Benutzerauthentifizierung über Ihre eigene Benutzeroberfläche (siehe Integrationsleitfaden).

Die API nutzt integrierte HTTP-Funktionen wie HTTP-Authentifizierung und HTTP-Methoden, die von gängigen HTTP-Clients interpretiert werden können. Die Schnittstelle unterstützt Cross-Origin Resource Sharing und gestattet Ihnen dadurch den sicheren Zugriff auf die API über eine clientseitige Webanwendung.

• https://api.xsolla.com – Pay Station API, Subscriptions API
• https://login.xsolla.com/api – Login API
• https://store.xsolla.com/api — IGS API

Anfragen und Antworten

• über HTTPS gesendet werden,
• TLS 1.2 oder höher nutzen,
• Parameter zur Authentifizierung enthalten,
• einen zusätzlichen Header für PUT- und POST-Anfragen aufweisen: Content-Type: application/json.

Authorization: Basic <your_authorization_basic_key>
Content-Type: application/json

Standardmäßig folgt auf sämtliche Anfragen eine Antwort samt JSON-Daten im Body und Content-Type: application/json im Header.

API-Änderungen

• Neue API-Ressourcen hinzufügen;
• Optionale Anfrageparameter hinzufügen;
• Bestehenden API-Antworten neue Eigenschaften hinzufügen;
• Bestehenden Parametern, die über zählbare Werte verfügen, neue Werte hinzufügen;
• Neue Arten von Webhooks und neue JSON-Parameter hinzufügen;
• Optionale HTTP-Anfrage-Header hinzufügen;
• Anfragen, bei denen gültigen Parametern ungültige Werte zugeordnet wurden, ablehnen.
• Unzulässig formatierte Anfragen, welche zuvor aufgrund von tolerantem Parsing akzeptiert wurden, ablehnen, falls sich die Logik des Parsers geändert hat.
• Undokumentierte Funktionen jederzeit hinzufügen, ändern oder entfernen

Ver­si­o­nie­rung

Authentifizierung

• Basisauthentifizierung. Solche API-Anfragen müssen den Header Authorization: Basic <your_authorization_basic_key< enthalten, wobei <your_authorization_basic_key> das Paar Händler-ID:API-Schlüssel ist, das gemäß dem Base64-Standard codiert ist. Diese Parameter finden Sie im Kundenportal:
  • Die Händler-ID wird an den folgenden Orten angezeigt:
    • unter Firmeneinstellungen > Firma.
    • in der URL in der Adresszeile des Browsers auf einer beliebigen Seite im Kundenportal. Die URL weist das folgende Format auf: https:​//publisher.xsolla.com/<merchant ID>/<Publisher Account section>.
  • Der API-Schlüssel wird im Kundenportal nur einmal angezeigt, nämlich dann, wenn er erstellt wird. Sie sind selbst dafür verantwortlich, den Schlüssel zu speichern. Einen neuen Schlüssel können Sie in den folgenden Abschnitten erstellen:
    • Firmeneinstellungen > API-Schlüssel
    • Projekteinstellungen > API-Schlüssel
• Authentifizierung über den Benutzer-JWT. Solche Anfragen an die API müssen den Header Authorization: Bearer <user_JWT> enthalten, wobei <user_JWT> der Nutzertoken ist.
• Authentifizierung über den Server-JWT. Solche API-Methoden müssen den Header X-SERVER-AUTHORIZATION: <server_JWT> enthalten, wobei <server_JWT> der Servertoken ist.
• Ohne Authentifizierung.

API-Aufrufe nach Interaktionsmodell

• Clientseitige API-Aufrufe: API-Aufrufe für die Interaktion zwischen dem Anwendungs-Client des Partners und dem Xsolla-Server. Nutzeraktionen auf dem Client lösen den API-Aufrufe aus. Clientseitige API-Aufrufe (Beispiel): Liste von Gegenständen abrufen, Nutzer authentifizieren, Zahlungstoken vom Client abrufen.
• Serverseitige API-Aufrufe: API-Aufrufe für die Interaktion zwischen dem Server des Partners und dem Xsolla-Server. Diese Aufrufe sind für die folgenden Aufgaben vorgesehen:
  • Implementation des Nutzerablaufs.
    Nutzeraktionen auf dem Client bewirken einen API-Aufruf aufseiten des Partner-Clients, woraufhin Xsollas serverseitiger API-Aufruf aufseiten des Partner-Servers aufgerufen wird.Serverseitige API-Aufrufe für die Implementierung des Nutzerablaufs: Benutzerattribute auf dem Server aktualisieren, Zahlungstoken vom Server abrufen.
  • Administrative Aufgaben oder Einrichtung von Xsolla-Produkten durch den Partner.
    Nutzeraktionen auf dem Client können keinen Aufruf dieser Methoden bewirken. Administrativer serverseitiger API-Aufruf (Beispiel): Artikel oder Werbeaktion erstellen und bearbeiten.

• Überschreitung der Ratenbegrenzungen:
  • Die Ratenbegrenzungen für serverseitige API-Aufrufe sind strenger als für clientseitige API-Aufrufe.
  • Die Ratenbegrenzungen für administrative serverseitige API-Aufrufe sind strenger als für API-Aufrufe zur Implementierung des Nutzerablaufs.
• Empfang irrelevanter Informationen in der Antwort. Zum Beispiel, wenn Sie serverseitige API-Aufrufe verwenden, um eine Liste von Artikeln für den Administrator abzurufen, anstatt clientseitige API-Aufrufe zu verwenden, um eine Liste von Artikeln für die Erstellung eines Katalogs abzurufen.
• Nicht autorisierte Datenänderungen durch die Nutzer. Zum Beispiel, wenn clientseitige API-Aufrufe zur Aktualisierung von Attributen verwendet werden, anstelle von serverseitigen API-Aufrufen.
• Falsch ermitteltes Land oder falsch ermittelte Währung im Zahlungsportal.

Ob ein API-Aufruf client- oder serverseitig erfolgt, können Sie anhand des Authentifizierungsschemas feststellen:

• Clientseitige Aufrufe werden ohne Authentifizierung oder mit dem Header Authorization header: Bearer <user_JWT> aufgerufen, wobei <user_JWT> der Benutzertoken ist.
• Serverseitige API-Aufrufe zur Implementierung des Nutzerablaufs werden mit einem der folgenden Header aufgerufen:
  • X-SERVER-AUTHORIZATION: <server_JWT>, wobei <server_JWT> der Servertoken ist, und
  • Authorization: Basic <your_authorization_basic_key>, wobei <your_authorization_basic_key> das project_id:api_key-Paar ist, kodiert gemäßg dem Base64-Standard.
• Serverseitige API-Aufrufe für administrative Aufgaben werden mit dem Header Authorization: Basic <your_authorization_basic_key> aufgerufen, wobei <your_authorization_basic_key> das project_id:api_key-Paar ist, kodiert gemäßg dem Base64-Standard.

Serverseitige API-Aufrufe mit serverseitiger Authentifizierung (Beispiel):

Clientseitige API-Aufrufe mit clientseitiger Authentifizierung (Beispiel):

Je nach Ihren Anforderungen können Sie bei der Implementierung des Nutzerablaufs wählen, wie die Integration erfolgen soll: entweder mit serverseitigen oder clientseitigen API-Aufrufen. Es wird davon abgeraten, serverseitige administrative API-Aufrufe zur Implementierung des Nutzerablauf zu verwenden.

Implementierung eines Nutzerablaufs mithilfe von clientseitigen API-Aufrufen (Beispiel):

1. Der Nutzer führt Aktionen auf dem Client aus, z. B.: legt er einen Artikel in den Warenkorb und kauft den Artikel.
2. Der Spiel-Client sendet eine Anfrage samt Daten an den Xsolla-Server.
3. Der Xsolla-Server antwortet dem Spiel-Client.
4. Der Spiel-Client zeigt dem Nutzer das Ergebnis an.

Bei diesem Ablauf erfolgt die Authentifizierung über den Benutzer-JWT.

Implementierung eines Nutzerablaufs mithilfe von serverseitigen API-Aufrufen (Beispiel):

1. Der Nutzer führt Aktionen auf dem Client aus, z. B.: legt er einen Artikel in den Warenkorb und kauft den Artikel.
2. Der Spiel-Client sendet eine Anfrage an den Spielserver.
3. Falls erforderlich, verarbeitet der Partner zusätzliche Daten auf dem Spielserver.
4. Der Spielserver sendet eine Anfrage an den Xsolla-Server.
5. Der Xsolla-Server antwortet dem Spielserver.
6. Der Spielserver verarbeitet die Daten und antwortet dem Spiel-Client.
7. Der Spiel-Client zeigt dem Nutzer das Ergebnis an.

Bei diesem Ablauf kommt die Basisauthentifizierung oder ein Servertoken zum Einsatz.

Interaktionsablauf bei Nutzung von serverseitigen administrativen API-Aufrufen:

1. Der Partner sendet eine Anfrage von seinem Anwendungs-Client oder ‑Server an den Xsolla-Server.
2. Der Xsolla-Server antwortet mit dem Ergebnis der verarbeiteten Anfrage.

Endpunkttypen

Datumsformat

Paginierung

Fehlerbehandlung

• 200, 201, 204 – Kein Fehler.
• 400 Bad Request – Weist oftmals darauf hin, dass ein erforderlicher Parameter fehlt. Weitere Informationen finden Sie im Nachrichtenrumpf.
• 401 Unauthorized – Kein gültiger API-Schlüssel bereitgestellt.
• 402 Request Failed – Anfrage trotz gültiger Parameter fehlgeschlagen.
• 403 Forbidden – Keine Berechtigung. Weitere Informationen finden Sie im Nachrichtenrumpf.
• 404 Not Found – Die angeforderte Ressource konnte nicht gefunden werden.
• 409, 422 – Ungültige Anfrageparameter.
• 412 Precondition Failed – Das Projekt wurde noch nicht aktiviert (wird bei der Token erstellen-Methode verwendet).
• 415 Unsupported Media Type – Im HTTP-Header fehlt die Angabe Content-Type: application/json.
• 500, 502, 503, 504 Server Errors – Etwas ist schiefgelaufen.

{
    "http_status_code": 500,
    "message": "Internal Server Error",
    "extended_message": null,
    "request_id": "6445b85"
}

Ratenbegrenzungen

Allgemeine Informationen

Häufige Ursachen für die Überschreitung der Ratenbegrenzungen

• Eine plötzliche Zunahme des Traffics aufseiten des Partners infolge von:
  • saisonalen Sales
  • Beginn einer geschlossenen und offenen Testphase
• Eine plötzliche Zunahme des Traffics infolge von DDoS-Angriffen aufseiten des Partners.
• Falsch konfigurierte Integration, zum Beispiel:
  • Verwendung von Methoden der Untergruppe Verwaltung, die nicht für den häufigen Gebrauch gedacht sind, anstelle der Methoden der Untergruppe Katalog
  • häufiger Aufruf der Methode Bestellung abrufen, um den Status einer Bestellung und die Liste der darin enthaltenen Artikel abzurufen. Zum Beispiel: 1 pro Sekunde, obwohl die empfohlene Verzögerung zwischen den Anfragen 3 Sekunden betragen sollte
• Übermäßig viele Anfragen innerhalb eines bestimmten Zeitraums. Zum Beispiel: mehr als 200 Aufrufe pro Sekunde an die Methode Liste virtueller Gegenstände abrufen zur Anzeige eines Artikelkatalogs.

Handhabung von Ratenbegrenzungen

• Tracken Sie den Statuscode 429, und erstellen Sie einen Wiederholungsmechanismus. Sie können das Wiederholungsmuster mit festem oder exponentiellem Backoff zwischen den Wiederholungen verwenden, anstelle von kontinuierlichen Wiederholungen.
• Optimieren Sie den Code so, dass nur die erforderlichen Daten abgerufen werden. Senden Sie nur Anfragen, die Ihre Anwendung benötigt, und vermeiden Sie unnötige API-Aufrufe. Wenn Sie die IGS API verwenden, können Sie mithilfe der WebSocket API die Anzahl der Aufrufe reduzieren.
• Zwischenspeichern Sie Daten, die häufig von Ihrer Anwendung verwendet werden. Die statischen Daten sollten Sie in einem eigenen Speicher hinterlegen und die Anzahl der Anfragen an die externe API reduzieren.
• Verhindern Sie DDoS-Angriffe, die Ihre API lahmlegen können.
• Passen Sie die Rate an, um eine gleichmäßigere Distribution zu erreichen. Tritt der Fehlercode 429 regelmäßig auf, sollten Sie einen Prozess in Ihren Code einbauen, der reguliert, in welchen zeitlichen Abständen Anfragen gesendet werden.

API-Schlüssel

Ein API-Schlüssel ist ein eindeutiger Schlüssel und dient dazu, Nutzerdaten zu verschlüsseln und API-Anfragen zu authentifizieren. Im Kundenportal können Sie API-Schlüssel für alle oder einzelne Firmenprojekte erstellen.

API-Schlüssel erstellen

1. Öffnen Sie das Kundenportal.
2. Navigieren Sie zu Firmeneinstellungen > API-Schlüssel oder Projekteinstellungen > API-Schlüssel.
3. Klicken Sie auf API-Schlüssel erstellen.
4. Füllen Sie die folgenden Felder aus:
   • Schlüsselname, dieser wird in der Schlüsselliste angezeigt. Vergeben Sie einen leicht zu identifizierenden Namen.
   • Schlüsseltyp – dauerhaft oder temporär.
   • Ablaufdatum – nur bei temporären Schlüsseln. Nach dem Ablaufdatum ist der Schlüssel nicht mehr gültig, Sie müssen einen neuen Schlüssel erstellen.
   • Projekt, für das der Schlüssel gültig ist (sollten Sie einen API-Schlüssel auf der Projektseite erstellt haben, wird dieses Feld nicht angezeigt). Standardmäßig sind alle Projekte ausgewählt.
5. Klicken Sie auf Erstellen.
6. Klicken Sie im sich daraufhin öffnenden Fenster auf API-Schlüssel kopieren, und speichern Sie den erstellten API-Schlüssel bei sich ab.

API-Schlüssel löschen

1. Öffnen Sie das Kundenportal.
2. Navigieren Sie zu Firmeneinstellungen > API-Schlüssel oder Projekteinstellungen > API-Schlüssel.
3. Klicken Sie in der Zeile des gewünschten API-Schlüssels auf das Papierkorb-Symbol, und bestätigen Sie die Aktion.

• lassen sich keine Zahlungen mehr in den Projekten entgegennehmen, in denen dieser API-Schlüssel verwendet wurde;
• lassen sich keine API-Methoden mehr aufrufen, die diesen API-Schlüssel verwendet haben.

1. Erstellen Sie einen neuen API-Schlüssel.
2. Aktualisieren Sie die API-Schlüssel in Ihren Anwendungen.
3. Löschen Sie den ursprünglichen API-Schlüssel.

Webhooks

Webhooks ermöglichen es, Sofortbenachrichtigungen über konfigurierte Ereignisse aufseiten von Xsolla zu erhalten. Sie können die Verarbeitung der Webhooks einrichten und so Ihre Anwendung automatisieren. In unserer Dokumentation finden Sie eine Liste der verfügbaren Webhooks und detaillierte Beschreibungen ihrer Funktionsweise.