whereparcel — WhereParcel 택배 추적 API의 공식 Node.js SDK를 출시했습니다.

npm install whereparcel

SDK가 필요한 이유

REST API는 어떤 HTTP 클라이언트로든 사용할 수 있지만, SDK를 통해 더 나은 개발 경험을 제공합니다:

  • 타입 안전한 응답 — 모든 API 응답에 대한 TypeScript 타입 정의
  • 제로 디펜던시 — 네이티브 fetch 사용 (Node.js 18+), 추가 의존성 없음
  • 간편한 인증 — API 키를 한 번만 설정하면 끝
  • 내장 에러 처리 — AuthenticationError, RateLimitError 등 타입화된 에러 클래스

빠른 시작

import { WhereParcel } from 'whereparcel';

const wp = new WhereParcel('your-api-key', 'your-secret-key');

// 단건 추적
const response = await wp.track([
  { carrier: 'us.usps', trackingNumber: '9400111899562537866361' },
]);

console.log(response.summary);
// { total: 1, success: 1, failed: 0, usageIncremented: 1 }

헤더 설정, JSON 파싱, URL 빌딩 없이 바로 사용 가능합니다.

다건 추적

한 번의 요청으로 최대 5건을 추적할 수 있습니다:

const response = await wp.track([
  { carrier: 'us.usps', trackingNumber: '9400111899562537866361' },
  { carrier: 'us.fedex', trackingNumber: '123456789012' },
  { carrier: 'kr.cj', trackingNumber: '1234567890', clientId: 'order-42' },
]);

console.log(response.summary);
// { total: 3, success: 2, failed: 1, usageIncremented: 2 }

택배사 조회

500개 이상의 지원 택배사를 프로그래밍 방식으로 탐색하세요:

// 전체 택배사
const carriers = await wp.getCarriers();

// 국가별 필터
const usCarriers = await wp.getCarriersByCountry('us');
// ['us.fedex', 'us.ups', 'us.usps', ...]

// 지역별 필터
const caCarriers = await wp.getCarriersByRegion('us', 'ca');

웹훅 지원

실시간 배송 알림을 설정하세요:

// 웹훅 엔드포인트 생성
const endpoint = await wp.createWebhookEndpoint({
  name: 'Production',
  url: 'https://myapp.com/webhooks/whereparcel',
});

// 반복 모니터링 등록
await wp.registerWebhook({
  trackingItems: [{ carrier: 'us.usps', trackingNumber: '...' }],
  recurring: true,
  webhookEndpointId: endpoint.endpointId,
});

에러 처리

타입화된 에러 클래스로 실패를 우아하게 처리하세요:

import { WhereParcel, AuthenticationError, RateLimitError } from 'whereparcel';

try {
  const result = await wp.track([{ carrier: 'us.usps', trackingNumber: '...' }]);
} catch (error) {
  if (error instanceof AuthenticationError) {
    console.error('API 인증 정보를 확인하세요');
  } else if (error instanceof RateLimitError) {
    console.error(`요청 제한. ${error.retryAfter}초 후 재시도`);
  }
}

향후 계획

현재 버전 0.1.0이며, 다음 기능을 준비 중입니다:

  • Python SDK — Python 개발자를 위한 SDK
  • 웹훅 서명 검증 — 웹훅 페이로드 검증 헬퍼
  • 자동 재시도 — 지수 백오프를 활용한 자동 재시도 로직

시작하기

npm install whereparcel