Node.js 애플리케이션에 택배 추적을 추가하는 건 복잡할 필요가 없습니다. 이 튜토리얼에서는 WhereParcel SDK를 사용해 설치부터 실시간 웹훅 알림까지 구현합니다.

사전 준비

  • Node.js 18+ (SDK는 네이티브 fetch 사용)
  • WhereParcel API 키 (무료 발급)

1단계: SDK 설치

npm install whereparcel

제로 디펜던시 — Node.js 내장 API만 사용합니다.

2단계: 클라이언트 초기화

import { WhereParcel } from 'whereparcel';

const wp = new WhereParcel(
  process.env.WHEREPARCEL_API_KEY!,
  process.env.WHEREPARCEL_SECRET_KEY!
);

API 키는 환경 변수에 저장하세요. 소스 코드에 하드코딩하지 마세요.

3단계: 택배 추적

가장 기본적인 사용법 — 택배사 코드와 운송장 번호로 단건 추적:

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

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

for (const result of response.results) {
  if (result.status === 'success') {
    console.log(`상태: ${result.data.deliveryStatus}`);
    // 상태: in_transit
  }
}

배송 상태 종류

WhereParcel은 모든 택배사의 상태를 다음 값으로 통일합니다:

상태설명
pending라벨 생성, 아직 픽업되지 않음
in_transit배송 중
out_for_delivery배달 출발
delivered배달 완료
failed배달 실패
returned반송
cancelled배송 취소
unknown상태 확인 불가

4단계: 다건 추적

이커머스 플랫폼처럼 대량 주문을 추적할 때는 벌크 API를 사용하세요 (요청당 최대 5건):

const response = await wp.track([
  { carrier: 'us.usps', trackingNumber: '9400111899562537866361' },
  { carrier: 'us.fedex', trackingNumber: '123456789012' },
  { carrier: 'us.ups', trackingNumber: '1Z999AA10123456784' },
]);

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

for (const result of response.results) {
  if (result.status === 'success') {
    console.log(`${result.carrier}: ${result.data.deliveryStatus}`);
  }
}

5단계: 택배사 코드 확인

어떤 택배사 코드를 사용해야 할지 모르겠다면:

// 전체 500+ 택배사
const allCarriers = await wp.getCarriers();

// 미국 택배사만
const usCarriers = await wp.getCarriersByCountry('us');
// ['us.fedex', 'us.ups', 'us.usps', ...]

// 지원 국가 목록
const countries = await wp.getCountries();
// ['kr', 'us', 'jp', 'cn', 'de', ...]

택배사 코드 형식: {국가}.{택배사} — 예: us.fedex, kr.cj, jp.yamato

6단계: 웹훅 설정

폴링 대신 WhereParcel이 상태 변경 시 알려주도록 설정하세요:

6a. 웹훅 엔드포인트 생성

const endpoint = await wp.createWebhookEndpoint({
  name: 'My App - Production',
  url: 'https://myapp.com/api/webhooks/tracking',
});

console.log(endpoint.endpointId); // 'endpoint_abc123'
console.log(endpoint.secret);     // 'whsec_...'

6b. 모니터링 등록

await wp.registerWebhook({
  trackingItems: [
    { carrier: 'us.usps', trackingNumber: '9400111899562537866361' },
    { carrier: 'us.fedex', trackingNumber: '123456789012' },
  ],
  recurring: true,
  webhookEndpointId: endpoint.endpointId,
});

recurring: true로 설정하면 배달 완료까지 상태 변경 시마다 알림을 받습니다.

6c. 웹훅 이벤트 처리

Express/Fastify/Next.js 앱에 웹훅 핸들러를 추가하세요:

app.post('/api/webhooks/tracking', (req, res) => {
  const { carrier, trackingNumber, deliveryStatus, events } = req.body;

  console.log(`${carrier} ${trackingNumber}: ${deliveryStatus}`);

  // DB 업데이트, 고객 알림 등

  res.status(200).json({ received: true });
});

에러 처리 모범 사례

항상 에러를 적절히 처리하세요:

import {
  WhereParcel,
  AuthenticationError,
  RateLimitError,
  NotFoundError,
} 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) {
    const retryAfter = error.retryAfter ?? 60;
    console.error(`요청 제한. ${retryAfter}초 후 재시도`);
  } else if (error instanceof NotFoundError) {
    console.error('택배사 또는 엔드포인트를 찾을 수 없습니다');
  }
}

전체 예제: Express 추적 서버

WhereParcel을 감싸는 간단한 Express 서버:

import express from 'express';
import { WhereParcel } from 'whereparcel';

const app = express();
const wp = new WhereParcel(
  process.env.WHEREPARCEL_API_KEY!,
  process.env.WHEREPARCEL_SECRET_KEY!
);

app.get('/track/:carrier/:trackingNumber', async (req, res) => {
  const { carrier, trackingNumber } = req.params;
  const result = await wp.track([{ carrier, trackingNumber }]);
  res.json(result);
});

app.listen(3000, () => console.log('추적 서버 실행 중 :3000'));

테스트:

curl http://localhost:3000/track/us.usps/9400111899562537866361

다음 단계