Zum Inhalt springen
/
Virtuellen Gegenstand anh...

Katalog-API (2.0.0)

Überblick

  • Version: 2.0.0
  • Server: https://store.xsolla.com/api
  • Kontakt per E-Mail
  • Kontakt-URL: https://xsolla.com/
  • Erforderliche TLS-Version: 1.2

Mit der Katalog-API können Sie aufseiten von Xsolla einen Katalog mit Ingame-Items konfigurieren und diesen Katalog den Nutzern in Ihrem Shop anzeigen.

Über die API können Sie die folgenden Katalogentitäten verwalten:

  • Virtuelle Gegenstände – Ingame-Items wie etwa Waffen, Skins, Booster.
  • Virtuelle Währung – Virtuelles Geld für den Kauf von virtuellen Gütern.
  • Virtuelle Währungspakete – vordefinierte Pakete voller virtueller Währung.
  • Bundles – eine Kombination aus virtuellen Gegenständen, Währung oder Spielschlüsseln. Bundles werden als eine einzelne SKU verkauft.
  • Spielschlüssel – Schlüssel für Spiele oder DLCs, die über Plattformen wie Steam oder andere DRM-Anbieter vertrieben werden.
  • Gruppen – logische Gruppierungen, um Artikel im Katalog zu organisieren und zu sortieren.

API-Aufrufe

Die API ist in die folgenden Gruppen unterteilt:

  • Admin – Aufrufe zum Erstellen, Aktualisieren, Löschen und Konfigurieren von Katalogartikeln und ‑gruppen. Die Authentifizierung erfolgt über die Basisauthentifizierung und Ihre Händler- oder Projekt-Anmeldedaten. Diese Aufrufe sind nicht für den Storefront bestimmt.
  • Catalog – Aufrufe zum Abrufen von Artikeln und zum Erstellen benutzerdefinierter Storefronts für Endnutzer. Konzipiert für den Einsatz unter hoher Auslastung. Unterstützt die optionale Nutzer-JWT-Autorisierung und kann personalisierte Daten (z. B. benutzerspezifische Limits und aktive Werbeaktionen) zurückgeben.
OpenAPI-Beschreibung herunterladen
index.json
index.yaml
Sprachen
Server
https://store.xsolla.com/api/
Mock server
https://xsolla.redocly.app/_mock/de/api/catalog/

Verwaltung

Operationen

Katalog

Operationen

Artikelliste anhand angegebener Gruppe abrufenClient-side

Anfrage

Ruft eine Artikelliste aus einer angegebenen Gruppe ab, um einen Katalog zu erstellen.

Achtung

Bei allen Projekten ist die Anzahl der Artikel begrenzt, die Sie erhalten können in der Antwort. Der Standard- und Höchstwert beträgt 50 Artikel pro Antwort. Um Seite für Seite mehr Daten zu erhalten, verwenden Sie die Felder limit und offset.

Hinweis

Auf diesen Endpunkt kann man ohne Autorisierung zugreifen, er gibt generische Daten zurück. Liegt eine Autorisierung vor, ist die Antwort jedoch mit benutzerspezifischen Details (z. B. vorhandene Nutzerlimits und Werbeaktionen) angereichert und sorgt so für ein personalisiertes Ergebnis.
Sicherheit
XsollaLoginUserJWT
Pfad
project_idintegererforderlich

Projekt-ID. Dieser Parameter wird im Kundenportal neben dem Projektnamen angezeigt.

Beispiel: 44056
external_idstringerforderlich

Externe ID der Gruppe.

Standard "all"
Abfrage
limitinteger>= 1

Begrenzung der Elementanzahl auf der Seite.

Beispiel: limit=50
offsetinteger>= 0

Elementnummer, aus der die Liste generiert wird (die Zählung beginnt bei 0).

Beispiel: offset=0
localestring

Antwortsprache. Sprachcode bestehend aus zwei Kleinbuchstaben gemäß ISO 639-1.

Standard "en"
additional_fields[]Array of strings

