Bestellungen anlegen, Rechnungen freigeben und bezahlen und den Workspace einrichten.

API-Referenz

Abwicklung

Wann Bestellungen und Rechnungen die manuelle Freigabe überspringen können, und der Plan des Workspace.

Mehr zu dieser Ressource

Die Autonomie-Einstellungen steuern, wann POs und Rechnungen die manuelle Freigabe überspringen; der Plan steuert, worauf der Workspace Anspruch hat. Der Plan selbst ist über die API nur lesbar - Stripe ist das maßgebliche System für Pleaxy-Abonnements, und der Anspruch wird ausschließlich aus signierten Webhooks von Stripe geschrieben.

Endpunkte

GET…/settlement/autonomy
PATCH…/settlement/autonomy
GET…/settlement/billing

Autonomie-Einstellungen abrufen

Gibt die Einstellungen zur automatischen Freigabe des Workspace zurück.

GET/v1/workspaces/{regionId}/settlement/autonomy

Rückgabe

200 OK mit dem in der Antwort gezeigten Objekt.

Weitere Details

Gibt die Einstellungen des Workspace zur autonomen Abwicklung zurück, standardmäßig { enabled: false, maxAutoApproveAmount: 300, approvalThreshold: 25000 }, wenn sie nie konfiguriert wurden.

Antwortfelder

maxAutoApproveAmountnumber
Bei aktivierter Autonomie wird eine PO oder Rechnung bis einschließlich dieses Betrags (in der Währung der Region) als Pleaxy Autonomy ohne Zutun einer Person freigegeben, es sei denn, ein bedingter oder ein Schritt für hohe Beträge greift, eine PO hat ein Ausgabenlimit überschritten, oder die Rechnung kann nicht automatisch freigegeben werden (das kann nur eine Rechnung, die gegen eine ausgestellte AWS-Rechnung abgeglichen wurde, nie eine von einem Käufer erfasste oder eine in einer anderen Währung). Bei einer Rechnung über der Abgleichstoleranz von 3% begrenzt der Wert stattdessen die Differenz.
approvalThresholdnumber
Der Schwellenwert für hohe Beträge: Als highValueOnly markierte Freigabeschritte laufen nur bei Beträgen darüber, und die Autonomie gibt nie ein Dokument frei, für das ein solcher Schritt gilt. Gilt unabhängig davon, ob die Autonomie aktiviert ist.

Fehler

401 Unauthorized - Es wurden keine Zugangsdaten übermittelt, oder der Bearer-Token bzw. der X-Api-Key-Wert fehlt, ist ungültig, abgelaufen oder widerrufen.
403 Forbidden - Der Bearer-Token oder API-Schlüssel des Aufrufers gewährt keinen Zugriff auf diesen Workspace (regionId) oder hat nicht die erforderliche Rolle.

GET /v1/workspaces/{regionId}/settlement/autonomy

Anfrage

curl "$PLEAXY_API_BASE_URL/v1/workspaces/{regionId}/settlement/autonomy" \
  -H "X-Api-Key: $PLEAXY_API_KEY"

Antwort · 200 OK

{
   "enabled": boolean,
   "maxAutoApproveAmount": number,
   "approvalThreshold": number
}

Autonomie-Einstellungen aktualisieren

Aktualisiert die Einstellungen zur automatischen Freigabe des Workspace.

PATCH/v1/workspaces/{regionId}/settlement/autonomy

Body

enabledboolean
Autonome Freigabe aktivieren oder deaktivieren.
maxAutoApproveAmountnumber
Neue Obergrenze für die automatische Freigabe.
approvalThresholdnumber
Neuer Schwellenwert für hohe Beträge.

Rückgabe

200 OK mit dem in der Antwort gezeigten Objekt.

Weitere Details

Aktualisiert eine oder mehrere Autonomie-Einstellungen. Das Aktivieren der Autonomie setzt voraus, dass der Plan des Workspace Autonomous oder Enterprise ist.

Nur angemeldete Sitzung: Die Autonomie entscheidet, ob überhaupt eine Person freigibt, daher erhält ein API-Schlüssel unabhängig von seiner Einkaufsrolle 403. Zum Lesen der Einstellungen genügt ein Käufer-API-Schlüssel.

Fehler

400 Bad Request - enabled: true wurde gesendet, aber der Plan der Region ist Free oder Managed (Autonomie erfordert Autonomous oder höher).
403 Forbidden - Der Aufrufer ist keine angemeldete Person (zum Beispiel ein API-Schlüssel): "This action requires a logged-in user session, not an API key". Es wird nichts gespeichert.
401 Unauthorized - Es wurden keine Zugangsdaten übermittelt, oder der Bearer-Token bzw. der X-Api-Key-Wert fehlt, ist ungültig, abgelaufen oder widerrufen.
403 Forbidden - Der Bearer-Token oder API-Schlüssel des Aufrufers gewährt keinen Zugriff auf diesen Workspace (regionId) oder hat nicht die erforderliche Rolle.

PATCH /v1/workspaces/{regionId}/settlement/autonomy

Anfrage

curl -X PATCH "$PLEAXY_API_BASE_URL/v1/workspaces/{regionId}/settlement/autonomy" \
  -H "X-Api-Key: $PLEAXY_API_KEY" \
  -H "Content-Type: application/json" \
  -d @body.json

body.json

{
   "enabled": boolean,
   "maxAutoApproveAmount": number,
   "approvalThreshold": number
}

Antwort · 200 OK

{
   "enabled": boolean,
   "maxAutoApproveAmount": number,
   "approvalThreshold": number
}

Abrechnung abrufen

