残高と請求

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

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

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

import requests

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

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

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

レスポンス

{
  "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上の保存されたカードに課金し、1ステップでクレジットを購入します。チェックアウトのリダイレクトや埋め込みの支払い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 <API-TOKEN>",
        "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 <API-TOKEN>",
    "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 <API-TOKEN>" \
  -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": "支払いが処理中です。支払いが確認されるとクレジットが追加されます。",
  "credits": 10000
}

クレジットは支払い確認後にStripeのWebhookによって発行され、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エラー；再試行する前に待機してください

開始する

機能