Node.js SDK로 택배 조회 시작하기

REST API를 직접 호출하는 대신 공식 Node.js SDK를 사용하면 인증 헤더 작성, HTTP 에러 처리, 타입 정의를 직접 만들 필요가 없습니다. npm install deliveryapi 한 줄로 시작해보세요.

1. 설치

Node.js 18 이상에서 동작하며 ESM과 CommonJS를 모두 지원합니다.

npm install deliveryapi

2. 환경 변수 설정

API 키는 절대 코드에 직접 작성하지 마세요. .env 파일이나 배포 환경의 환경 변수에 저장하세요.

# .env
DELIVERY_API_KEY=pk_live_xxxxxxxxxxxxxxxx
DELIVERY_SECRET_KEY=sk_live_xxxxxxxxxxxxxxxx

3. 클라이언트 초기화

앱 시작 시 DeliveryAPIClient를 한 번 생성하여 재사용합니다.

import { DeliveryAPIClient } from 'deliveryapi';

const client = new DeliveryAPIClient({
  apiKey: process.env.DELIVERY_API_KEY,
  secretKey: process.env.DELIVERY_SECRET_KEY,
});

4. 택배 조회

client.tracking.trace()는 배열을 받는 하나의 엔드포인트입니다. 1건을 조회할 때도 배열에 넣어서 전달합니다.

const { results } = await client.tracking.trace({
  items: [
    {
      courierCode: 'cj',
      trackingNumber: '1234567890',
      clientId: 'order_001',  // 내 주문번호 (선택)
    },
  ],
});

const result = results[0];

if (result.success) {
  const { deliveryStatus, deliveryStatusText, progresses } = result.data;
  console.log('상태:', deliveryStatusText);        // "배송중"
  console.log('최근 위치:', progresses[0].location); // "서울 허브"
} else {
  console.error('조회 실패:', result.error.code);  // "NOT_FOUND"
}

응답의 result.success로 건별 성공 여부를 반드시 확인하세요. 일부 조회가 실패해도 전체 요청은 실패하지 않습니다.

5. 여러 건 동시 조회

배열에 여러 항목을 넣으면 한 번의 API 호출로 처리됩니다. 주문 번호를 clientId로 매핑하면 응답에서 쉽게 식별할 수 있습니다.

// 여러 택배를 한 번에 조회
const { results, summary } = await client.tracking.trace({
  items: [
    { courierCode: 'cj',    trackingNumber: '1111111111', clientId: 'order_001' },
    { courierCode: 'lotte', trackingNumber: '2222222222', clientId: 'order_002' },
    { courierCode: 'hanjin',trackingNumber: '3333333333', clientId: 'order_003' },
  ],
});

console.log(`전체: ${summary.total}, 성공: ${summary.successful}, 실패: ${summary.failed}`);

for (const result of results) {
  if (result.success) {
    console.log(`[${result.clientId}] ${result.data.deliveryStatusText}`);
  }
}

6. 배송 상태 코드 활용 (TypeScript)

SDK에 포함된 CourierDeliveryStatus enum을 사용하면 문자열 비교 없이 타입 안전하게 분기할 수 있습니다.

import { CourierDeliveryStatus } from 'deliveryapi';

const result = results[0];

if (result.success) {
  switch (result.data.deliveryStatus) {
    case CourierDeliveryStatus.DELIVERED:
      console.log('배송 완료');
      break;
    case CourierDeliveryStatus.OUT_FOR_DELIVERY:
      console.log('배송 출발 — 곧 도착합니다');
      break;
    case CourierDeliveryStatus.IN_TRANSIT:
      console.log('이동 중');
      break;
    default:
      console.log(result.data.deliveryStatusText);
  }
}

지원되는 상태 코드:

• PENDING — 접수 대기
• REGISTERED — 접수 완료
• PICKED_UP — 집하 완료
• IN_TRANSIT — 배송 중 (간선 이동)
• OUT_FOR_DELIVERY — 배송 출발
• DELIVERED — 배송 완료
• FAILED / RETURNED / CANCELLED — 실패·반송·취소

7. 지원 택배사 목록 조회

택배사 코드가 필요할 때 직접 조회할 수 있습니다.

const { couriers } = await client.tracking.getCouriers();

couriers.forEach(courier => {
  console.log(`${courier.displayName}: ${courier.trackingApiCode}`);
});
// CJ대한통운: cj
// 롯데택배: lotte
// 한진택배: hanjin
// ...

8. 에러 처리

인증 실패, 요청 한도 초과 등 전체 요청이 실패하는 경우 ApiError가 throw됩니다. 건별 실패는 result.error.code로 확인합니다.

import { ApiError } from 'deliveryapi';

try {
  const { results } = await client.tracking.trace({
    items: [{ courierCode: 'cj', trackingNumber: '1234567890' }],
  });
} catch (err) {
  if (err instanceof ApiError) {
    switch (err.code) {
      case 'UNAUTHORIZED':
        console.error('API 키를 확인하세요');
        break;
      case 'RATE_LIMITED':
        console.error('요청 한도 초과 — 잠시 후 재시도하세요');
        break;
      default:
        console.error(`API 오류: ${err.message}`);
    }
  }
}

9. Express 서버 연동 예시

API 프록시 서버를 만들어 프론트엔드에 노출할 수 있습니다. Secret Key는 서버에만 존재합니다.

import express from 'express';
import { DeliveryAPIClient } from 'deliveryapi';

const app = express();
const client = new DeliveryAPIClient({
  apiKey: process.env.DELIVERY_API_KEY,
  secretKey: process.env.DELIVERY_SECRET_KEY,
});

app.get('/track/:courier/:number', async (req, res) => {
  const { results } = await client.tracking.trace({
    items: [{
      courierCode: req.params.courier,
      trackingNumber: req.params.number,
    }],
  });

  const result = results[0];
  if (!result.success) {
    return res.status(404).json({ error: result.error.code });
  }

  res.json(result.data);
});

다음 단계

• Python SDK 가이드
• 웹훅 구독으로 자동 알림 받기
• 전체 API 문서 보기