Guthaben & Abrechnung

Nutze die Endpunkte der Benutzerabrechnung, um das Guthaben deines Teams abzurufen und Aufladungen mit einer gespeicherten Zahlungsmethode zu kaufen. Beide Endpunkte erfordern eine Authentifizierung mit deinem API-Schlüssel. Ungültige Schlüssel geben 402 zurück.

Guthaben überprüfen

GET /user/credits/info gibt das Guthaben des authentifizierten Teams, eine Aufschlüsselung pro Los, Details zum aktiven Abonnement und ob die Nutzung erlaubt ist, zurück. Nutze diesen Endpunkt, um Abrechnungs-Widgets, Nutzungs-Dashboards oder Vorabprüfungen vor großen Aufträgen zu betreiben. Für API-Details siehe Guthabeninformationen abrufen.

import requests

response = requests.get(
    "https://api.olostep.com/user/credits/info",
    headers={"Authorization": "Bearer <YOUR_API_KEY>"},
)
print(response.json())

const res = await fetch("https://api.olostep.com/user/credits/info", {
  headers: { Authorization: "Bearer <YOUR_API_KEY>" },
})
console.log(await res.json())

curl -s "https://api.olostep.com/user/credits/info" \
  -H "Authorization: Bearer <YOUR_API_KEY>"

Antwort

{
  "credits": 12500,
  "breakdown": [
    {
      "purchase_kind": "Subscription",
      "allocated_units": 10000,
      "remaining_units": 8500,
      "expiry_date": 1735689600
    },
    {
      "purchase_kind": "Top-up",
      "allocated_units": 5000,
      "remaining_units": 4000,
      "expiry_date": 1743465600
    }
  ],
  "active_subscription": {
    "id": "SUB_PRO",
    "display_name": "Pro",
    "credits": 10000,
    "created_at": 1704067200
  },
  "allow_usage": true
}

Feld	Beschreibung
`credits`	Gesamtes verbleibendes Guthaben über alle nicht abgelaufenen Lose hinweg
`breakdown`	Detail pro Los: Typ, zugewiesene und verbleibende Einheiten, Ablaufdatum
`active_subscription`	Aktueller Plan (fällt auf `SUB_BASE` zurück, wenn keiner aktiv ist)
`allow_usage`	Ob das Team weiterhin Guthaben verbrauchen kann

Jedes Los in breakdown hat eine purchase_kind von Subscription, Top-up, Manual, Setup oder Pending.

Eine Aufladung kaufen

POST /user/purchase-topup belastet eine gespeicherte Karte bei Stripe und kauft Guthaben in einem Schritt. Es gibt keine Checkout-Weiterleitung oder eingebettete Zahlungsoberfläche. Gib die Guthabenmenge im Anfragetext an:

{ "credits": 10000 }

Feld	Beschreibung
`credits`	Anzahl der zu kaufenden Guthaben

Unterstützte Werte: 10.000, 20.000, 80.000 und 100.000. Für API-Details siehe Aufladung kaufen.

import requests

response = requests.post(
    "https://api.olostep.com/user/purchase-topup",
    headers={
        "Authorization": "Bearer <YOUR_API_KEY>",
        "Content-Type": "application/json",
    },
    json={"credits": 10000},
)
print(response.status_code)
print(response.json())

const res = await fetch("https://api.olostep.com/user/purchase-topup", {
  method: "POST",
  headers: {
    Authorization: "Bearer <YOUR_API_KEY>",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ credits: 10000 }),
})
console.log(res.status)
console.log(await res.json())

curl -s -X POST "https://api.olostep.com/user/purchase-topup" \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{"credits": 10000}'

Anforderungen

Das Team muss einen Stripe-Kunden mit mindestens einer gespeicherten Karte haben.
Pro Team ist nur ein Kaufversuch alle 60 Sekunden erlaubt. Wenn du die Abkühlzeit erreichst, ist die Antwort 429 mit einem Retry-After-Header.

Antworten

200 — Zahlung erfolgreich:

{
  "success": true,
  "payment_intent_id": "pi_xxx",
  "credits": 10000
}

202 — Zahlung wird noch verarbeitet. Guthaben wird hinzugefügt, sobald Stripe die Zahlung bestätigt:

{
  "success": true,
  "status": "processing",
  "payment_intent_id": "pi_xxx",
  "message": "Payment is processing. Credits will be added once the payment is confirmed.",
  "credits": 10000
}

Guthaben wird durch den Stripe-Webhook nach Zahlungsbestätigung ausgestellt, nicht direkt von der HTTP-Antwort. Behandle 200 als Zahlungserfolg; frage GET /user/credits/info ab, wenn du das aktualisierte Guthaben bestätigen musst.

Häufige Fehler

