Software-as-a-Service Integrationsprozess

Zuletzt aktualisiert am 7. Mai 2026

Dieser Leitfaden beschreibt die technischen Interaktionen, die für die Anbindung Ihrer SaaS-Anwendung an den STACKIT Marketplace erforderlich sind. Er erläutert die Customer Journey vom ersten Abonnement bis zur endgültigen Freigabe und dem laufenden Zugriff.

Voraussetzungen

Stellen Sie vor Beginn der technischen Implementierung sicher, dass die folgenden technischen Anforderungen erfüllt sind:

Anbieter-Projekt: Sie haben Ihr Anbieter-Projekt eingerichtet und den API-Zugriff erfolgreich getestet.
Produktdaten: Ihr Produkt wurde in die zentrale Produktdatenbank des STACKIT Marketplace aufgenommen.
Registrierungs-URL: Sie verfügen über eine öffentlich zugängliche Landingpage, die bereit ist, von STACKIT weitergeleitete Kunden zu empfangen.

Integrationspfade für asynchrone vs. synchrone Bereitstellungsmethoden

Der Implementierungs-Workflow hängt davon ab, ob Ihre Produktbereitstellung vollständig automatisiert erfolgt oder manuelle Eingriffe erfordert.

Synchrone Auslieferung

Bei Standard-SaaS-Produkten wird eine automatische Bereitstellung erwartet. Der STACKIT Marketplace erwartet eine API-basierte Freigabe kurz nachdem der Kunde auf Ihre Landingpage weitergeleitet wurde.

Asynchrone Auslieferung

SaaS async. ist ideal für Produkte, die manuelle Konfigurationen erfordern, bevor der Kunde Zugriff erhält.

Manuelle Verwaltung: Sie können eine dedizierte Web-UI im Bereich „Abonnementverwaltung“ des STACKIT Marketplace nutzen, um Bestellungen manuell zu verwalten.
Erweiterte Timeouts: Während Standard-Abonnements ein Zeitfenster von einer Stunde für die Freigabe haben, ermöglichen SaaS-async.-Produkte ein Zeitfenster von bis zu 30 Tagen.
Kommunikation mit dem Kunden: Sie erhalten die Email-Adresse des Kunden. So können Sie die nötigen Details direkt abstimmen, wenn Sie die Services manuell einrichten.

Schritte der technischen Implementierung

Um Ihr Produkt auf dem STACKIT Marketplace live zu schalten, müssen Sie einen sicheren Handshake implementieren, der einen Kunden vom Abonnement-Kauf zu einem vollständig aktivierten Konto in Ihrer SaaS-Umgebung überführt.

Den Kunden-Redirect verarbeiten
Wenn ein Kunde ein Abonnement abschließt, sendet STACKIT eine GET-Anfrage an Ihre Registrierungs-URL. Sie müssen eine öffentliche Landingpage bereitstellen, die das x-stackit-marketplace-token extrahiert und den Benutzer auffordert, ein lokales, unabhängiges Konto zu erstellen.
Das JWT verifizieren
Das Token ist ein mit RS256 signiertes JWT. Sie müssen die öffentlichen Schlüssel von STACKIT herunterladen, die Signatur und den Ablauf (5 Minuten TTL) überprüfen und die subscriptionId aus dem Payload extrahieren.
Den Kunden auflösen
Tauschen Sie das verifizierte Token gegen vollständige Abonnement-Details aus, indem Sie den Endpunkt /resolve-customer aufrufen. Dieser liefert kritische Daten zurück, einschließlich des lifecycleState, der productId und des spezifischen pricingPlan, den der Kunde ausgewählt hat.
Das Abonnement freigeben
Rufen Sie den Endpunkt /approve auf, um zu bestätigen, dass das Abonnement auf Ihrer Seite aktiv ist.

Den Kunden-Redirect verarbeiten

Wenn ein STACKIT-Kunde Ihr Produkt abonniert, wird er über eine GET-Anfrage an Ihre registrierte Registrierungs-URL weitergeleitet. Diese Anfrage enthält ein eindeutiges Token, das zur Identifizierung des Abonnements dient.

Beispiel:

GET https://marketplace-app.eu/register?x-stackit–marketplace-token=[token]

Anforderungen an die Landingpage

Öffentlicher Zugriff: Die Registrierungs-URL muss öffentlich zugänglich sein.
Identitätserstellung: Sie müssen während der Registrierung alle erforderlichen Benutzerinformationen sammeln, um ein neues Konto auf Ihrer Seite zu erstellen.
Identitätsisolation: Sie können keine STACKIT-Benutzeridentitäten verwenden. Der Kunde muss eine neue, unabhängige Identität innerhalb Ihres Systems erstellen.
Token-Verifizierung: Sie müssen das x-stackit-marketplace-token verifizieren, um sicherzustellen, dass die Anfrage authentisch ist.

JWT-Verifizierung

