택배 API 개발 용어 사전

택배 API란?

택배사의 배송 조회, 등록, 추적 기능을 프로그래밍 방식으로 사용할 수 있게 제공하는 인터페이스입니다.

• 여러 택배사(CJ대한통운, 롯데택배, 한진택배 등)를 하나의 API로 통합하여 연동 복잡도를 줄여줍니다.
• 직접 각 택배사 사이트를 크롤링할 필요 없이 표준화된 응답을 받을 수 있습니다.
• 택배사별로 다른 데이터 형식을 하나로 통일해주기 때문에, 택배사가 추가되더라도 코드 변경이 최소화됩니다.

활용 사례: 쇼핑몰 배송 추적 페이지, 물류 관리 시스템(WMS), 배송 알림 서비스, 고객 CS 자동화

웹훅이란?

특정 이벤트가 발생했을 때 서버가 지정된 URL로 HTTP POST 요청을 자동으로 전송하는 방식입니다.

• 택배 API에서는 배송 상태가 변경될 때마다 고객의 서버로 알림을 보냅니다.
• Polling(주기적 조회) 대비 장점: 실시간성, API 호출 횟수 절감, 서버 부하 감소
• 웹훅을 사용하면 불필요한 API 호출 없이도 배송 상태 변경을 즉시 감지할 수 있습니다.

REST API란?

Representational State Transfer의 약자로, 웹에서 데이터를 주고받는 가장 널리 사용되는 아키텍처 스타일입니다.

• HTTP 메서드(GET, POST, PUT, DELETE)로 리소스를 조작합니다.
• 택배 API는 REST API로 설계되어 있어 어떤 프로그래밍 언어에서든 HTTP 요청만 보낼 수 있으면 연동이 가능합니다.
• 주요 특징: 무상태(Stateless), URL 기반 리소스 식별, JSON 응답

예를 들어 송장번호 1234567890의 배송 상태를 조회하려면 POST /v1/tracking/trace에 택배사 코드와 송장번호를 JSON body로 전송합니다.

JSON이란?

데이터를 키-값 쌍으로 표현하는 경량 데이터 교환 형식입니다.

• 택배 API의 요청과 응답 모두 JSON 형식을 사용합니다.
• 사람이 읽기 쉽고, 거의 모든 프로그래밍 언어에서 파싱이 가능합니다.
• XML에 비해 가볍고 간결하여 API 통신의 표준 포맷으로 자리 잡았습니다.

택배 조회 API 응답 예시:

{
  "isSuccess": true,
  "data": {
    "results": [
      {
        "success": true,
        "data": {
          "courierCode": "cj",
          "courierName": "CJ대한통운",
          "trackingNumber": "1234567890",
          "deliveryStatus": "IN_TRANSIT",
          "deliveryStatusText": "배송중",
          "isDelivered": false,
          "progresses": [
            {
              "dateTime": "2025-03-12T14:00:00+09:00",
              "status": "집하",
              "statusCode": "PICKED_UP",
              "location": "서울 강남 집화처리",
              "description": "집하 완료"
            }
          ],
          "dateLastProgress": "2025-03-12T14:00:00+09:00",
          "queriedAt": "2025-03-13T10:30:00+09:00"
        }
      }
    ],
    "summary": { "total": 1, "successful": 1, "failed": 0, "billable": 1 }
  }
}

송장번호란?

택배사가 각 배송 건에 부여하는 고유 식별 번호입니다.

• 택배사마다 형식이 다릅니다. (예: CJ대한통운 10~12자리, 롯데택배 12자리, 우체국 13자리)
• 택배 조회 API에서는 송장번호 + 택배사 코드를 함께 전달하여 배송 상태를 조회합니다.
• 운송장번호, 배송번호, 트래킹번호 등으로도 불립니다.

API Key란?

API 사용자를 식별하고 인증하는 고유 키입니다.

• 택배 API에서는 Public Key(pk_)와 Secret Key(sk_)가 쌍으로 발급됩니다.
• Authorization 헤더에 Bearer pk_xxx:sk_xxx 형태로 전달합니다.
• API Key를 통해 사용량 추적, 요금 과금, 접근 권한 관리가 이루어집니다.