요청 한도 & 활용 가이드

API 요청 한도와 올바른 연동 방식 안내

요청 한도 & 활용 가이드

플랜별 요청 한도

모든 API 키에는 분당/월간 요청 한도가 적용됩니다:

모든 플랜에 서버 보호를 위한 초당 10건 제한이 적용됩니다.

한도를 초과하면 HTTP 429 Too Many Requests를 반환합니다. 응답 헤더에서 현재 사용량을 확인하세요:

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

올바른 연동 방식 선택

/v2/track — 단발성 조회

사용자가 직접 요청하는 1회성 조회에 사용하세요:

• 쇼핑몰에서 고객이 주문 상태를 확인할 때
• 고객센터 상담원이 송장번호를 조회할 때
• 일회성 대량 데이터 조회

호출할 때마다 요청 한도가 차감됩니다.

/v2/webhooks/register + recurring: true — 지속 모니터링 (권장)

DB를 배송 상태와 동기화해야 할 때 사용하세요:

• 상태 변경 시 주문 레코드 업데이트
• 배송 완료 시 고객에게 알림 발송
• 실시간 배송 현황 대시보드 구축

왜 웹훅이 더 효율적인가:

웹훅 구독은 송장번호당 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: 'kr.cj', trackingNumber: '123456789012' }
    ],
    recurring: true,
    webhookEndpointId: 'your-endpoint-id',
  }),
});

한도 초과 시 처리

HTTP 429를 받으면 지수 백오프(exponential backoff)를 사용하세요:

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. 웹훅을 사용하세요 — 폴링 대비 95% 이상 요청 절약
2. 결과를 캐싱하세요 — 배송 완료된 택배는 상태가 변하지 않습니다
3. 배치 요청을 활용하세요 — /v2/track은 1회 호출로 최대 5건 조회 가능
4. 배송 완료된 택배는 추적을 중단하세요