POST /api/v1/links/bulk
itemsまたはlinks配列を最大100件まで送信します。
links:bulk:create
APIキーには一括作成スコープが必要です。
Idempotency-Key
同じバッチの再試行では同じUUIDを使い、重複作成を防ぎます。
コピーして調整
curl・JavaScript・Pythonの例
APIキーと遷移先を置き換えます。各項目は単一作成APIと同種のフィールドに対応します。
curl -X POST https://tt.vg/api/v1/links/bulk \
-H "Authorization: Bearer ttvg_your_api_key" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000" \
-d '{
"items": [
{ "destinationUrl": "https://example.com/a", "description": "Campaign A" },
{ "destinationUrl": "https://example.com/b", "key": "campaign-b" }
]
}'レスポンス処理
項目ごとに結果を処理
1つのバッチに成功リンクとエラーが混在します。返却されたindexを入力データと一緒に保存してください。
全項目が成功
itemsとsummaryを読み取ります。errorsは空です。
部分成功
成功項目を保存し、失敗した入力だけを確認・再試行します。
リクエストまたは権限エラー
入力、認証、メール確認、スコープを修正してから再試行します。
クォータまたはレート制限
バッチを停止して待機し、Retry-Afterがある場合は従います。
一時的なサーバー障害
指数バックオフと同じIdempotency-Keyで再試行します。
クォータとバッチ上限
1リクエスト最大100件です。成功項目ごとにプランの日次links:create枠を1件消費し、失敗項目は成功数に入りません。
Webhookで後続処理
link.created、link.updated、link.clickedを購読できます。署名付きで非同期配信され、APIを止めずに再試行されます。
よくある質問
一括APIの質問
一括作成は全件成功か全件失敗ですか？
いいえ。有効な項目が成功し、別の項目がindex付きエラーになる場合があり、混在時はHTTP 207です。
途中でクォータが尽きるとどうなりますか？
現在以降の項目に429エラーが返り、処理が停止します。
再試行の重複を防ぐ方法は？
ランダムなIdempotency-Keyを送り、同一バッチの再試行にだけ同じ値を使います。