Die Liste der zusätzlichen Felder. Diese Felder sind in der Antwort enthalten, sofern Sie diese in der Anfrage senden.

Elemente Enum"media_list""order""long_description""custom_attributes""item_order_in_group"
countrystring

Zweistelliger Ländercode in Großbuchstaben gemäß ISO 3166-1 Alpha-2. Weitere Informationen zu den von Xsolla unterstützten Ländern und dazu, wie das Land ermittelt wird, finden Sie in der Dokumentation.

Beispiel: country=US
promo_codestring[ 1 .. 128 ] characters

Eindeutiger Code, es wird zwischen Groß- und Kleinschreibung unterschieden. Enthält Buchstaben und Ziffern.

Beispiel: promo_code=WINTER2021
show_inactive_time_limited_itemsinteger

Zeigt zeitlich begrenzte Artikel an, die nicht erhältlich sind. Der Gültigkeitszeitraum dieser Artikel hat noch nicht begonnen oder ist bereits vorüber.

Standard 0
Beispiel: show_inactive_time_limited_items=1
curl -i -X GET \
  'https://store.xsolla.com/api/v2/project/44056/items/virtual_items/group/{external_id}?limit=50&offset=0&locale=en&additional_fields%5B%5D=media_list&country=US&promo_code=WINTER2021&show_inactive_time_limited_items=1' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Antworten

Die Liste der Artikel aus der angegebenen Gruppe wurde erfolgreich empfangen.

Bodyapplication/json
has_moreboolean(Pagination_has-more)

Dient als Indikator dafür, dass weitere Seiten vorhanden sind.

Beispiel: true
itemsArray of objects
Beispiel: [{"attributes":[{"external_id":"stack_size","name":"Stack size","values":[{"value":"5"}]}],"can_be_bought":true,"description":"Big Rocket - description","groups":[{"external_id":"weapons","name":"weapons"}],"image_url":"https://popmedia.blob.core.windows.net/popyourself/male/outfit/male_armor_white_a-01.png","is_free":false,"limits":{"per_item":null,"per_user":{"available":3,"limit_exceeded_visibility":"show","recurrent_schedule":{"interval_type":"weekly","reset_next_date":1746057600},"total":5}},"name":"Big Rocket","periods":[{"date_from":"2020-08-11T10:00:00+03:00","date_until":"2020-08-11T20:00:00+03:00"}],"price":{"amount":"100.99","amount_without_discount":"100.99","currency":"USD"},"promotions":[{"bonus":[{"image_url":"https://cdn.xsolla.net/img/misc/images/2fc5c491a47413a8e8000447889093c2.png","name":"Xsolla Minigun","quantity":1,"sku":"com.xsolla.minigun_1","type":"virtual_good"}],"date_end":"2026-04-15T16:16:00+03:00","date_start":"2020-04-15T16:16:00+03:00","discount":{"percent":"50.00"},"name":"Bonus promotion"}],"sku":"com.xsolla.big_rocket_1","type":"virtual_good","virtual_item_type":"non_renewing_subscription","virtual_prices":[{"amount":100,"amount_without_discount":100,"description":"description","image_url":"http://image.png","is_default":true,"name":"SHOTGUN FOR TRUE RAIDERS","sku":"com.xsolla.vc_1","type":"virtual_currency"}]},{"attributes":[{"external_id":"stack_size","name":"Stack size","values":[{"value":"5"}]},{"external_id":"rating","name":"Rating","values":[{"value":"3.9"}]},{"external_id":"genre","name":"Genre","values":[{"value":"Strategy"},{"value":"Tactical"},"Turn-based"]}],"can_be_bought":true,"description":"description","groups":[{"external_id":"weapons","name":{"en":"weapons"}}],"image_url":"http://image.png","is_free":false,"limits":null,"name":"SHOTGUN FOR TRUE RAIDERS","periods":[],"price":{"amount":"101.0","amount_without_discount":"101.0","currency":"USD"},"promotions":[],"sku":"com.xsolla.shotgun_raider","type":"virtual_good","virtual_item_type":"non_renewing_subscription","virtual_prices":[{"amount":100,"amount_without_discount":100,"description":"description","image_url":"http://image.png","is_default":true,"name":"SHOTGUN FOR TRUE RAIDERS","sku":"com.xsolla.vc_1","type":"virtual_currency"},{"amount":200,"amount_without_discount":200,"description":"description","image_url":"http://image.png","is_default":false,"name":"SHOTGUN FOR TRUE RAIDERS","sku":"com.xsolla.vc_2","type":"virtual_currency"}]}]
Antwort
application/json
{
  "has_more": false,
  "items": [
    { … },
    { … }
  ]
}

