Ü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 APIhttps://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.
Versionierung
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
- 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.
- http
- curl
- php
- C#
- python
- ruby
- java
- js
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:Aktion | HTTP-Methode | Beschreibung |
---|---|---|
Erstellen | POST | Erstellt und speichert eine Entität des angegebenen Typs. |
Auflisten | GET | Liefert 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. |
Abrufen | GET | Liefert detaillierte Angaben zur Entität mit der angegebenen ID. |
Ersetzen | PUT | Modifiziert alle Felder der Entität mit der angegebenen ID. |
Aktualisieren | PATCH | Modifiziert bestimmte Felder der Entität mit der angegebenen ID. |
Löschen | DELETE | Lö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:
Bezeichnung | Typ | Beschreibung |
---|---|---|
http_status_code | integer | HTTP-Code. |
message | string | Eine 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_message | string | Detailliertere Fehlerbeschreibung. |
request_id | string | Eindeutige Request-ID, die wir eventuell für die Fehlersuche verwenden können. |
- http
{
"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?
Diese Seite bewerten
Jetzt nicht
Vielen Dank für Ihr Feedback!
Haben Sie einen Tippfehler oder einen anderen Textfehler gefunden? Wählen Sie den Text aus und drücken Sie Strg+Eingabe.