残高と請求

ユーザー請求エンドポイントを使用して、チームのクレジット残高を読み取り、保存された支払い方法でトップアップを購入します。両方のエンドポイントは、APIキーでの認証が必要です。無効なキーは402を返します。

クレジット残高を確認する

GET /user/credits/infoは、認証されたチームのクレジット残高、ロットごとの内訳、アクティブなサブスクリプションの詳細、および使用が許可されているかどうかを返します。このエンドポイントを使用して、請求ウィジェット、使用状況ダッシュボード、または大規模なジョブを実行する前の事前チェックを強化します。 APIの詳細については、クレジット情報を取得を参照してください。

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>"

レスポンス

{
  "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
}

フィールド	説明
`credits`	すべての有効期限が切れていないロットにおける合計残りクレジット
`breakdown`	ロットごとの詳細：種類、割り当てられたユニットと残りのユニット、有効期限
`active_subscription`	現在のプラン（アクティブなものがない場合は`SUB_BASE`にフォールバック）
`allow_usage`	チームがクレジットを消費できるかどうか

breakdownの各ロットには、Subscription、Top-up、Manual、Setup、またはPendingのpurchase_kindがあります。

トップアップを購入する

POST /user/purchase-topupは、Stripeで保存されたカードに請求し、クレジットを一度に購入します。チェックアウトのリダイレクトや埋め込み支払いUIはありません。リクエストボディにクレジット金額を渡します：

{ "credits": 10000 }

フィールド	説明
`credits`	購入するクレジットの数

サポートされている値：10,000、20,000、80,000、および100,000。 APIの詳細については、トップアップを購入を参照してください。

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}'

要件

チームには、少なくとも1枚の保存されたカードを持つStripeの顧客が必要です。
チームごとに60秒ごとに1回の購入試行のみが許可されます。クールダウンに達した場合、レスポンスは429でRetry-Afterヘッダーが付きます。

レスポンス

200 — 支払い成功：

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

202 — 支払いはまだ処理中です。Stripeが支払いを確認するとクレジットが追加されます：

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

クレジットは支払い確認後にStripeのウェブフックによって発行され、HTTPレスポンスから直接ではありません。200を支払い成功と見なし、更新された残高を確認する必要がある場合はGET /user/credits/infoをポーリングしてください。

一般的なエラー

ステータス	エラー	発生条件
400	`missing_topup_selector`	`credits`が送信されていません
400	`invalid_credits`	クレジット金額が許可されたリストにありません
400	`no_stripe_customer`	チームにStripeの顧客がいません
400	`no_payment_method`	保存されたカードがありません
402	`payment_failed`	保存されたカードが請求を完了しませんでした
429	`purchase_topup_cooldown`	60秒以内に別の購入が試みられました
503	`payment_status_unknown`	曖昧なStripeエラー；再試行する前に待機してください

自動リフィル

残高が切れないように、スケジュールで残高を確認し、しきい値を下回った場合にトップアップを購入します。これは上記の2つのエンドポイントを使用し、スクリプトを実行できる場所ならどこでも動作します：cronジョブ、CIステップ、サーバーレス関数、または大規模なジョブの前のAIエージェント。

GET /user/credits/infoを呼び出し、creditsを読み取ります。
creditsがしきい値を下回った場合、サポートされている金額の1つでPOST /user/purchase-topupを呼び出します。
200または202の場合、停止します。Stripeが支払いを確認するとクレジットが到着するので、次のチェックで再度購入しないでください。

import os
import requests

API = "https://api.olostep.com"
HEADERS = {"Authorization": f"Bearer {os.environ['OLOSTEP_API_KEY']}"}
THRESHOLD = 2000      # 残高がこれを下回ったらリフィル
TOPUP_CREDITS = 10000  # 10000, 20000, 80000, または 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"残高OK: {credits} クレジット")

const API = "https://api.olostep.com"
const headers = {
  Authorization: `Bearer ${process.env.OLOSTEP_API_KEY}`,
  "Content-Type": "application/json",
}
const THRESHOLD = 2000 // 残高がこれを下回ったらリフィル
const TOPUP_CREDITS = 10000 // 10000, 20000, 80000, または 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(`残高OK: ${credits} クレジット`)
}

#!/usr/bin/env bash
# jqが必要です。残高がTHRESHOLDを下回ったらリフィル。
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 "残高OK: $credits クレジット"
fi

cronで毎時間チェックを実行するには：

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

チェック間の使用量をカバーするしきい値を選択してください。毎時間チェックを実行し、1時間あたり約1,000クレジットを使用する場合、2,000のしきい値はトップアップが処理中の間のバッファを残します。

各実行は保存されたカードに請求する可能性があります。チームごとに1つのリフィルジョブのみを実行し、429（purchase_topup_cooldown）および503（payment_status_unknown）を次のスケジュールされたチェックまで待機することで処理し、すぐに再試行しないでください。402（payment_failed）はカードが拒否されたことを意味します。次回の実行前にダッシュボードで更新してください。

Get Started

Features

Balance & Billing

クレジット残高を確認する

レスポンス

トップアップを購入する

要件

レスポンス

一般的なエラー

自動リフィル

​クレジット残高を確認する

​レスポンス

​トップアップを購入する

​要件

​レスポンス

​一般的なエラー

​自動リフィル

クレジット残高を確認する

レスポンス

トップアップを購入する

要件

レスポンス

一般的なエラー

自動リフィル