Virtuellen Gegenstand anhand der SKU abrufenClient-side

Anfrage

Ruft einen virtuellen Gegenstand anhand der SKU ab, um einen Katalog zu erstellen.

Hinweis

Auf diesen Endpunkt kann man ohne Autorisierung zugreifen, er gibt generische Daten zurück. Liegt eine Autorisierung vor, ist die Antwort jedoch mit benutzerspezifischen Details (z. B. vorhandene Nutzerlimits und Werbeaktionen) angereichert und sorgt so für ein personalisiertes Ergebnis.
Sicherheit
XsollaLoginUserJWT
Pfad
project_idintegererforderlich

Projekt-ID. Dieser Parameter wird im Kundenportal neben dem Projektnamen angezeigt.

Beispiel: 44056
item_skustringerforderlich

Artikel-SKU.

Beispiel: booster_mega_1
Abfrage
localestring

Antwortsprache. Sprachcode bestehend aus zwei Kleinbuchstaben gemäß ISO 639-1.

Standard "en"
countrystring

Zweistelliger Ländercode in Großbuchstaben gemäß ISO 3166-1 Alpha-2. Weitere Informationen zu den von Xsolla unterstützten Ländern und dazu, wie das Land ermittelt wird, finden Sie in der Dokumentation.

Beispiel: country=US
show_inactive_time_limited_itemsinteger

Zeigt zeitlich begrenzte Artikel an, die nicht erhältlich sind. Der Gültigkeitszeitraum dieser Artikel hat noch nicht begonnen oder ist bereits vorüber.

Standard 0
Beispiel: show_inactive_time_limited_items=1
additional_fields[]Array of strings

Die Liste der zusätzlichen Felder. Diese Felder sind in der Antwort enthalten, sofern Sie diese in der Anfrage senden.

Elemente Enum"media_list""order""long_description""custom_attributes""item_order_in_group"
curl -i -X GET \
  'https://store.xsolla.com/api/v2/project/44056/items/virtual_items/sku/booster_mega_1?locale=en&country=US&show_inactive_time_limited_items=1&additional_fields%5B%5D=media_list' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Antworten

Der virtuelle Gegenstand wurde erfolgreich empfangen.

Bodyapplication/json
attributesArray of objects(Virtual-Items-Currency_client-attributes)

Liste der Attribute und ihrer Werte, die dem Artikel zugeordnet sind. Kann für die Katalogfilterung verwendet werden.

Standard []
Beispiel: {"value":{"external_id":"genre","name":"Жанр","values":[{"external_id":"genre_e3364991f92e751689a68b96598a5a5a84010b85","value":"Casual"},{"external_id":"genre_eba07bfd0f982940773cba3744d97264dd58acd7","value":"Strategy"},{"external_id":"genre_b8d0c6d8f0524c2b2d79ebb93aa3cd0e8b5199a8","value":"Mobile"}]}}
can_be_boughtboolean(Can_be_bought)

Sofern true, kann der Nutzer einen Artikel kaufen.

Beispiel: true
custom_attributesobject(json)(item-custom-attributes-response)

Ein JSON-Objekt mit Artikelattributen und ‑werten.

descriptionobject

Artikelbeschreibung.

Beispiel: "Big Rocket - description"
groupsArray of objects(items_client_groups_response)

Gruppen, zu denen der Artikel gehört.

Standard []
Beispiel: [{"external_id":"exclusive","name":"Exclusive"}]
image_urlstring

