Überblick

Die Xsolla-API umfasst:

• Pay Station API – Zahlungsportal und Tokenisierungsmethoden.
• Commerce 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 Integrationsanleitung).

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

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

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

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

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

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!