택배사별 응답을 하나로 통합하는 방법

택배 조회 기능을 개발할 때 가장 큰 골칫거리는 무엇일까요? 바로 택배사마다 다른 응답 형식입니다. 롯데택배, CJ대한통운, 한진택배, 우체국... 각 택배사가 제공하는 데이터 구조가 모두 다릅니다.

문제: 택배사마다 다른 응답 형식

예를 들어 동일한 "배송 완료" 상태를 각 택배사는 이렇게 다르게 표현합니다:

택배사	원본 상태 텍스트	날짜 형식
롯데택배	인수자등록	2026-01-02 14:30:00
CJ대한통운	배달완료	2026.01.02 14:30
한진택배	배송완료	2026-01-02 14:30
로젠택배	인수확인	2026.01.02 14:30

만약 직접 구현한다면 택배사별로 별도의 파싱 로직을 작성해야 합니다:

// 😱 택배사별 다른 처리 로직이 필요
if (courier === 'lotte') {
  status = response.deliveryStatusText === '인수자등록' ? 'delivered' : 'in_transit';
} else if (courier === 'cj') {
  status = response.statusName === '배달완료' ? 'delivered' : 'in_transit';
} else if (courier === 'hanjin') {
  status = response.stateDesc === '배송완료' ? 'delivered' : 'in_transit';
}
// ... 택배사 추가될 때마다 if문 추가 😵

해결: 통합 응답 타입 (Unified Response)

DeliveryAPI는 모든 택배사의 응답을 하나의 통합된 형식으로 정규화하여 반환합니다. 택배사가 7개든 100개든 클라이언트 코드는 동일합니다.

통합 응답 형식

{
  "trackingNumber": "123456789012",
  "courierCode": "lotte",           // 택배사 코드
  "courierName": "롯데택배",          // 택배사 이름
  "deliveryStatus": "DELIVERED",    // 정규화된 상태 코드
  "deliveryStatusText": "배송완료",   // 표시용 텍스트
  "isDelivered": true,              // 배송 완료 여부
  "senderName": "김**",
  "receiverName": "홍**",
  "productName": "애플망고 3kg",
  "dateLastProgress": "2026-01-02 14:30:00",
  "progresses": [
    {
      "dateTime": "2026-01-02 14:30:00",
      "location": "서울 강남구",
      "status": "배송완료",
      "statusCode": "DELIVERED"
    }
  ],
  "queriedAt": "2026-01-02T14:35:00.000Z"
}

정규화된 배송 상태 코드

7개 택배사의 다양한 상태 표현이 12개의 정규화된 코드로 통일됩니다:

상태 코드	의미	isDelivered
PENDING	접수 대기	false
REGISTERED	접수 완료	false
PICKED_UP	집하 완료	false
IN_TRANSIT	배송중	false
OUT_FOR_DELIVERY	배송 출발	false
DELIVERED	배송 완료	true

실제 코드 비교

Before: 택배사별 분기 처리

// 😱 유지보수 지옥
function getDeliveryStatus(courier, response) {
  switch(courier) {
    case 'lotte':
      return parseLotteResponse(response);
    case 'cj':
      return parseCJResponse(response);
    case 'hanjin':
      return parseHanjinResponse(response);
    case 'post':
      return parsePostResponse(response);
    // ... 택배사 추가될 때마다 case 추가
  }
}

function parseLotteResponse(res) {
  // 롯데택배 전용 파싱 로직 100줄...
}

function parseCJResponse(res) {
  // CJ대한통운 전용 파싱 로직 100줄...
}

After: 통합 인터페이스

// ✅ 깔끔하고 일관된 코드
async function trackDelivery(courierCode, trackingNumber) {
  const response = await fetch(API_URL, {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      items: [{ courierCode, trackingNumber }]
    })
  });

  const data = await response.json();
  const result = data.data.results[0].data;

  // 🎉 택배사 상관없이 동일한 필드 사용
  console.log(`상태: ${result.deliveryStatusText}`);
  console.log(`완료 여부: ${result.isDelivered}`);
  console.log(`마지막 위치: ${result.progresses[0].location}`);

  return result;
}

// 롯데든 CJ든 한진이든 동일한 코드!
trackDelivery('lotte', '123456789012');
trackDelivery('cj', '987654321098');
trackDelivery('hanjin', '555555555555');

지원 택배사

현재 7개 택배사를 지원하며, 모두 동일한 응답 형식으로 반환됩니다:

택배사	코드	지원 기능
롯데택배	lotte	조회 등록
CJ대한통운	cj	조회 등록
한진택배	hanjin	조회
우체국택배	post	조회
경동택배	kyungdong	조회
대신택배	daesin	조회
로젠택배	logen	조회

핵심 요약

다음 단계

• API 문서 - 택배 조회
• 택배 API 5분 만에 연동하기
• 실제 택배조회 체험하기