Bild-URL.

Beispiel: "https://popmedia.blob.core.windows.net/popyourself/male/outfit/male_armor_white_a-01.png"
is_freeboolean(value-is_free)

Ist true eingestellt, ist der Artikel kostenlos.

Standard false
Beispiel: false
item_idnumber

Artikel-ID.

limitsobject or null(client-item-limit-response)

Artikelbeschränkungen.

nameobject

Artikelname.

Beispiel: "Big Rocket"
periodsArray of objects(item-periods-response)

Artikelangebotszeitraum.

priceobject or null

Artikelpreise.

promotionsArray of objects(Catalog_item_promotions)

Auf bestimmte Artikel im Warenkorb angewandte Werbeaktionen. Das array wird in den folgenden Fällen zurückgegeben:

  • Für einen bestimmten Artikel ist eine Rabattaktion konfiguriert.

  • Ein Promocode mit der Einstellung Rabatt auf ausgewählte Artikel ist angewandt.

Werden keine Werbeaktionen auf Artikelebene angewandt, wird ein leeres Array zurückgegeben.

skustring

Eindeutige Artikel-ID. Die SKU darf nur lateinische Klein- und Großbuchstaben, Ziffern, Punkte, Bindestriche und Unterstriche enthalten.

Beispiel: "big_rocket"
typestring

Artikeltyp: virtual_good/virtual_currency/bundle.

Beispiel: "virtual_good"
virtual_item_typestring

Art des virtuellen Gegenstands.

Enum WertBeschreibung
consumable

Ein Artikel, der nach Gebrauch aus dem Inventar verschwindet (z. B. Munition).

non_consumable

Ein Artikel, der für unbegrenzte Zeit im Inventar verbleibt.

non_renewing_subscription

Zeitlich begrenzter Artikel, der den Zugang zu Diensten oder Inhalten für einen begrenzten Zeitraum ermöglicht.

Beispiel: "non-consumable"
virtual_pricesArray of objects

Virtuelle Preise.

vp_rewardsArray of objects(client-item-value-point-reward)

Wertpunktartikel-Belohnung.

Antwort
application/json
{
  "attributes": [
    { … }
  ],
  "can_be_bought": true,
  "custom_attributes": {
    "attr": "value",
    "purchased": 0
  },
  "description": {
    "en": "Honshu Boshin Wakizashi - Modern Tactical Samurai / Ninja Sword - Hand Forged 1060 Carbon Steel - Full Tang, Fully Functional, Battle Ready - Black TPR, Steel Guard and Pommel"
  },
  "groups": [
    { … }
  ],
  "image_url": "https://cdn.xsolla.net/img/misc/images/8ab44fe99038a56de01950ba4a971b77.png",
  "is_free": false,
  "item_id": 488833,
  "limits": {
    "per_item": null,
    "per_user": { … }
  },
  "name": {
    "en": "Sword Xsolla Skin"
  },
  "periods": [
    { … }
  ],
  "price": {
    "amount": "4.99",
    "amount_without_discount": "4.99",
    "currency": "USD"
  },
  "promotions": [],
  "sku": "com.xsolla.swords_1",
  "type": "virtual_good",
  "virtual_item_type": "non_consumable",
  "virtual_prices": [],
  "vp_rewards": []
}

Virtuelle Bezahlung

Operationen

Katalog

Operationen

Berechtigung

Operationen

Verwaltung

Operationen

Verwaltung

Operationen

Katalog

Operationen

Warenkorb (clientseitig)

Operationen

Warenkorb (serverseitig)

Operationen

Zahlung (clientseitig)

Operationen

Zahlung (serverseitig)

Operationen

Bestellung

Operationen

Kostenlose Artikel

Operationen

Verwaltung

Operationen

Verwaltung

Operationen

Webhooks

Operationen

Vorbestellungen

Operationen

Händler

Operationen

Katalog

Diese API ermöglicht es, jede Art von verkäuflichen oder bestimmten Artikeln zu erhalten.

Operationen

Gängige Regionen

Operationen

Verwaltung

Operationen