Das x-stackit-marketplace-token ist ein kurzlebiges JSON Web Token (JWT), das mit RS256 signiert ist. Es enthält die subscriptionId, die für die nächsten Schritte erforderlich ist.

Wenn der STACKIT Marketplace zur Ihrer SaaS-Anwendung weiterleitet, wird der Parameter x-stackit-marketplace-token angehängt.

Header

Der Header enthält Metadaten über die Signatur.

{
    "alg": "RS256",
    "kid": "uuid",
    "typ": "JWT"
}

alg: Der Algorithmus, der zum Signieren des Tokens verwendet wurde (RSA mit SHA-256).
kid: Die Schlüssel-ID, die zur Identifizierung des korrekten öffentlichen Schlüssels für die Verifizierung verwendet wird.
typ: Der Typ des Tokens ist immer JWT.

Body

Der Body enthält den spezifischen Abonnement-Identifikator.

{
    "subscriptionId": "uuid",
    "iss": "https://keys.marketplace.stackit.cloud/v1/resolve-customer/keys.json",
    "exp": 1683081000,
    "iat": 1683077400
}

subscriptionId: Der eindeutige Identifikator für das Abonnement des Anbieters.
iss: Der Issuer-Claim, der angibt, wo die öffentlichen Schlüssel verfügbar sind.
exp: Der Ablauf-Zeitstempel (Unix-Epoche). Das Token ist nach der Ausstellung 5 Minuten lang gültig.
iat: Der Zeitstempel der Ausstellung („issued at“).

Schritte zur Verifizierung

Laden Sie die öffentlichen Schlüssel des STACKIT Marketplace herunter: https://keys.marketplace.stackit.cloud/v1/resolve-customer/keys.json.
Dekodieren Sie das JWT und lesen Sie die Schlüssel-ID aus dem Header.
Verwenden Sie die Schlüssel-ID, um den richtigen öffentlichen Schlüssel aus den heruntergeladenen Schlüsseln auszuwählen.
Verifizieren Sie die JWT-Signatur unter Verwendung der öffentlichen Schlüssel des STACKIT Marketplace.
Stellen Sie sicher, dass das JWT nicht abgelaufen ist.
Überprüfen Sie, ob der Aussteller (Issuer) mit dem Aussteller des STACKIT Marketplace übereinstimmt.
Stellen Sie sicher, dass die Abonnement-ID mit der vom Resolve Customer-Flow zurückgegebenen Abonnement-ID übereinstimmt.

Implementierungsbeispiele finden Sie für Python oder Go im Repository für STACKIT Marketplace-Codebeispiele.

Kunden auflösen

Der STACKIT Marketplace leitet den Kunden zur registrierten SaaS-Landingpage weiter und fügt ein x-stackit-marketplace-token hinzu. Der Token-Wert ist ein fünf Minuten gültiges JSON Web Token (JWT), das die Abonnement-ID des Anbieters enthält. Dieses Token kann über die Vendor API gegen Abonnement-Informationen eingetauscht werden.

Endpunkt:

POST /v1/vendors/projects/[projectId]/resolve-customer

Request-Body:

{
  "token": "[token]"
}

Response-Body:

{
  "lifecycleState": "SUBSCRIPTION_PENDING",
  "product": {
    "deliveryMethod": "SAAS",
    "lifecycleState": "PRODUCT_LIVE",
    "priceType": "CONTRACT",
    "pricingPlan": "Test Plan",
    "productId": "2ea4b536-07c8-479e-a7a7-41ff724e053f",
    "productName": "Test Product Name",
    "vendorName": "STACKIT",
    "vendorPlanId": "custom-plan-id-123", // vom Anbieter bereitgestellter Identifikator; optional
    "vendorProductId": "vendor-custom-id", // vom Anbieter bereitgestellter Identifikator; optional
    "vendorWebsiteUrl": "https://example.com"
  },
  "projectId": "c5fedcab-920d-40cd-a06f-e7443db8e7f7",
  "subscriptionId": "e93750b2-3d5c-496e-844d-67c947e34c67"
}

Implementierungsbeispiele finden Sie für Go und Python im Repository für STACKIT Marketplace-Codebeispiele.

Das Abonnement freigeben

Die Freigabe des Abonnements ist der letzte Schritt. Damit beginnt die Abrechnung für den Kunden und die Aktivierung des Dienstes wird bestätigt.

Kritisches Timing & Abrechnung:

Standard-TTL: Für Standard-SaaS haben ausstehende Abonnements eine Time-to-Live (TTL) von einer Stunde. Wenn die Freigabe nicht innerhalb dieses Zeitfensters erfolgt, schlägt die Anfrage fehl.
Asynchrone TTL: Für SaaS-async.-Produkte wird dieses Fenster auf bis zu 30 Tage erweitert.
Abrechnungs-Trigger: Die Abrechnung beginnt erst, wenn Sie den Freigabe-Endpunkt erfolgreich aufgerufen haben.