> ## Documentation Index
> Fetch the complete documentation index at: https://docs.olostep.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 残高と請求

> クレジット残高を確認し、プログラムでトップアップを購入します。

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

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

`GET /user/credits/info`は、認証されたチームのクレジット残高、ロットごとの内訳、アクティブなサブスクリプションの詳細、および使用が許可されているかどうかを返します。

このエンドポイントを使用して、請求ウィジェット、使用状況ダッシュボード、または大規模なジョブを実行する前の事前チェックを強化します。

APIの詳細については、[クレジット情報を取得する](/api-reference/billing/credits-info)を参照してください。

<CodeGroup>
  ```python Python theme={null}
  import requests

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

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

  ```bash cURL theme={null}
  curl -s "https://api.olostep.com/user/credits/info" \
    -H "Authorization: Bearer <API-TOKEN>"
  ```
</CodeGroup>

### レスポンス

```json theme={null}
{
  "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はありません。

リクエストボディにクレジット量を渡します：

```json theme={null}
{ "credits": 10000 }
```

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

サポートされる値：**10,000**、**20,000**、**80,000**、および**100,000**。

APIの詳細については、[トップアップを購入する](/api-reference/billing/purchase-topup)を参照してください。

<CodeGroup>
  ```python Python theme={null}
  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())
  ```

  ```js Node theme={null}
  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())
  ```

  ```bash cURL theme={null}
  curl -s -X POST "https://api.olostep.com/user/purchase-topup" \
    -H "Authorization: Bearer <API-TOKEN>" \
    -H "Content-Type: application/json" \
    -d '{"credits": 10000}'
  ```
</CodeGroup>

### 要件

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

### レスポンス

**200** — 支払いが成功しました：

```json theme={null}
{
  "success": true,
  "payment_intent_id": "pi_xxx",
  "credits": 10000
}
```

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

```json theme={null}
{
  "success": true,
  "status": "processing",
  "payment_intent_id": "pi_xxx",
  "message": "支払いが処理中です。支払いが確認されるとクレジットが追加されます。",
  "credits": 10000
}
```

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

### 一般的なエラー

| ステータス | エラー                       | 発生条件                           |
| ----- | ------------------------- | ------------------------------ |
| 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エラー；再試行する前に待機してください |