Erste Schritte

Überblick

Die Xsolla-API umfasst die:

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
Die meisten Endpunktpfade enthalten die merchant_id als Parameter. Dadurch ist ersichtlich, dass die Anwendung in Ihrem Auftrag handelt.

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.

Copy
Full screen
Small screen

    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.

    Hinweis
    Denken Sie bitte daran, dass wir API-Integrität nur innerhalb der gleichen Version garantieren können.

    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

    Achtung

    Weitere Informationen über die Arbeit mit API-Schlüsseln finden Sie in der API-Referenz.

    Wichtige Empfehlungen:

    • Sie sind selbst dafür verantwortlich, den generierten API-Schlüssel zu speichern. Der API-Schlüssel wird im Kundenportal nur einmal angezeigt, nämlich dann, wenn er erstellt wird.
    • Halten Sie Ihren API-Schlüssel geheim. Er gewährt den Zugang zu Ihrem persönlichen Konto und Ihren Projekten im Kundenportal.
    • Der API-Schlüssel muss auf Ihrem Server gespeichert sein, niemals in Binärdateien oder im Frontend.

    Endpunkttypen

    Der Endpunkttyp gibt an, welche Art von Daten der Endpunkt verarbeitet und welche Aktionen ausgeführt werden. Die häufigsten Aktionen sind:

    AktionHTTP-MethodeBeschreibung
    ErstellenPOSTErstellt und speichert eine Entität des angegebenen Typs.
    AuflistenGETLiefert eine Liste von Entitäten, die der Anfrage entsprechen. Um Details zu einer Entität anzufordern, muss zuerst deren ID mit Hilfe des Endpunkttyps "Auflisten" bestimmt werden. Danach muss diese ID am entsprechenden Endpunkt (Typ: "Abrufen") bereitgestellt werden.
    AbrufenGETLiefert detaillierte Angaben zur Entität mit der angegebenen ID.
    ErsetzenPUTModifiziert alle Felder der Entität mit der angegebenen ID.
    AktualisierenPATCHModifiziert bestimmte Felder der Entität mit der angegebenen ID.
    LöschenDELETELöscht die Entität mit der angegebenen ID.

    Datumsformat

    Alle Datumsangaben sind spezifiziert als Strings gemäß ISO 8601. Sie können die Datumstrings entweder als UTC (z. B.: 2013-01-15T00:00:00Z) angeben oder die Abweichung von der UTC anzeigen lassen Im letzteren Fall ist darauf zu achten,dass gegebenenfalls die Sommerzeit berücksichtigt werden muss.

    Paginierung

    Endpunkte des Typs "Auflisten" können die gelieferten Ergebnisse paginieren. Anstelle alle Ergebnisse in einer einzigen Antwort zu versenden Können diese Endpunkte einige der Ergebnisse gemeinsam mit einem Antwort-Header zurückgeben, welcher zu den nächsten Ergebnissen verlinkt. Zu diesem Zweck verwenden wir Offset- und Limit-Parameter.

    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:

    BezeichnungTypBeschreibung
    http_status_codeintegerHTTP-Code.
    messagestringEine für Menschen verständliche Meldung, welche den Fehler beschreibt. Diese Nachricht wird immer in englischer Sprache ausgegeben. Verlassen Sie sich bei einem bestimmten Fehler nicht auf die Aussagekraft der Meldung, da sich diese Nachricht in Zukunft ändern könnte.
    extended_messagestringDetailliertere Fehlerbeschreibung.
    request_idstringEindeutige Request-ID, die wir eventuell für die Fehlersuche verwenden können.
    Copy
    Full screen
    Small screen

    {
        "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.

    Hinweis
    API-Schlüssel, die für alle Firmenprojekte gültig sind, werden auf den Seiten der einzelnen Projekte nicht angezeigt.
    Achtung

    Um mit API-Schlüsseln zu arbeiten (Schlüsselliste anzeigen, Schlüssel erstellen und löschen), muss Ihnen eine der folgenden Rollen zugewiesen sein:

    • Entwickler
    • Inhaber

    Nur ein Projektinhaber kann Rollen im Kundenportal unter Firmeneinstellungen > Nutzer ändern.

    API-Schlüssel erstellen

    So erstellen 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 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.

    Hinweis
    Wenn Sie einen API-Schlüssel auf der Projektseite erstellen, ist der Schlüssel nur für dieses bestimmte Projekt gültig.
    Achtung
    Wichtige Empfehlungen:
    • Sie sind selbst dafür verantwortlich, den generierten API-Schlüssel zu speichern. Der API-Schlüssel wird im Kundenportal nur einmal angezeigt, nämlich dann, wenn er erstellt wird.
    • Halten Sie Ihren API-Schlüssel geheim. Er gewährt den Zugang zu Ihrem persönlichen Konto und Ihren Projekten im Kundenportal.
    • Der API-Schlüssel muss auf Ihrem Server gespeichert sein, niemals in Binärdateien oder im Frontend.

    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.

    War dieser Artikel hilfreich?
    Vielen Dank!
    Gibt es etwas, das wir verbessern können? Nachricht
    Das tut uns leid
    Bitte erläutern Sie, weshalb dieser Artikel nicht hilfreich ist. Nachricht
    Vielen Dank für Ihr Feedback!
    Wir werden Ihr Feedback aufgreifen und dazu nutzen, Ihr Erlebnis verbessern.
    Diese Seite bewerten
    Diese Seite bewerten
    Gibt es etwas, das wir verbessern können?

    Jetzt nicht

    Vielen Dank für Ihr Feedback!
    Letztmalig aktualisiert: 16. August 2021

    Haben Sie einen Tippfehler oder einen anderen Textfehler gefunden? Wählen Sie den Text aus und drücken Sie Strg+Eingabe.