リクエスト制限 & 活用ガイド

APIリクエスト制限と正しい連携方式のご案内

リクエスト制限 & 活用ガイド

プラン別リクエスト制限

すべてのAPIキーには分あたり・月あたりのリクエスト制限があります:

全プラン共通でサーバー保護のため秒あたり10件の制限があります。

制限を超過するとHTTP 429 Too Many Requestsを返します。レスポンスヘッダーで現在の使用量を確認できます:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 42
X-RateLimit-Reset: 1706200000

正しい連携方式の選択

/v2/track — 単発照会

ユーザーが直接リクエストする1回限りの照会に使用してください:

• ECサイトで顧客が注文状況を確認する場合
• サポート担当者が追跡番号を照会する場合
• 一回限りの大量データ取り込み

呼び出すたびにリクエスト制限が消費されます。

/v2/webhooks/register + recurring: true — 継続モニタリング（推奨）

データベースを配送状況と同期する必要がある場合に使用してください:

• ステータス変更時に注文レコードを更新
• 配送完了時に顧客へ通知を送信
• リアルタイム配送状況ダッシュボードの構築

なぜWebhookがより効率的か：

Webhookサブスクリプションは追跡番号あたり1件のみ使用量がカウントされます。配送完了までステータスが何回変更されても追加コストはかかりません。一度登録すれば、WhereParcelが配送完了まで自動でモニタリングします。

// 一度登録すればステータス変更時に自動通知
await fetch('https://api.whereparcel.com/v2/webhooks/register', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${API_KEY}:${SECRET_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    trackingItems: [
      { carrier: 'jp.yamato', trackingNumber: '1234-5678-9012' }
    ],
    recurring: true,
    webhookEndpointId: 'your-endpoint-id',
  }),
});

制限超過時の対処

HTTP 429を受信したら、指数バックオフを使用してください:

async function trackWithRetry(carrier, trackingNumber, maxRetries = 3) {
  for (let attempt = 0; attempt <= maxRetries; attempt++) {
    const response = await fetch('https://api.whereparcel.com/v2/track', {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${API_KEY}:${SECRET_KEY}`,
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({
        trackingItems: [{ carrier, trackingNumber }],
      }),
    });

    if (response.status === 429) {
      const retryAfter = parseInt(response.headers.get('Retry-After') || '60');
      await new Promise(r => setTimeout(r, retryAfter * 1000));
      continue;
    }

    return await response.json();
  }
}

API使用量の節約ヒント

1. Webhookを使用 — ポーリングと比較して95%以上のリクエスト節約
2. 結果をキャッシュ — 配送完了した荷物はステータスが変わりません
3. バッチリクエストを活用 — /v2/trackは1回の呼び出しで最大5件照会可能
4. 配送完了した荷物の追跡を停止