Gibt den Plan und das Abonnement des Workspace zurück.

GET/v1/workspaces/{regionId}/settlement/billing

Rückgabe

200 OK mit dem in der Antwort gezeigten Objekt.

Weitere Details

Gibt den Plan des Workspace und den Stand seines Pleaxy-Abonnements zurück. Der Plan ist ein Anspruchs-Cache, der ausschließlich aus signierten Stripe-Webhooks geschrieben wird (oder, bei Enterprise-Verträgen, vom Pleaxy-Betrieb) - es gibt keine API, um ihn zu ändern, und keine Pleaxy-API akzeptiert je einen Plan von einem Aufrufer. Änderungen per Self-Service laufen über das von Stripe gehostete Checkout und das Stripe Customer Portal, deren URLs von den beiden Sitzungsendpunkten unter diesem Pfad ausgegeben werden; beide erfordern eine Sitzung einer Person, daher können API-Schlüssel kein Abonnement starten oder ändern. Stripe-Kennungen sind bewusst nicht Teil dieser Antwort.

Antwortfelder

billingEnabledboolean
false, wenn die Umgebung keine Stripe-Konfiguration hat; die Sitzungsendpunkte geben dann 503 zurück.
planstring
Der Anspruchsplan, gegen den Limits durchgesetzt werden.
managedBystring
"platform" für einen vom Pleaxy-Betrieb zugewiesenen Enterprise-Vertrag - keine Änderungen per Self-Service; sonst "self-serve".
hasBillingAccountboolean
Für diesen Workspace gibt es einen Stripe Customer, daher ist das Customer Portal verfügbar.
subscriptionStatusstring
Der Abonnementstatus von Stripe, wörtlich übernommen. Fehlt, wenn der Workspace nie ein Abonnement hatte.
currentPeriodEndstring
ISO-8601-Verlängerungsdatum oder das Datum, an dem der Zugang endet, wenn cancelAtPeriodEnd true ist.
cancelAtPeriodEndboolean
Das Abonnement ist so eingestellt, dass es zu currentPeriodEnd endet statt sich zu verlängern.
pastDueSincestring
ISO-8601-Zeitstempel der fehlgeschlagenen Zahlung. Der bezahlte Plan bleibt für die Dauer des Mahnzeitraums von Stripe erhalten.
availablePlansarray
Die buchbaren Pläne mit ihren aktuellen Preisen, aus Stripe gelesen: der Monatspreis der ersten Region, der Jahrespreis, sofern einer konfiguriert ist, und die Preisstufe jeder weiteren Region. Leer, wenn die Abrechnung deaktiviert ist oder die Stripe-Preise vorübergehend nicht verfügbar sind.
*PriceLabel, *Pricestring, object
Jeder Preis zweimal: eine englische Bezeichnung (etwa ein Monatspreis gefolgt von "/mo") und derselbe Preis als Zahlen - { amount, currency, interval }, amount in der kleinsten Einheit der Währung (Cent) und currency in Kleinbuchstaben, wie Stripe sie liefert -, um ihn in Ihrer eigenen Sprache zu formatieren. additionalRegionPrices enthält ein { fromRegion, toRegion, price } pro Bezeichnung (toRegion null: und jede weitere Region).
currentPrice, currentTotalobject
Der Preis der ersten Region des aktuellen Abonnements und was das Unternehmen pro Intervall für alle seine Käuferregionen (buyerRegionCount) zahlt, mit ihren Bezeichnungen. Nur wenn die Abrechnung aktiviert ist und ein Preis hinterlegt ist.

Fehler

401 Unauthorized - Es wurden keine Zugangsdaten übermittelt, oder der Bearer-Token bzw. der X-Api-Key-Wert fehlt, ist ungültig, abgelaufen oder widerrufen.
403 Forbidden - Der Bearer-Token oder API-Schlüssel des Aufrufers gewährt keinen Zugriff auf diesen Workspace (regionId) oder hat nicht die erforderliche Rolle.

GET /v1/workspaces/{regionId}/settlement/billing

Anfrage

curl "$PLEAXY_API_BASE_URL/v1/workspaces/{regionId}/settlement/billing" \
  -H "X-Api-Key: $PLEAXY_API_KEY"

Antwort · 200 OK

{
   "billingEnabled": boolean,
   "plan": "assisted" | "managed" | "autonomous" | "enterprise",
   "managedBy": "self-serve" | "platform",
   "hasBillingAccount": boolean,
   "subscriptionStatus": "trialing" | "active" | "past_due" | "unpaid" | "canceled" | "incomplete" | "incomplete_expired" | "paused",
   "currentPeriodEnd": "string",
   "cancelAtPeriodEnd": boolean,
   "pastDueSince": "string",
   "buyerRegionCount": number,
   "interval": "month" | "year",
   "availablePlans": [
      {
         "plan": "managed" | "autonomous",
         "monthlyPriceLabel": "string",
         "monthlyPrice": { "amount": number, "currency": "string", "interval": "month" },
         "yearlyPriceLabel": "string",
         "yearlyPrice": { "amount": number, "currency": "string", "interval": "year" },
         "additionalRegionPriceLabels": [ "string" ],
         "additionalRegionPrices": [ { "fromRegion": number, "toRegion": number | null, "price": { "amount": number, "currency": "string", "interval": "month" | "year" } } ]
      }
   ],
   "currentPriceLabel": "string",
   "currentPrice": { "amount": number, "currency": "string", "interval": "month" | "year" },
   "currentTotalLabel": "string",
   "currentTotal": { "amount": number, "currency": "string", "interval": "month" | "year" }
}