Status	Fehler	Wann
400	`missing_topup_selector`	`credits` wurde nicht gesendet
400	`invalid_credits`	Guthabenmenge ist nicht in der erlaubten Liste
400	`no_stripe_customer`	Team hat keinen Stripe-Kunden
400	`no_payment_method`	Keine gespeicherte Karte vorhanden
402	`payment_failed`	Keine gespeicherte Karte hat die Belastung abgeschlossen
429	`purchase_topup_cooldown`	Ein weiterer Kauf wurde innerhalb von 60 Sekunden versucht
503	`payment_status_unknown`	Mehrdeutiger Stripe-Fehler; warte, bevor du es erneut versuchst

Automatische Nachfüllungen

Um zu verhindern, dass dein Guthaben ausgeht, überprüfe es regelmäßig und kaufe eine Aufladung, wenn es unter einen Schwellenwert fällt. Dies nutzt die beiden oben genannten Endpunkte und funktioniert überall, wo du ein Skript ausführen kannst: ein Cron-Job, ein CI-Schritt, eine serverlose Funktion oder ein KI-Agent vor einem großen Auftrag.

Rufe GET /user/credits/info auf und lese credits.
Wenn credits unter deinem Schwellenwert liegt, rufe POST /user/purchase-topup mit einem der unterstützten Beträge auf.
Bei 200 oder 202 stoppe. Guthaben wird hinzugefügt, sobald Stripe die Zahlung bestätigt, also kaufe nicht erneut beim nächsten Check, bis das Guthaben aktualisiert wurde.

import os
import requests

API = "https://api.olostep.com"
HEADERS = {"Authorization": f"Bearer {os.environ['OLOSTEP_API_KEY']}"}
THRESHOLD = 2000      # nachfüllen, wenn Guthaben unter diesen Wert fällt
TOPUP_CREDITS = 10000  # 10000, 20000, 80000 oder 100000

credits = requests.get(f"{API}/user/credits/info", headers=HEADERS).json()["credits"]

if credits < THRESHOLD:
    res = requests.post(
        f"{API}/user/purchase-topup",
        headers=HEADERS,
        json={"credits": TOPUP_CREDITS},
    )
    print(res.status_code, res.json())
else:
    print(f"Guthaben OK: {credits} credits")

const API = "https://api.olostep.com"
const headers = {
  Authorization: `Bearer ${process.env.OLOSTEP_API_KEY}`,
  "Content-Type": "application/json",
}
const THRESHOLD = 2000 // nachfüllen, wenn Guthaben unter diesen Wert fällt
const TOPUP_CREDITS = 10000 // 10000, 20000, 80000 oder 100000

const { credits } = await (await fetch(`${API}/user/credits/info`, { headers })).json()

if (credits < THRESHOLD) {
  const res = await fetch(`${API}/user/purchase-topup`, {
    method: "POST",
    headers,
    body: JSON.stringify({ credits: TOPUP_CREDITS }),
  })
  console.log(res.status, await res.json())
} else {
  console.log(`Guthaben OK: ${credits} credits`)
}

#!/usr/bin/env bash
# Benötigt jq. Nachfüllen, wenn Guthaben unter THRESHOLD fällt.
THRESHOLD=2000
TOPUP_CREDITS=10000

credits=$(curl -s "https://api.olostep.com/user/credits/info" \
  -H "Authorization: Bearer $OLOSTEP_API_KEY" | jq '.credits')

if [ "$credits" -lt "$THRESHOLD" ]; then
  curl -s -X POST "https://api.olostep.com/user/purchase-topup" \
    -H "Authorization: Bearer $OLOSTEP_API_KEY" \
    -H "Content-Type: application/json" \
    -d "{\"credits\": $TOPUP_CREDITS}"
else
  echo "Guthaben OK: $credits credits"
fi

Um den Check stündlich mit Cron auszuführen:

0 * * * * OLOSTEP_API_KEY=your_key /usr/bin/python3 /path/to/refill.py

Wähle einen Schwellenwert, der deinen Verbrauch zwischen den Checks abdeckt. Wenn du den Check stündlich ausführst und etwa 1.000 Guthaben pro Stunde verbrauchst, lässt ein Schwellenwert von 2.000 einen Puffer, während eine Aufladung verarbeitet wird.

Jeder Lauf kann deine gespeicherte Karte belasten. Führe nur einen Nachfülljob pro Team aus und behandle 429 (purchase_topup_cooldown) und 503 (payment_status_unknown), indem du auf den nächsten geplanten Check wartest, anstatt sofort erneut zu versuchen. Ein 402 (payment_failed) bedeutet, dass deine Karte abgelehnt wurde; aktualisiere sie im Dashboard vor dem nächsten Lauf.

Loslegen

Funktionen

Kontostand & Abrechnung

Guthaben überprüfen

Antwort

Eine Aufladung kaufen

Anforderungen

Antworten

Häufige Fehler

Automatische Nachfüllungen

​Guthaben überprüfen

​Antwort

​Eine Aufladung kaufen

​Anforderungen

​Antworten

​Häufige Fehler

​Automatische Nachfüllungen

Guthaben überprüfen

Antwort

Eine Aufladung kaufen

Anforderungen

Antworten

Häufige Fehler

Automatische Nachfüllungen