APIキーの取得
UTAGE管理画面からAPIキーを発行します。
- UTAGE管理画面にログイン
- 右上メニューの API設定 を開く
- 「追加する」をクリック
- 管理名称を入力し、API利用ポリシーに同意して「保存」
- 表示されたAPIキーをコピーして安全な場所に保存
APIキーは発行時に一度だけ表示されます。紛失した場合は新しいキーを発行してください。
認証方法
全てのAPIリクエストに Authorization ヘッダーでAPIキーを送信します。
Authorization: Bearer {api_key}
curlでのテスト
curl -X GET "https://api.utage-system.com/v1/funnels" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json"
401 Unauthorized エラーが返ります。
{
"error": {
"code": "unauthorized",
"message": "APIキーが無効です"
}
}
リクエストの文字コード
リクエストボディは UTF-8 でエンコードしてください。UTF-8 以外の場合は 400 invalid_encoding エラーが返ります。
セキュリティ
- APIキーはハッシュ化して保存されます。平文では保存されません
- 全てのAPIリクエストはログに記録されます
- 不要になったAPIキーは管理画面から無効化してください
レート制限
APIにはレート制限があります。
| 分間リクエスト数 | 日間リクエスト数 |
|---|
| 60回/分 | 10,000回/日 |
レスポンスヘッダー
全てのAPIレスポンスに、現在のレート制限状況を示すヘッダーが含まれます。
| ヘッダー | 説明 |
|---|
X-RateLimit-Limit | 分間の最大リクエスト数 |
X-RateLimit-Remaining | 残りのリクエスト数 |
X-RateLimit-Reset | 制限がリセットされるUNIXタイムスタンプ |
制限超過時
レート制限を超過すると 429 Too Many Requests が返ります。
{
"error": {
"code": "rate_limit_exceeded",
"message": "レート制限を超過しました"
}
}
X-RateLimit-Reset ヘッダーの時刻まで待ってからリトライしてください。
リソース作成上限
レート制限とは別に、データを作成するAPIには作成数の上限があります。超過すると 429 が返ります。
| エラーコード | 意味 |
|---|
monthly_limit_exceeded | 月間の作成上限を超過（details.retry_after に再試行可能日時） |
hourly_limit_exceeded | 1時間あたりの作成上限を超過 |
total_limit_exceeded | 累計の保有上限を超過 |
details.resource_type に対象のリソース種別が含まれます。
読者作成（POST /accounts/{account_id}/scenarios/{scenario_id}/readers および POST /accounts/{account_id}/line/friends/{friend_id}/readers）は、短時間に多数登録されるケースに対応するため分間レート制限の対象外です。代わりに上記のリソース作成上限（時間・月間）で制御されます。
認証不要のエンドポイント
以下の参照系エンドポイントは、APIキーなしで利用できます。
| エンドポイント | 内容 |
|---|
GET /element-types/funnel | ファネルページの要素タイプ一覧 |
GET /element-types/funnel/properties | ファネルページ要素のプロパティ定義 |
GET /element-types/mail | HTMLメール要素タイプ一覧 |
GET /element-types/mail/properties | HTMLメール要素のプロパティ定義 |
GET /message-types/line | LINEメッセージタイプ一覧 |
GET /message-condition-types | 配信条件タイプ一覧 |