Erste Schritte

Überblick

Die Xsolla-API umfasst:

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, Commerce 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.

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

    Authentifizierung

    Xsolla-API nutzt Basisauthentifizierung. Alle Anfragen an die API müssen im Header Authorization: Basic <your_authorization_basic_key> enthalten, wobei <your_authorization_basic_key> dem, gemäß Base64-Standard, kodierten merchant_id:api_key-Paar entspricht.

    Navigieren Sie zum Xsolla-Kundenportal, um die Werte der merchant_id- und api_key-Parameter zu erhalten:

    • merchant_id: Firmeneinstellungen > Firma > Händler-ID
    • api_key: Firmeneinstellungen > API-Schlüssel

    Notice:
    • Halten Sie Ihren API-Schlüssel geheim. Er ermöglicht den Zugriff auf Ihr persönliches Konto und Ihre Projekte im Kundenportal.
    • Eine Änderung des API-Schlüssels kann dazu führen, dass Zahlungen an alle Ihre Projekte gestoppt werden. API-Aufrufe mit Ihrem derzeitigen Schlüssel funktionieren erst wieder, wenn Sie sie mit Ihrem neuen Schlüssel aktualisieren.
    Copy
    Full screen
    Small screen
    http
    • http
    • curl
    • php
    • C#
    • python
    • ruby
    • java
    • js
    Beispiel
    GET https://api.xsolla.com/merchant/v2/merchants/{merchant_id}/events/messages
    Headers:
      Authorization: Basic <your_authorization_basic_key>
    curl --request GET \
    --url 'https://api.xsolla.com/merchant/v2/merchants/{merchant_id}/events/messages' \
    --header 'authorization: Basic <your_authorization_basic_key>'
    <?php
    
    // if you use Xsolla SDK for PHP
    use Xsolla\SDK\API\XsollaClient;
    $xsollaClient = XsollaClient::factory(array(
        'merchant_id' => MERCHANT_ID,
        'api_key' => API_KEY
    ));
    $eventsList = $client->ListEvents(array());
    
    // if you don’t use Xsolla SDK for PHP
    $client = new http\Client;
    $request = new http\Client\Request;
    
    $request->setRequestUrl('https://api.xsolla.com/merchant/v2/merchants/{merchant_id}/events/messages');
    $request->setRequestMethod('GET');
    $request->setHeaders(array(
      'authorization' => 'Basic <your_authorization_basic_key>'
    ));
    
    $client->enqueue($request)->send();
    $response = $client->getResponse();
    
    echo $response->getBody();
    
    var client = new RestClient("https://api.xsolla.com/merchant/v2/merchants/{merchant_id}/events/messages");
    var request = new RestRequest(Method.GET);
    request.AddHeader("authorization", "Basic <your_authorization_basic_key>");
    IRestResponse response = client.Execute(request);
    
    import http.client
    
    conn = http.client.HTTPSConnection("api.xsolla.com")
    
    headers = { 'authorization': "Basic <your_authorization_basic_key>" }
    
    conn.request("GET", "/merchant/v2/merchants/{merchant_id}/events/messages", headers=headers)
    
    res = conn.getresponse()
    data = res.read()
    
    print(data.decode("utf-8"))
    require 'uri'
    require 'net/http'
    
    url = URI("https://api.xsolla.com/merchant/v2/merchants/{merchant_id}/events/messages")
    
    http = Net::HTTP.new(url.host, url.port)
    http.use_ssl = true
    http.verify_mode = OpenSSL::SSL::VERIFY_NONE
    
    request = Net::HTTP::Get.new(url)
    request["authorization"] = 'Basic <your_authorization_basic_key>'
    
    response = http.request(request)
    puts response.read_body
    OkHttpClient client = new OkHttpClient();
    
    Request request = new Request.Builder()
      .url("https://api.xsolla.com/merchant/v2/merchants/{merchant_id}/events/messages")
      .get()
      .addHeader("authorization", "Basic <your_authorization_basic_key>")
      .build();
    
    Response response = client.newCall(request).execute();
    var data = null;
    
    var xhr = new XMLHttpRequest();
    xhr.withCredentials = true;
    
    xhr.addEventListener("readystatechange", function () {
      if (this.readyState === this.DONE) {
        console.log(this.responseText);
      }
    });
    
    xhr.open("GET", "https://api.xsolla.com/merchant/v2/merchants/{merchant_id}/events/messages");
    xhr.setRequestHeader("authorization", "Basic <your_authorization_basic_key>");
    
    xhr.send(data);
    

    Typen von Endpunkten

    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"
    }

    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.