Überblick

Die Xsolla-API umfasst die:

• Pay Station API – Zahlungsportal und Tokenisierungsmethoden.
• IGS&BB API – Methoden für die Arbeit mit den Modulen Ingame-Online-Shop und Buy Button.
• Subscription API – Methoden für Abonnements.
• Publisher Account API – Methoden für die Arbeit mit Kundenportal-Projekten sowie Benutzern, Berichten und Support-Tickets.
• Login API – Methoden für die Benutzerauthentifizierung über Ihre eigene Benutzeroberfläche (siehe Integrationsleitfaden).

Die Xsolla-API basiert auf REST. Die API hat vorhersagbare, ressourcenorientierte URLs und verwendet HTTP-Statuscodes, um API-Fehler anzuzeigen. Die API antwortet stets im JSON-Format, auch im Falle von Fehlern.

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.

Die Xsolla-API nutzt folgende Endpunktpfade:

• https://api.xsolla.com – Pay Station API, IGS&BB API, Publisher Account API
• https://login.xsolla.com/api – Login API

Anfragen und Antworten

Die Anfragen an die Xsolla-API müssen:

• ü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

Xsolla kann die API-Funktionalität folgendermaßen ändern:

• 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

Ihr Client sollte, unabhängig von derartigen Änderungen funktionsfähig bleiben. Beispielsweise sollten neue JSON-Parameter, welche von Ihrem Client nicht erkannt werden, den normalen Betrieb des Clients nicht behindern.

Ver­si­o­nie­rung

Alle Xsolla-API-Methoden unterstützen Versionierung. Wir werden immer dann eine neue Version veröffentlichen, wenn es Änderungen gibt, die mit der aktuellen Version nicht kompatibel sind. Die Version ist in der URL durch die Angabe von "v1"/"v2"/usw., welche auf das Präfix "/merchant" folgt, identifizierbar.

Nutzen Sie bitte die neuste Version, falls Sie das erste Mal mit der API arbeiten. Wenn Sie die Versionsangabe weglassen, verwenden wir standardmäßig die erste Version.

Authentifizierung

Die Xsolla-API nutzt die Basisauthentifizierung. Alle Anfragen an die API müssen den Header Authorization: Basic <your_authorization_basic_key> enthalten, wobei <your_authorization_basic_key> das gemäß dem Base64-Standard kodierte Paar Händler-ID:API-Schlüssel ist. Die Parameter finden Sie im Kundenportal:

• Die Händler-ID finden Sie:
  • unter Projekteinstellungen > Webhooks.
  • 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/​Händler-ID/Kundeportalabschnitt.

• 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

Endpunkttypen

Datumsformat

Paginierung

Fehlerbehandlung

Liste der unterstützten HTTP-Statuscodes:

• 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.

Xsolla verwendet konventionelle HTTP-Statuscodes, um zu verdeutlichen, ob die API-Anfrage erfolgreich war. steht 2xx für eine erfolgreiche Anfrage, 4xx weist auf einen Fehler bei den bereitgestellten Daten hin (z. B.:Fehlen eines erforderlichen Parameters, fehlgeschlagene Autorisierung usw.) und 5xx deutet auf ein Problem mit Xsollas

Jedoch entsprechen nicht alle Fehler exakt den HTTP-Statuscodes. Beispielsweise wird die API den Fehlercode 422 zurückgeben, falls eine Anfrage gültig war, aber fehlgeschlagen ist.

Alle API-Fehlerrückmeldungen liefern ein JSON-Objekt mit folgenden Feldern:

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

Ratenbegrenzungen

Allgemeine Informationen

Um Xsolla-Systeme nicht zu überlasten und vor einer Flut von eingehendem Traffic zu schützen, begrenzt Xsolla die von der Xsolla-API empfangenen Anfragen innerhalb eines bestimmten Zeitraums. Wird das Limit überschritten, antwortet die Xsolla-API mit dem HTTP-Statuscode 429.

Die Limits variieren je nach Methode, Projekt und anderen Faktoren. Die aktuellen Limits werden regelmäßig aktualisiert, damit die Xsolla-Systeme stabil und störungsfrei laufen. In einigen Fällen ist es möglich, die angegebenen Limits auf Anfrage anzupassen. Wenden Sie sich dazu an Ihren Account Manager oder senden Sie eine E-Mail an am@xsolla.com.

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 Admin, die nicht für den häufigen Gebrauch gedacht sind, anstelle der Methoden der Untergruppe Catalog
  • häufiger Aufruf der Methode Get order, 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 Get virtual items list zur Anzeige eines Artikelkatalogs.

Handhabung von Ratenbegrenzungen

Um durch die Ratenbegrenzungen verursachte Fehler zu vermeiden, empfehlen wir Folgendes:

• 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&BB 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

So löschen Sie einen API-Schlüssel:

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.

Durch das Löschen eines API-Schlüssels:

• 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.

So beugen Sie dem vor:

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.

Diese Seite bewerten

Gibt es etwas, das wir verbessern können? Senden

Jetzt nicht

Vielen Dank für Ihr Feedback!